BMC Remedy Action Request System 9.0 en

BMC Software Confidential
BMC Remedy Action Request

System 9.0
Home
Date:
22-Apr-2015 02:39
URL:
https://docs.bmc.com/docs/display/ars9000/Home
Home
Contents
What's new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Featured content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Where to start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Release notes and notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related topics: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Known and corrected issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9.0.00 enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System enhancements in version 9.0.00 . . . . . . . . . . . .
BMC Remedy Migrator enhancements in version 9.0.00 . . . . . . . . . . . . . . .
Locating white papers, guides, and technical bulletins . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System online documentation . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Encryption online documentation . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Migrator online documentation . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy IT Service Management Preconfigured Stack online
documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
White papers online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
30
31
32
33
33
44
45
54
55
55
60
61
61
61
Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
About BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Key concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Product overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
License overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Access control overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Application development overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
User goals and features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
User roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Available BMC Remedy AR System features and configurations . . . . . . . . . .
Features you can install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuration Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation and upgrade paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Planning to upgrade BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Action Request System 9.0
163
164
164
167
168
169
Page 2 of 4705
Home
Planning a server group installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Planning BMC Remedy AR System installation in an enterprise environment
180
BSM environment recommendations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
BSM Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Mainframe integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
BSM Reference Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Deployment architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Email deployment use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Performance benchmarks and tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
BMC Remedy ITSM Suite 9.0 Solution Performance Benchmarks . . . . . . 335
System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370
Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
Server operating system platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Unicode requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
Portmapper service introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
BMC Remedy Migrator memory usage and disk space requirements . . . . 386
Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Security architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Security considerations for BMC Remedy AR System . . . . . . . . . . . . . . . . 388
General security guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
BMC Remedy Encryption Security options . . . . . . . . . . . . . . . . . . . . . . . . 397
Security policy impact on client-server communication . . . . . . . . . . . . . . . 398
BMC Remedy Encryption Security compatibility . . . . . . . . . . . . . . . . . . . . 399
BMC Remedy Encryption Security modifications to the JRE . . . . . . . . . . . 399
Standard security modifications to the IBM JDK . . . . . . . . . . . . . . . . . . . . 400
Single sign-on authentication systems integration . . . . . . . . . . . . . . . . . . . 400
BMC Remedy security certification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422
Language information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Supported languages and character encodings . . . . . . . . . . . . . . . . . . . . . 442
Localized forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Installing BMC Remedy AR System in an international environment: Oracle on
UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
BMC Remedy Email Engine internationalization support . . . . . . . . . . . . . . 446
Page 3 of 4705
Home
BMC Remedy AR System standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

BMC Remedy AR System server standards . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Mid Tier standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Post-installation or post-upgrade considerations . . . . . . . . . . . . . . . . . . . .
Supported operating systems for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported databases for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported database clients for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tested web servers for IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
IPv6 considerations with BMC Remedy AR System . . . . . . . . . . . . . . . . .
446
446
446
447
448
448
448
448
449
449
Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450
About BMC Remedy ITSM Suite 9.0 Deployment online documentation . . . . 450
Configuring after installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging on to the system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with BMC Remedy AR System licenses . . . . . . . . . . . . . . . . . . . . . .
Adding or removing licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exporting or importing licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying and Tracking server group license usage . . . . . . . . . . . . . . . . .
Reviewing license usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Generating a license usage report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Licensing for server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring AR System servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring clients for AR System servers . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring firewalls with AR System servers . . . . . . . . . . . . . . . . . . . . . .
Running a stand-alone AR System server on Windows . . . . . . . . . . . . . . .
Configuring a server for alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the AR System server for external authentication . . . . . . . . .
Configuring a server to use plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting version control options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting timeout options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting a connection to the BMC Atrium SSO server . . . . . . . . . . . . . . . . .
Setting a connection to the BMC Atrium Web Services Registry . . . . . . . .
Setting platform options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting log files options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting server logging options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
452
453
453
454
454
456
458
461
463
465
465
467
468
469
469
470
472
473
474
475
476
476
477
481
Page 4 of 4705
Home
Setting ports and RPC numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482

Setting database options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Setting currency types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487
Setting license options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
Setting external authentication options . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Setting performance and security options . . . . . . . . . . . . . . . . . . . . . . . . . 492
Setting server passwords, RPC options, and plug-in timeouts . . . . . . . . . 495
Setting administrative options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Monitoring service operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Defining queues and configuring threads . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Changing a server name when using a duplicated or migrated environment .
507
Setting security restrictions on file uploads . . . . . . . . . . . . . . . . . . . . . . . . 522
Setting server statistics options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Renaming the AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Configuring server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Configuring the server group check interval . . . . . . . . . . . . . . . . . . . . . . . . 545
Setting failover rankings for servers and operations . . . . . . . . . . . . . . . . . 546
Configuring the server group signaling option . . . . . . . . . . . . . . . . . . . . . . 548
Configuring full text search for a server group . . . . . . . . . . . . . . . . . . . . . . 550
Configuring DSO for a server group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Configuring the Email Engine for a server group . . . . . . . . . . . . . . . . . . . . 554
Configuring flashboards for server groups . . . . . . . . . . . . . . . . . . . . . . . . . 554
Bypassing the load balancer to work on a specific server . . . . . . . . . . . . . 555
Using data archiving with server groups . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Configuring logging for server groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
Removing a server from a server group or remove an unused server name . .
557
Sharing a database without using a server group . . . . . . . . . . . . . . . . . . . 557
Configuring java plug-in servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Creating Java plug-in sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Setting global plug-in server options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Setting plug-in server options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
Working with Java plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Working with Java plug-in sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Page 5 of 4705
Home
BMC Remedy AR System cache management . . . . . . . . . . . . . . . . . . . . . . .

Configuring the server cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Guidelines for resolving cache memory issues . . . . . . . . . . . . . . . . . . . . .
Setting the distributed mapping cache refresh interval . . . . . . . . . . . . . . .
Actions that trigger cache events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mid Tier cache configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Actions in ITSM 7.0.00 applications that trigger caching . . . . . . . . . . . . . .
BMC Remedy Mid Tier configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring BMC Remedy Mid Tier as a shared service . . . . . . . . . . . . . .
Onboarding a new tenant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Offboarding a tenant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the mid tier through a firewall . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring mid tier memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing the Mid Tier Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Change Password page . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Overview page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the General Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting pagination properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the AR Server Settings page . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Cache Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Report Settings page . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Web Service Settings page . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Connection Settings page . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring a mid tier to launch a browser in a different mid tier . . . . . . . .
Cookies used by BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . .
Settings in the config.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up a cluster with multiple tenants . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring a hardware load balancer with BMC Remedy AR System . . . . . .
What a load balancer does . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How load balancers route requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Considerations for configuring load balancers with AR System servers . .
Using a load balancer with server groups . . . . . . . . . . . . . . . . . . . . . . . . .
Load balancer configuration examples . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample load-balancer- Cisco 11500 Series Content Services Switch . . . .
Special considerations and known issues . . . . . . . . . . . . . . . . . . . . . . . . .
Load balancing with Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
568
569
575
579
579
582
593
594
595
617
624
626
627
629
630
631
632
635
637
640
658
660
661
663
665
666
683
685
686
687
688
688
690
695
696
701
Page 6 of 4705
Home
f5 load balancer sample configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702

Configuring a Unicode server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Running your Unicode server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
How BMC Remedy AR System works with Unicode . . . . . . . . . . . . . . . . . 708
Specifying a character set for data import to a Unicode AR System server . . .
712
Filter and escalation workflow considerations . . . . . . . . . . . . . . . . . . . . . . 713
BMC Remedy SNMP Agent configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
SNMP introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
SNMP access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
Monitoring BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Sending traps to clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
SNMP configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
arsnmpd configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
snmpd configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
armonitor configuration file purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Starting the SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Stopping the SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
SNMP Configuration form in the AR System Administration Console . . . . 727
Configuring BMC Remedy Distributed Server Option . . . . . . . . . . . . . . . . . . . 729
Setting up DSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Enabling DSO on an AR System server . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
Configuring a password for the DSO user . . . . . . . . . . . . . . . . . . . . . . . . . 732
Assigning an RPC program number to DSO . . . . . . . . . . . . . . . . . . . . . . . 733
Configuring remote AR System servers for DSO . . . . . . . . . . . . . . . . . . . . 734
Configuring DSO for firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Specifying a DSO host name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737
Configuring the RPC timeout setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
DSO for load balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 738
AR System Administration - Server Information form - DSO tab . . . . . . . . 738
Configuring full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
FTS tab configuration options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741
High-availability architecture for FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743
FTS Configuration form in the AR System Administration Console . . . . . . 746
Creating index files in a different directory from the default . . . . . . . . . . . . 749
Scheduling scans for updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Page 7 of 4705
Home
Configuring the Ignore Words List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Displaying FTS weight in a results list . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Providing a shortcut for specifying expanded FTS qualifications . . . . . . . .
Configuring FTS for localization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Advanced FTS configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding FTS licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Upgrading with FTS installed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying the config.properties file for limiting report entries . . . . . . . . . . .
Limiting entries using a published report . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring web and BMC Remedy AR System reports . . . . . . . . . . . . . .
Using Crystal reports with BMC Remedy AR System . . . . . . . . . . . . . . . .
Managing localized Crystal and Web reports . . . . . . . . . . . . . . . . . . . . . . .
Configuring the BMC Remedy Approval Server . . . . . . . . . . . . . . . . . . . . . . .
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with the AP-Administration form . . . . . . . . . . . . . . . . . . . . . . . . . .
Process administrator overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring process administrator capabilities . . . . . . . . . . . . . . . . . . . . . .
Configuring Approval Server to work with flowcharts . . . . . . . . . . . . . . . . .
Configuring BMC Remedy Approval Server with a separate plug-in server
instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and stopping the Approval Server . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring BMC Remedy Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring outgoing mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performance and configuration settings for Email Engine . . . . . . . . . . . . .
BMC Remedy Email Engine mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving outgoing notifications in MAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the default time interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing your mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring incoming mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Stopping and starting the Email Engine . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying the Email Engine component . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying the companionservername or RMIPort properties . . . . . . . . . . .
Configuring BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up flashboard update intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting or stopping the Flashboards server manually . . . . . . . . . . . . . . . .
750
751
751
752
753
755
755
756
756
757
758
775
784
788
788
788
789
790
791
792
794
795
796
799
810
811
811
811
813
817
819
819
819
820
821
Page 8 of 4705
Home
Setting up a headless environment with Tomcat to display flashboards . . 822

Configuring the display properties for a flashboard . . . . . . . . . . . . . . . . . . 822
Modifying the config.properties file for flashboards . . . . . . . . . . . . . . . . . . 828
Multiple Flashboards servers and AR System servers . . . . . . . . . . . . . . . . 829
Configuring BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830
Removing an AR System server and its BMC Remedy Migrator license from
view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831
Adding AR System server into server account . . . . . . . . . . . . . . . . . . . . . . 831
Adding a licensed AR System server in BMC Remedy Migrator . . . . . . . . 833
Adding or transferring BMC Remedy Migrator license to an AR System server
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
Starting BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
Setting-up BMC Remedy Migrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 834
Configuring the Assignment Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 835
Configuring Assignment Engine properties . . . . . . . . . . . . . . . . . . . . . . . . 835
Stopping and starting the Assignment Engine . . . . . . . . . . . . . . . . . . . . . . 836
Securing BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
Configuring SSL for the email engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837
Resetting the Application Service password . . . . . . . . . . . . . . . . . . . . . . . 841
Securing incoming and outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . 842
Configuring BMC Remedy Encryption Security . . . . . . . . . . . . . . . . . . . . . . . . 846
Configuring the data key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 848
Configuring the public key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849
Activating encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 851
Deactivating encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
Activating FIPS compliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852
Using Oracle CLOBs with BMC Remedy AR System . . . . . . . . . . . . . . . . . . . 854
About Oracle LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854
Storage size impact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 855
Performance impact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
Converting LOB storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858
Monitoring API calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862
To monitor API calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
To view API call details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863
Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867
About BMC Remedy ITSM Suite 9.0 Deployment online documentation . . . . 867
Page 9 of 4705
Home
Integrating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Where to integrate BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . .
Multiplatform issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing an implementation method . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Integration technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AR System plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Plug-in types supported by BMC Remedy AR System . . . . . . . . . . . . . . .
AR Filter API plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AREA plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ARDBC plug-ins introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installed plug-in components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating C plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C plug-in naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the Java plug-in server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Java plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the AR System server to access a plug-in server . . . . . . . . . .
Running the plug-in server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common plug-in C functions and Java methods . . . . . . . . . . . . . . . . . . . .
Opening Knowledge Management System Configuration form . . . . . . . . .
Integrating with a directory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LDAP plug-ins in BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . . .
Using the ARDBC LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring the ARDBC LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building BMC Remedy AR System forms for directory services . . . . . . . .
Using the AREA LDAP plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ARDBC LDAP example - Accessing inetorgperson data . . . . . . . . . . . . . .
AR System external authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling AREA authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring authentication processing . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the AREA hub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling FIPS support for BMC Atrium SSO . . . . . . . . . . . . . . . . . . . . . . .
Data and database integrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating vendor forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
869
870
870
872
872
873
875
875
876
878
902
906
927
928
929
929
935
938
939
942
943
944
944
945
945
948
954
960
966
966
967
974
975
976
976
978
Page 10 of 4705
Home
SQL database access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 986

ODBC database access introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988
Extending BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . 1000
Creating plug-ins to extend BMC Remedy Developer Studio . . . . . . . . . 1001
Prerequisites for creating plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003
Extension points for BMC Remedy Developer Studio . . . . . . . . . . . . . . . 1003
Developer Studio Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
Installation directory for the BMC Remedy Developer Studio plug-ins . . 1004
BMC Atrium Orchestrator integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1004
Defining BMC Atrium Orchestrator web services . . . . . . . . . . . . . . . . . . . 1006
Modifying entries in the AR System Orchestrator Configuration form . . . 1007
BMC Remedy AR System workflow for BMC Atrium Orchestrator integration .
1008
Obtaining job status for asynchronous execution operations . . . . . . . . . . 1011
Atrium Integrator adapter for BMC Remedy AR System . . . . . . . . . . . . . . . . 1012
Data integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1012
AR System permissions scheme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
ETL in the Atrium Integrator adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1014
Input, output and file input steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017
AR Connection module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1029
Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1031
BMC Remedy AR System forms for data management . . . . . . . . . . . . . . 1042
Atrium Integrator Spoon client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065
Scheduling and manually executing a transformation or job . . . . . . . . . . 1066
Running external processes with the Run Process action . . . . . . . . . . . . . . 1067
Running external processes introduction . . . . . . . . . . . . . . . . . . . . . . . . . 1067
Triggering Run Process on clients and servers . . . . . . . . . . . . . . . . . . . . 1067
Starting applications with the Run Process action . . . . . . . . . . . . . . . . . . 1068
Retrieving data from applications with Run Process . . . . . . . . . . . . . . . . 1072
Using Run Process for the web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1075
Integrating the BMC Remedy Assignment Engine into an application . . . . . 1076
To integrate the BMC Remedy Assignment Engine with your application 1076
Preparing for the auto-assignment process . . . . . . . . . . . . . . . . . . . . . . . 1077
Adding fields to the assignee and request forms . . . . . . . . . . . . . . . . . . . 1077
Adding assignee and request forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1078
Page 11 of 4705
Home
Adding assignment rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting sequencing for rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding and executing assignment processes . . . . . . . . . . . . . . . . . . . . .
Using DSO with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up DSO to use CMDB data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Join forms and BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Writing to the CMDB production dataset . . . . . . . . . . . . . . . . . . . . . . . . .
Examples of using DSO to replicate CMDB data . . . . . . . . . . . . . . . . . . .
Recommendations for using DSO with BMC Atrium CMDB . . . . . . . . . .
Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1082
1083
1083
1084
1085
1086
1087
1087
1089
1090
Using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigating the BMC Remedy AR System interface . . . . . . . . . . . . . . . . . . .
Using the AR System Object List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Opening Approval Central . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copying field information to a new request . . . . . . . . . . . . . . . . . . . . . . .
Running and saving searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding a request by example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running a saved, recent, or defined search . . . . . . . . . . . . . . . . . . . . . .
Loading search criteria without execution . . . . . . . . . . . . . . . . . . . . . . . .
Saving searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing saved searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the advanced search bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reporting on BMC Remedy AR System data . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System Report Console . . . . . . . . . . . . . . . . . . . . . . .
Report designer screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Report types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running reports in the Report Console . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing and deleting reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Publishing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving or exporting BMC Remedy AR System reports . . . . . . . . . . . . . .
Using a BIRT editor to create or modify web reports . . . . . . . . . . . . . . . .
Approving requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1092
1092
1092
1114
1115
1116
1116
1119
1120
1120
1121
1121
1122
1122
1131
1132
1133
1134
1134
1144
1158
1158
1160
1161
1163
1188
Page 12 of 4705
Home
Approval notification through email . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Configuring the Request ID link on Approval Central . . . . . . . . . . . . . . . .
Setting previews for approval requests . . . . . . . . . . . . . . . . . . . . . . . . . .
Processing approval requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Get Agreement sample application . . . . . . . . . . . . . . . . . . . . .
Using BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sorting flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Refreshing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying tooltips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Manipulating BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . .
Drilling down to information in a flashboard . . . . . . . . . . . . . . . . . . . . . . .
1188
1193
1194
1194
1211
1218
1218
1218
1221
1222
1222
1223
Administering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1224
Navigating the BMC Remedy AR System Administration console interface . 1225
Opening the AR System Administration Console . . . . . . . . . . . . . . . . . . . 1225
AR System Administration Console introduction . . . . . . . . . . . . . . . . . . . 1225
System category . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1226
BMC Remedy AR System configuration files . . . . . . . . . . . . . . . . . . . . . . . . 1228
ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1229
ar.cfg or ar.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1230
ardb.cfg or ardb.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292
armonitor.cfg or armonitor.conf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1296
AR System server components and external utilities . . . . . . . . . . . . . . . . . . 1297
AR System server components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1298
External utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1306
Centralized configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1313
Backing up and restoring centralized configuration settings . . . . . . . . . . 1314
Centralized configuration system forms . . . . . . . . . . . . . . . . . . . . . . . . . . 1315
Configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316
Notifications about changes to centralized configuration settings . . . . . . 1363
Updating configuration settings by using the AR System Configuration Generic
UI form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1363
Service failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365
Monitor service failover . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1366
Service provider states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1367
Service failover ranking entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1369
Page 13 of 4705
Home
Changing the ranking of a service provider . . . . . . . . . . . . . . . . . . . . . . .

Naming conventions for service names . . . . . . . . . . . . . . . . . . . . . . . . . .
Email engine service failover in a server group . . . . . . . . . . . . . . . . . . . .
Security administration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating users, groups, and roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Access control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up an authentication alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Restrictions when logging in to a BMC Remedy AR System server . . . .
Defining your user base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding database security issues . . . . . . . . . . . . . . . . . . . . . . . . .
Using audit records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting user preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing preference forms for centralized preferences . . . . . . . . . . . . .
Restricting preferences from users . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring clients to use a preference server . . . . . . . . . . . . . . . . . . . . .
Establishing a mandatory preference server . . . . . . . . . . . . . . . . . . . . . .
Behaviors associated with preference server configuration . . . . . . . . . . .
Setting the AR System User Preference form . . . . . . . . . . . . . . . . . . . . .
Setting user preferences in the BMC Remedy Mid Tier . . . . . . . . . . . . . .
Defining business schedules using Business Time . . . . . . . . . . . . . . . . . . . .
Business Time introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scheduling a time segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using time zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Business Time 2.0 commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the old Business Time forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Migrating Workdays and Holidays to the Business Time Segment form .
Enabling alert notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Alert system architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Alert Events form introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting unread alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering users for alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the alert list in a browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Web services with alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning requests with the Assignment Engine . . . . . . . . . . . . . . . . . . . . . .
Auto-assignment methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1369
1370
1370
1372
1373
1398
1444
1447
1448
1454
1456
1459
1459
1460
1460
1460
1461
1462
1484
1485
1485
1488
1495
1500
1509
1517
1518
1518
1519
1520
1520
1520
1522
1523
1526
1527
Page 14 of 4705
Home
Assignment process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Assignment Engine Administration Console introduction . . . . . . . . . . . . .
Configuring a private queue for the Assignment Engine . . . . . . . . . . . . .
Assignment Engine forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To enable FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up FTS to search across multiple forms . . . . . . . . . . . . . . . . . . .
Re-indexing considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining a field for FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How FTS indexing works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performing searches with FTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FTS index migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling FTS high availability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling BMC Remedy AR System through email . . . . . . . . . . . . . . . . . .
BMC Remedy Email Engine terminology . . . . . . . . . . . . . . . . . . . . . . . . .
How BMC Remedy Email Engine works . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up incoming email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up UNIX mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and using email templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Email Engine forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the approval process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Approval Server concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining an approval process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining approval rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Lunch Scheduler sample application . . . . . . . . . . . . . . . . . . . .
Worksheets for setting up processes and rules . . . . . . . . . . . . . . . . . . . .
Approval forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running the approval utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up DSO to synchronize data across multiple AR System servers . .
Distributed operations introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distributed operations components . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implementing DSO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distributed operations scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chained and broadcast distributed transfers . . . . . . . . . . . . . . . . . . . . . .
Distributed Server Administration program . . . . . . . . . . . . . . . . . . . . . . .
1528
1528
1529
1529
1530
1531
1531
1539
1541
1545
1549
1558
1560
1562
1563
1563
1568
1614
1646
1648
1689
1707
1707
1736
1745
1778
1785
1797
1866
1868
1869
1875
1881
1906
1914
1925
Page 15 of 4705
Home
Managing request IDs in distributed environments . . . . . . . . . . . . . . . . .

Overwriting all fields in duplicate requests . . . . . . . . . . . . . . . . . . . . . . . .
Capturing server events for workflow or API calls . . . . . . . . . . . . . . . . . . . . .
Understanding the Server Events form . . . . . . . . . . . . . . . . . . . . . . . . . .
How the Server Events form is created . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of events you can record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing the server changes you recorded . . . . . . . . . . . . . . . . . . . . . . . .
Using server events in workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Auditing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Archiving data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File types used in migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing data into BMC Remedy AR System forms . . . . . . . . . . . . . . . .
Importing and exporting Flashboards objects . . . . . . . . . . . . . . . . . . . . .
Exporting and importing data and definitions . . . . . . . . . . . . . . . . . . . . . .
Using the Request ID to improve performance or security . . . . . . . . . . . .
Understanding the AR System database . . . . . . . . . . . . . . . . . . . . . . . . .
SQL definitions of the data dictionary tables . . . . . . . . . . . . . . . . . . . . . .
Migrating applications and data between AR System servers . . . . . . . . . . .
Migration overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigating the BMC Remedy Migrator interface . . . . . . . . . . . . . . . . . . .
Setting BMC Remedy Migrator options . . . . . . . . . . . . . . . . . . . . . . . . . .
Performing migrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with migration scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using migration reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling social collaboration in BMC Remedy AR System . . . . . . . . . . . . . .
Receiving alerts through Twitter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring RSS feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring chat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying a BMC Remedy AR System form in a portlet . . . . . . . . . . . . . . .
Required knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tested platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Portlet structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Authentication solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1928
1929
1930
1930
1931
1931
1932
1947
1948
1948
1965
1987
1989
2000
2001
2026
2039
2071
2071
2072
2082
2115
2139
2186
2197
2221
2221
2225
2230
2251
2251
2251
2252
2253
2254
2256
Page 16 of 4705
Home
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2257

Developing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application development with BMC Remedy Developer Studio . . . . . . . . . .
Determining what your application needs to track . . . . . . . . . . . . . . . . . .
Determining what to track . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Determining how your application should work . . . . . . . . . . . . . . . . . . . .
Designing effective and more usable applications . . . . . . . . . . . . . . . . . .
Designing the user interface effectively . . . . . . . . . . . . . . . . . . . . . . . . . .
Resources for product design and usability . . . . . . . . . . . . . . . . . . . . . . .
Providing accessibility for users with disabilities . . . . . . . . . . . . . . . . . . .
About the Sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Navigating the BMC Remedy Developer Studio interface . . . . . . . . . . . . . . .
About BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and logging on to BMC Remedy Developer Studio . . . . . . . . . .
Using menu options in BMC Remedy Developer Studio . . . . . . . . . . . . .
Event Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using buttons and menu bar items to execute active links . . . . . . . . . . .
Modifier keywords for use in workflows . . . . . . . . . . . . . . . . . . . . . . . . . .
Understanding the AR System Navigator . . . . . . . . . . . . . . . . . . . . . . . . .
Working with perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with existing objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using associations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using working lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Outline tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Messages tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing from BMC Remedy Developer Studio . . . . . . . . . . . . . . . . . . . . .
Clearing BMC Remedy Developer Studio cache . . . . . . . . . . . . . . . . . . .
Creating reports for selected objects . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Developer Studio frequently asked questions . . . . . . . . . . . . . . . . .
Differences between BMC Remedy Administrator and BMC Remedy
Developer Studio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the development environment . . . . . . . . . . . . . . . . . . . . . . . . . . .
Packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating packing lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2258
2259
2260
2261
2262
2262
2263
2264
2265
2265
2266
2267
2269
2271
2272
2274
2277
2278
2280
2284
2286
2294
2304
2309
2313
2314
2315
2315
2316
2319
2320
2326
2326
2327
Page 17 of 4705
Home
Saving packing lists as XML import or export command files . . . . . . . . .

Working with applications and packing lists . . . . . . . . . . . . . . . . . . . . . . .
Version control in BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . .
Using object reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the object modification log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Development modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining and managing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deployable applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Alternatives for presenting applications to users . . . . . . . . . . . . . . . . . . .
Deleting an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Developing the application interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System installed forms . . . . . . . . . . . . . . . . . . . . . . . .
Using templates to dynamically present HTML content from a form . . . .
Working with panels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and managing fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recommendations while developing applications . . . . . . . . . . . . . . . . . .
Adding graphics to an application with flashboards . . . . . . . . . . . . . . . . . . .
BMC Remedy Flashboards overview . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data flow in flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Types of flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Process for creating a flashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Planning a flashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating flashboard variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and managing flashboards . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a flashboard to a BMC Remedy AR System form . . . . . . . . . . . .
Securing your application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Access control for a deployable application . . . . . . . . . . . . . . . . . . . . . . .
Granting permission to applications and their objects . . . . . . . . . . . . . . .
Defining workflow to automate processes . . . . . . . . . . . . . . . . . . . . . . . . . . .
Introducing workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2329
2329
2331
2334
2336
2343
2351
2351
2351
2373
2375
2376
2377
2407
2414
2420
2451
2516
2539
2544
2651
2654
2654
2655
2656
2663
2663
2664
2668
2675
2690
2690
2690
2691
2692
2692
Page 18 of 4705
Home
Configuring workflow forms and execution options . . . . . . . . . . . . . . . . . 2706

Building qualifications and expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 2719
Specifying workflow actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2775
Workflow processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2893
Workflow extras . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2903
Mid tier application development guidelines . . . . . . . . . . . . . . . . . . . . . . . . . 2916
Managing resource files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2917
URLs for forms and applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2918
Creating login and logout buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2926
Creating customized login pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2928
Using the Object List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2929
Embedding web content in an application through data visualization fields . . .
2930
Browser settings for scripting and ActiveX controls . . . . . . . . . . . . . . . . . 2946
How a view is selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2948
How the locale is established . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2948
Types of browser searches for end users . . . . . . . . . . . . . . . . . . . . . . . . 2948
Setting up the query builder widget for end users . . . . . . . . . . . . . . . . . . 2949
Including parameters in saved or defined searches . . . . . . . . . . . . . . . . . 2951
Creating help for web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2952
Adding approvals to an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2953
Designing an approval application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2954
Integrating Approval Server with an application . . . . . . . . . . . . . . . . . . . . 2954
Adding notifications to the approval process . . . . . . . . . . . . . . . . . . . . . . 2960
Creating notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2961
Enhancing your approval forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2969
Adding previews to your approval application . . . . . . . . . . . . . . . . . . . . . 2972
Using the multi-process preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2974
Using a custom ad hoc dialog box with the approval server . . . . . . . . . . 2974
Calling Approval Server application commands in your application . . . . . 2975
Building performance into applications and workflow . . . . . . . . . . . . . . . . . . 2978
Customizing applications using overlays and custom objects . . . . . . . . . . . . 2981
About origin objects and custom objects . . . . . . . . . . . . . . . . . . . . . . . . . 2982
About overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2984
Creating custom objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2998
Creating overlays to customize objects . . . . . . . . . . . . . . . . . . . . . . . . . . 2999
Page 19 of 4705
Home
Working with overlays and custom objects . . . . . . . . . . . . . . . . . . . . . . .

Hiding unmodified objects in Best Practice Customization mode . . . . . .
Converting custom objects to origin objects . . . . . . . . . . . . . . . . . . . . . . .
Converting origin objects to custom objects . . . . . . . . . . . . . . . . . . . . . . .
About export and import operations on overlays and custom objects . . .
About auditing and archiving overlays and custom objects . . . . . . . . . . .
Comparing and reconciling objects using objects list . . . . . . . . . . . . . . . .
Customizing the interface for multiple consumers . . . . . . . . . . . . . . . . . . . . .
Customizing applications with Cascading Style Sheets . . . . . . . . . . . . . .
Customizing views for forms in browsers . . . . . . . . . . . . . . . . . . . . . . . . .
Defining and managing form views . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing the home page and entry points . . . . . . . . . . . . . . . . . . . . .
Localizing an application to other languages . . . . . . . . . . . . . . . . . . . . . . . .
Localizing BMC Remedy AR System applications . . . . . . . . . . . . . . . . . .
Using the localization toolkit to localize your applications . . . . . . . . . . . .
Making your application accessible - Section 508 compatibility . . . . . . . . . .
What Section 508 support means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting accessibility options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessibility features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Section 508 testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web settings to support Section 508 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
JAWS settings for the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Low Vision users and BMC Remedy AR System clients . . . . . . . . . . . . .
No Vision support for BMC Remedy AR System features . . . . . . . . . . . .
Shortcut keys for BMC Remedy AR System . . . . . . . . . . . . . . . . . . . . . .
Executing active links on the Web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Mid Tier and caching . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Mid Tier and RTL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Form design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Verifying your BMC Remedy AR System forms . . . . . . . . . . . . . . . . . . . .
Section 508 rules for application designers . . . . . . . . . . . . . . . . . . . . . . .
Section 508 rules for others . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Testing and debugging a BMC Remedy AR System application . . . . . . . . .
Application debugging process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Active link debugging example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3009
3027
3028
3030
3031
3032
3035
3039
3040
3054
3060
3097
3121
3122
3141
3166
3167
3168
3168
3169
3169
3171
3174
3174
3188
3190
3190
3190
3190
3193
3194
3201
3202
3202
3205
3205
Page 20 of 4705
Home
The BMC Remedy AR System workflow debugger . . . . . . . . . . . . . . . . .

Using Analyzer to find problems in your applications . . . . . . . . . . . . . . . .
Working with the Analyzer View tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Launching the Analyzer from a command line . . . . . . . . . . . . . . . . . . . . .
Capturing application performance with the Mid-Tier Profiler . . . . . . . . .
HTTP tracing in the mid tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Measuring BMC Remedy AR System application performance . . . . . . . .
Moving to production . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing and exporting object definitions and locking objects . . . . . . . .
BMC Remedy AR System definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exporting and importing definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Distributing an application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locking objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Making applications licensable for integration system vendors . . . . . . . .
Publishing the BMC Remedy AR System functionality as a web service . . .
AR System and web services introduction . . . . . . . . . . . . . . . . . . . . . . . .
Web service standards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined BMC Remedy AR System web services . . . . . . . . . . . . . . . .
Forms and field mappings for web services . . . . . . . . . . . . . . . . . . . . . . .
Basic and custom web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating web service clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting up the environment for web services . . . . . . . . . . . . . . . . . . . . . .
Publishing a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registering a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Consuming a web service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mapping web service data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using join forms in web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web service operation types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Web service scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML editing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supported schema constructs and web service limitations . . . . . . . . . . .
SOAP headers and authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3206
3216
3229
3231
3238
3239
3239
3329
3329
3330
3331
3344
3344
3349
3355
3356
3357
3359
3359
3360
3360
3365
3369
3376
3384
3389
3399
3401
3407
3427
3437
3439
Developing an API program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

API overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
When to use API programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3446
3447
3448
3448
Page 21 of 4705
Home
Understanding JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tools for testing the REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Login information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operations on entry objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
API use cases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Configuring REST API for SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System C API overview . . . . . . . . . . . . . . . . . . . . . . . . . .
Client-server application model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System API library functions . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System C API program structure . . . . . . . . . . . . . . . .
Multithreaded API clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the BMC Remedy AR System API for integration . . . . . . . . . . . . .
BMC Remedy AR System API issues and considerations . . . . . . . . . . . .
BMC Remedy AR System C API installation and compilation requirements
BMC Remedy AR System C API package contents . . . . . . . . . . . . . . . .
Migrating to the current release of BMC Remedy AR System C API . . . .
Compile and link requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Lists and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
High-level object relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Login and session information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Status information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Permissions and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Group information and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structures for ARGetListEntryWithMultiSchemaFields . . . . . . . . . . . . . .
Filters, escalations, and active links and structures . . . . . . . . . . . . . . . . .
Character menus and data structures . . . . . . . . . . . . . . . . . . . . . . . . . . .
Images and data structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Containers and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overlays and structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Server object properties and structures . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing and exporting and structures . . . . . . . . . . . . . . . . . . . . . . . . . .
Freeing allocated memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3449
3452
3453
3455
3474
3477
3480
3480
3481
3482
3483
3484
3486
3486
3486
3495
3498
3501
3502
3502
3503
3504
3506
3508
3510
3511
3531
3546
3561
3562
3562
3569
3569
3573
3576
3577
Page 22 of 4705
Home
BMC Remedy AR System C API functions . . . . . . . . . . . . . . . . . . . . . . . . . .

Types of functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating and executing BMC Remedy AR System C API programs . . . . . .
Program structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performing common tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying fields or keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Executing C API programs in workflow . . . . . . . . . . . . . . . . . . . . . . . . . .
Program design tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multithreaded C API clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Impersonating a user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling client-managed transactions . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending alerts to a filter API plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debugging API programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logging BMC Remedy AR System activity . . . . . . . . . . . . . . . . . . . . . . .
Using the driver program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System plug-in API functions . . . . . . . . . . . . . . . . . . . . . .
AR System plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AREA plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ARDBC plug-in API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AR Filter API plug-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML transformation routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transforming XML and BMC Remedy AR System objects . . . . . . . . . . .
Object API functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the object XML functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object API function descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving entries from multiple forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About ARGetListEntryWithMultiSchemaFields . . . . . . . . . . . . . . . . . . . . .
Dynamic joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recursive queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Value set queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Vendor form joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System Java API overview . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy AR System Java API installed files . . . . . . . . . . . . . . . . . .
Runtime configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3579
3579
3585
3985
3985
3987
3990
3990
3992
3993
3993
3994
3994
3996
3996
3997
3997
4003
4003
4008
4013
4030
4031
4032
4032
4034
4036
4124
4124
4128
4131
4137
4143
4145
4145
4146
Page 23 of 4705
Home
BMC Remedy AR System Java API programming model . . . . . . . . . . . . 4147

Programming with the Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4149
Java API sample code for managing BMC Remedy AR System records 4152
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4157
Troubleshooting BMC Remedy AR System installation, migration, or upgrade . .
4158
Free and available ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4159
Server issues on DB2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4159
BMC Remedy Approval Server installation and upgrade issues . . . . . . . 4159
Locating BMC Remedy AR System files and forms . . . . . . . . . . . . . . . . . 4160
Troubleshooting BMC Remedy Migrator installation . . . . . . . . . . . . . . . . 4168
Installation issues on an Oracle database . . . . . . . . . . . . . . . . . . . . . . . . 4168
Understanding digital signatures for Windows installers . . . . . . . . . . . . . 4168
Gathering information for support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4168
Collecting AR System server information . . . . . . . . . . . . . . . . . . . . . . . . . 4169
Collecting Mid tier information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4169
Collecting BMC Remedy Email Engine information . . . . . . . . . . . . . . . . . 4169
Collecting BMC Remedy Assignment Engine information . . . . . . . . . . . . 4170
Collecting BMC Remedy Approval Server information . . . . . . . . . . . . . . . 4170
Collecting Data Import Tool information . . . . . . . . . . . . . . . . . . . . . . . . . . 4171
Collecting BMC Atrium CMDB information . . . . . . . . . . . . . . . . . . . . . . . . 4171
Collecting diagnostics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4172
Collecting diagnostics in a zip file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4172
Displaying version information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4173
Checking the database tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4174
Creating flashboards to collect server statistics . . . . . . . . . . . . . . . . . . . . 4180
Tracking cache loads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4184
Working with logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4194
BMC Remedy Mid Tier preload logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4195
Using log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4195
Enabling logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4195
Analyzing logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4259
Running the Maintenance Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4300
Logging and monitoring AR System server . . . . . . . . . . . . . . . . . . . . . . . 4302
Additional troubleshooting resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4304
Viewing logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4304
Page 24 of 4705
Home
BMC Remedy AR System Maintenance tool . . . . . . . . . . . . . . . . . . . . . . . . . 4311

Collect and view logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4311
Perform a health check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4311
Encrypt passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4312
Working with error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4312
BMC Remedy Migrator error messages . . . . . . . . . . . . . . . . . . . . . . . . . . 4313
BMC Remedy AR System diagnostic messages . . . . . . . . . . . . . . . . . . . 4332
BMC Remedy AR System error messages . . . . . . . . . . . . . . . . . . . . . . . 4336
Troubleshooting BMC Remedy AR System performance issues . . . . . . . . . 4535
Peak use issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4537
Hardware issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4538
Memory configuration issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4539
Multithreaded server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4539
Checking log files for long-running operations . . . . . . . . . . . . . . . . . . . . . 4541
Troubleshooting server processes on Windows . . . . . . . . . . . . . . . . . . . . . . 4541
Troubleshooting BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4541
Troubleshooting out-of-memory exceptions in the BMC Remedy Mid Tier 4541
Resolving attachment issues in BMC Remedy Mid Tier . . . . . . . . . . . . . 4544
BMC Remedy Mid Tier troubleshooting tips . . . . . . . . . . . . . . . . . . . . . . . 4544
Monitoring mid tier response time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4546
To enable mid tier response time monitoring . . . . . . . . . . . . . . . . . . . . . . 4546
To view overall response time details . . . . . . . . . . . . . . . . . . . . . . . . . . . 4546
Overall response time parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4547
Troubleshooting BMC Remedy Developer Studio issues . . . . . . . . . . . . . . . 4548
Q: When I use a preference server, why are some preferences still stored
locally? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4548
Q: Sometimes, menu commands in the Form, Layout, and Workflow menus
are not available (disabled). How do I make them available? . . . . . . . . . 4548
Q: The tabs in my perspective are not where I want them or I can't find them.
How I do fix the perspective? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4548
Q: When I try to start BMC Remedy Developer Studio, it reports that my
workspace is locked. How can I unlock my workspace? . . . . . . . . . . . . . 4548
Q: Where are all the preferences from the Preferences dialog box of BMC
Remedy Administrator? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4549
Troubleshooting BMC Remedy Flashboards . . . . . . . . . . . . . . . . . . . . . . . . 4550
Troubleshooting BMC Remedy Flashboards displays . . . . . . . . . . . . . . . 4550
Page 25 of 4705
Home
Using the FBImageServlet to test a flashboard . . . . . . . . . . . . . . . . . . . .

Troubleshooting BMC Remedy Email Engine . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting outgoing email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Temporary directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recommendations for avoiding outages . . . . . . . . . . . . . . . . . . . . . . . . .
Fixing common problems with the BMC Remedy Email Engine . . . . . . .
Configuring mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining a heap size for the BMC Remedy Email Engine . . . . . . . . . . . .
Troubleshooting startup issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Determining problems with the mail server . . . . . . . . . . . . . . . . . . . . . . .
Email daemon issues when AR System server stops . . . . . . . . . . . . . . .
Making changes to mailbox configuration . . . . . . . . . . . . . . . . . . . . . . . .
Submitting email requests across different time zones . . . . . . . . . . . . . .
Verifying permissions for the Windows accounts . . . . . . . . . . . . . . . . . . .
Troubleshooting email request processing and notification filters . . . . . .
Fixing issues with notifications that fail . . . . . . . . . . . . . . . . . . . . . . . . . . .
Temporary directories and files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting BMC Remedy Approval Server . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Approval Server configuration file settings . . . . . . . . . . . .
Accessibility issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error 333 and Assignee Group Permission . . . . . . . . . . . . . . . . . . . . . . .
Runtime issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Common error messages for BMC Remedy Approval Server and BMC
Remedy Assignment Engine signaling . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Approval Server files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting BMC Remedy Assignment Engine . . . . . . . . . . . . . . . . . . .
BMC Remedy Assignment Engine files . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting BMC Remedy Distributed Server Option . . . . . . . . . . . . . .
Errors encountered by Distributed Server Option . . . . . . . . . . . . . . . . . .
BMC Remedy Distributed Server Option files . . . . . . . . . . . . . . . . . . . . .
Verifying the Distributed Server Option is in active state . . . . . . . . . . . . .
Missing distributed operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performance issues processing Distributed Server Option operations . .
Troubleshooting full text search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To enable FTS index logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To enable SQL logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4553
4554
4554
4554
4556
4556
4556
4558
4559
4562
4564
4565
4565
4566
4567
4567
4567
4569
4569
4570
4571
4571
4572
4573
4574
4574
4576
4576
4577
4577
4579
4579
4580
4580
4581
Page 26 of 4705
Home
Cannot connect to the Java plug-in server . . . . . . . . . . . . . . . . . . . . . . . .

Troubleshooting plug-in issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General approach for troubleshooting plug-in issues . . . . . . . . . . . . . . . .
Enabling server-side AR System logs . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting issues with plug-in servers . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting issues with ARDBC plug-ins . . . . . . . . . . . . . . . . . . . . .
Troubleshooting issues with AR System Filter API plug-ins . . . . . . . . . . .
Troubleshooting issues with AREA plug-ins . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting encryption security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Java-based encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Related topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting BMC Remedy SNMP Agent . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting issues with BMC Atrium CMDB . . . . . . . . . . . . . . . . . . . . .
Troubleshooting alert activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using alerts in a server group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking the status of alerts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using alert and Web service logs to check alert activity . . . . . . . . . . . . .
Searching the Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
To search the Knowledge Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting issues connecting to the AR System server . . . . . . . . . . . .
Related topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Running arconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Support status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4581
4581
4582
4583
4585
4588
4604
4632
4636
4636
4636
4636
4638
4639
4639
4639
4640
4640
4640
4641
4641
4641
4646
4646
4646
FAQs and additional resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BMC Remedy Mid Tier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
PDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additional resources from BMC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4647
4647
4647
4649
4649
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4650
Page 27 of 4705
Home
This space contains information about the 9.0 release of the BMC Remedy Action Request System
(BMC Remedy AR System), BMC Remedy Encryption Security, and BMC Remedy Migrator
products, including service packs and patches.
The following topics will help you begin:
What's new
Featured content
Where to start
Page 28 of 4705
Home
What's new
Announcement, April 30, 2015
BMC Remedy Action Request System 9.0 is available with the following new features:
Reconciling AR customizations using BMC Remedy Developer Studio
Implementation of RESTful APIs
New AR System Server Object Association
Improved archiving
Enhanced logging features logging configuration, logging restriction, logging
consistency
For the details of all new features, see 9.0.00 enhancements.
BMC will no longer provide support for Workflow debugger.
The following interactive graphic summarizes enhancements for the BMC Remedy Action Request
System 9.0. (The graphic may take a few seconds to load).
Page 29 of 4705
Home
Featured content
For information about the issues in this release, see Known and corrected issues.
To find content in the online documentation that was previously provided in PDF format, see
Locating white papers, guides, and technical bulletins .
To plan for an installation or upgrade, see Planning.
To learn about installing or upgrading BMC Remedy AR System, see BMC Remedy ITSM
9.0 Deployment.
The BMC Remedy User and BMC Remedy Alert clients are no longer installed. For details,
see the End of Life statement (Support login required).
Page 30 of 4705
Home
Where to start
End users: Using
Administrators: Planning, Installing, Upgrading, Configuring after installation, Integrating,
Administering, and Troubleshooting
Developers: Integrating, Developing an application, and Developing an API program
Architects: Architecture
For a description of key user responsibilities, see User goals and features.
PDFs
Help
Recently updated pages
Recently Updated
Upgradingabout an hour ago updated by Prachi Kalyani view change
Installingabout an hour ago updated by Prachi Kalyani view change
Upgrade.pngabout an hour ago attached by Prachi Kalyani
Upgrade.pngabout an hour ago attached by Prachi Kalyani
Clearing BMC Remedy Developer Studio cacheabout an hour ago updated by
Chinmay Gadre view change
Configuring AR System server queue threads for scheduler jobsabout 2 hours ago
commented by Prachi Kalyani
Show More
Page 31 of 4705
Home
Release notes and notices

This section provides information about what is new or changed in this space, including resolved
issues, documentation updates, maintenance releases, service packs, and patches. It also provides
license entitlement information for the release.
Tip
To stay informed of changes to this space, place a watch on this page.
The following updates have been added since the release of the space:
Date
Title
Summary
April 30,
2015
9.0.00
enhancements
BMC Remedy AR System 9.0 has been enhanced with the following new features and
changes:
C API support for associations
RESTful API to simplify integrations between platforms
New restrictions for users and groups
Centralized configuration
Service failover
Changes in the AR System server queue threads configuration
Service operations monitoring
Limiting number of entries in a report
Reconciling AR customizations using BMC Remedy Developer Studio
Associations object
Archiving related forms using associations
Ability to restrict switching between developer studio modes
Ability to add alias for the server name
Mid tier response time monitoring
Clustering support for mid tier
Multitenancy in mid tier
Global archive schedule
Archive Manager console
Enabling skins administration for users
Search result pagination
Enhanced logging features
Support for associations object
Page 32 of 4705
Home
Related topics:
Known and corrected issues
Support information

This section to learn about the issues that are corrected in the 9.0 release along with its
subsequent service packs and patches, and to look for open issues and workarounds to known
problems before contacting Support.
Tips
To search for issues related to a specific component, for example, BMC Remedy
AR System, use the Component drop down.
To search for issues corrected in a specific release, service pack, or patch, use the
Corrected in drop down. An issue with no version number in the Corrected in
column remains open.
To perform a custom search on a specific issue number or description, type the text
in Issue or Description text boxes.
To sort the table, click on the column heading.
To view the table in full-screen mode, press the F key. To exit the full screen mode,
press the Esc key.
Component
Issue
Description
Affected
versions
Corrected
in
Page 33 of 4705
Home
Component
Issue
Description
AR System
server
SW00456852
If you create an overlay and enable archiving for the HPD:Help Desk form,
AR System
server
SW00487963
AR System
server
SW00387679
Affected
versions
Corrected
in
9.0.00
and select the Copy to Archive and Delete from Source option, a blank form
is created. The form does not contain any fields.
The pending entries from the ft_pending table fail to be indexed if you enable
9.0.00
the FTS Indexer.

When the AR System server and the mid tier are integrated with an Atrium
SSO server and if the Cross Reference Blank Password is selected in the
EA Configuration tab on the Server Information form for External
Authentication, the user present in the BMC Remedy AR System server does
not get authenticated internally. This is because, in an Atrium SSO-enabled
environment, the mid tier always connects to the BMC Remedy AR System
server with the user name and authorization string supplied by the Atrium SSO
server.
AR System
server
SW00417387
An email message is sent to all the users registered on the People form (users
belonging to a particular group) under either of the following circumstances:
A user on the People form has an email address such as "00000",
group IDs, or some garbage characters, and an incident is created for
7.1.0,
7.5.00,
7.6.04,
8.1.00,
9.0.00
this user.
The user who is creating a ticket for the customer for whom the incident
is being created replaces the value in the Email address field with
zeros (for example, 000000)
or the group ID and submits the incident.
AR System
server
SW00445408
If you integrate BMC Remedy AR System and BMC Atrium Single Sign-On in
version 8.0.00 and then you upgrade the BMC Remedy AR System server and
BMC Remedy Mid Tier to version 9.0, you break the integration with the SSO
Server.
8.0.01,
8.1.00,
9.0.00
Workaround:
Re-run the version 9.0 SSO integration utilities that are installed with the BMC
Remedy AR System server and BMC Remedy Mid Tier to restore the
integration with the version 8.0.00 SSO Server.
For more information, see:
Running SSOARIntegration utility on the AR System server
Running the SSOMidtierIntegration utility on the Mid Tier
Note: BMC recommends that you upgrade BMC Atrium Single Sign-On
to version 9.0 as well.
AR System
server
SW00467043
In the AR System Job form, when you create a job with Job Type as Report
and select Schedule Information type as Hourly or By Minute,the record is
not created generating the following error:
ARERR [8753] Error in plugin: ARSYS.ARF.REPORTSCHEDULER
Page 34 of 4705
Home
Component
Issue
Description
Affected
versions
AR System
server
SW00467816
In BMC Remedy AR System 9.0, when you create a web service filter action
and specify the username in the format <domainName\username>, the
domainName is removed automatically. The web service filter action fails and
a 401 Unauthorized Error error occurs.
8.1.01,
9.0.00
Corrected
in
Workaround:
Specify the username in the format <domainName\domainName\username>
or <username@FullyQualifiedDomainName>.
For example if the domainName is abc and username is xyz, specify the
username in the format abc\abc\xyz or xyz@abc.com
AR System
server
SW00469288
In BMC Remedy AR System 9.0 on a Windows Operating System with HR (

Croatian) locale, the AR Server converts the dates to dd.mm.yyyy HH:MM:SS
format, but it does not convert the date back to EPOCH format. The following
error occurs: ARERR 313: Incompatible data types for intended
8.1.01,
9.0.00
relational operation.
AR System
server
SW00471581
If you upgrade from BMC Remedy IT Service Management 7.6.04 or an earlier

version to 9.0, there is a potential for view creation failure during the upgrade
resulting in a field count mismatch on forms. These forms are not cached
when you restart the AR Server.
8.1.01,
9.0.00
AR System
server
SW00487626
BMC Atrium Integrator data is not available on the AR System Server Group
Operation Ranking form.
9.0.00
Workaround:
Add the required data manually.
Approval
Server
SW00454927
9.0.00
In Approval Central console, if you enter a justification in Justification for

Action field and then click Approve, the justification is not saved or displayed
on relevant forms. The Add button next to Justification for Action field is not
required.
Developer
Studio
SW00436945
When you upgrade to version 9.0, the existing overlay objects display the
overlay type as No Overlay for the granular sections such as Permissions,
Indexes, Other Definitions, and so forth.
8.0.01,
8.1.00,
9.0.00
Workaround:
Create a new workspace while launching BMC Remedy Developer Studio.
The overlay objects show the overlay type as Overwrite.
Note: The overlay type for Indexes is displayed as Additive.
Page 35 of 4705
Home
Component
Issue
Description
Affected
versions
Developer
Studio
SW00475891
When you create an association between the main form and its audit form and
you have chosen this to follow this association during archiving, all the related
audit entries are also archived with that form. However, after archiving, when
you delete the archived records from the main form, an audit entry gets added
for deletion in the audit form and it is not archived.
9.0.00
Corrected
in
Workaround:
you can choose to archive those entries in your audit form which were created
due to deletion on the form by archive user.
1.
2.
3.
4.
Developer
Studio
SW00482018
Define an archive on your audit form.

Select Appear in Archive Policy check box.
Add the qualification as 'User'='AR_ARCHIVER' & 'Action'='Delete'.
Save the form.
After you perform a drop to drop upgrade for BMC Remedy Developer studio,
the BMC Remedy Developer Studio welcome screen still displays the older
version instead of the upgraded version. You may also not see the new
features after the upgrade or hotfix.
9.0.00
Workaround:
Delete the .eclipse directory for the user directory at the following location: <
windows-users-directory>\users\<username>.
Email
Engine
SW00359899
Because the BMC Remedy Email Engine has an open issue for supporting
LDAP user authentication, the approval notification through the email
7.6.03,
8.0.00,
feature is currently not available for users residing on LDAP directories.
8.1.00,
9.0.00
Mid Tier
SW00471613
In BMC Remedy Mid Tier 9.0, auto-complete results are unavailable if you
type a character string in a field on a form and then press the down arrow key
immediately after you type the last character in the string. Auto-complete
starts but does not finish, and the auto-complete operation is canceled.
9.0.00
Mid Tier
SW00459869
When you create a knowledge article using BMC Remedy Knowledge
8.1.00,
Management 9.0, if you have a bulleted list nested in a numbered list in any
9.0.00
RTF field, the numbered list restarts at 1 instead of incrementing to the next
number.
Mid Tier
SW00464462
When you create a new incident by using the Incident Management Console,
if you select a value from a drop-down list or enter multiple characters in a
character field, the new screen rendition is delayed. This delay happens when
8.1.00,
9.0.00
the chat status in Incident Management Console is Online. If you change the
chat status to Offline, there is no delay in screen rendition.
This issue is observed in Mozilla Firefox 23, Internet Explorer 8 or other
browsers.
Mid Tier
SW00475922
The Sync Cache operation does not rebuild the image if you make any
9.0.00
changes to the image. Also deleting the image during Sync Cache operation,
results in a heavy performance hit in mid tier.
Workaround:
Change the image name, update the form where the image is saved and then
perform the Sync Cache operation to reflect the changes on mid tier.
Page 36 of 4705
Home
Component
Issue
Description
Affected
versions
Mid Tier
SW00434214
When you click a bookmark, the link does not point to the exact bookmark
location, so you cannot identify the bookmark text in an article.
8.0.01,
8.1.00,
9.0.00
Mid Tier
SW00440761
After you run the Atrium SSO Integration Utility for AR System version 9.0 and
8.0.01,
BMC Atrium Single Sign-On version 9.0 with JBoss 6, the JBoss logs
contain an exception. As a result, the mid tier URL returns the following error:
8.1.00,
9.0.00
Corrected
in
The requested resource (/arsys) is not available.

Workaround:
1. Remove the Doctype element from web.xml.
For example:
<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//
DTD Web Application 2.3//EN' 'http://java.sun.com/dtd
/web-app_2_3.dtd'>
2. Replace the <web-app> element with a new one. Do not enter extra
spaces.
<web-app version="2.5"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
3. Remove all the <display-name> tags from web.xml.
4. Replace the birt tag element <taglib> with a new one.
Previous tag:
<taglib>
<taglib-uri>/birt.tld
</taglib-uri>
<taglib-location>
/WEB-INF/tlds/birt.tld
</taglib-location>
</taglib>
New tag:
<jsp-config>
<taglib>
<taglib-uri>http://www.eclipse.org/birt/taglibs/birt.tld
</taglib-uri>
<taglib-location>/WEB-INF/tlds/birt.tld
</taglib-location>
</taglib>
</jsp-config>
5. Restart Jboss with the -b 0.0.0.0 option.
Page 37 of 4705
Home
Component
Issue
Description
Affected
versions
Mid Tier
SW00434732
If you install the BMC Remedy Mid Tier with the AR Crystal Web application
on a 64-bit Windows system with BusinessObjects XI version 4 installed, the
mid tier
creates ODBC-driver information on the system. If you open the ODBC
Administrator Tool from the Windows Control Panel, you will not see the BMC
Remedy AR System ODBC driver listed.
8.0.01,
8.1.00,
9.0.00
Corrected
in
Workaround:
Open the ODBC Administrator Tool from a command prompt: <
WindowsHomeDirectory>\SysWOW64\odbcad32.exe
Mid Tier
SW00436240
In SAML environments, you encounter an SSO timeout with the SSO-enabled
8.0.01,
mid tier when the session expires.
8.1.00,
9.0.00
Workaround:
If you have installed BMC Remedy AR System and Mid Tier with BMC Atrium
Single Sign-On, you must set the BMC Atrium Single Sign-On Idle Timeout
and Max Session Time values greater than the mid-tier timeout value.
For example, if you use the mid-tier default of 90 minutes, the BMC Atrium
Single Sign-On Max Session Time and Idle Timeout values should be set to
120 minutes.
Mid Tier
SW00431582
If you log on to a central mid tier in a distributed mid tier environment using a
Safari browser and open a remote mid tier on a new Safari browser to display
a form that resides on a remote server, make some changes, and then you log
out from the remote mid tier without saving the changes, BMC Remedy Mid
Tier does not display a warning that the changes are not saved.
8.0.00,
8.1.00,
9.0.00
Page 38 of 4705
Home
Component
Issue
Description
Affected
versions
Mid Tier
SW00380883
When you open the customizable home page in an inline view field, the
images to expand or collapse the panels, and to add or remove panels do not
display correctly.
7.6.04,
8.0.00,
8.1.00,
9.0.00
Corrected
in
Workaround:
1. Open the AR System Customizable Home Page in BMC Remedy
Developer Studio.
2. Select the Default Administrator View tab and open the Properties
window.
3. Go to the Web Header Content property and click the ellipses button.
You see the CSS style rules that reference the class img.btnimg
enclosed in the <STYLE> tag.
4. Open the form with a view field on which you have embedded the home
page.
For example, Form X.
5. Verify the <STYLE> tag in the Web Header Content property for Form X
. The CSS rules pertaining to the image buttons must be the same as in
AR System Customizable Home Page.
6. If the style is different, and you are in Best Practice Customization
Mode, create an overlay of the form (Form X). For more information
about how to create an overlay, see Developing an application.
7. Copy the style from the home page form and paste it into the Web
Header Content property on the form (or the form overlay, as
appropriate).
8. If you have other views, or outer parent forms, repeat step 4 through
step 7. For example,assume that you have Form Y with a view field.
You embed AR System Customizable Home Page on Form Y's view
field. The Form Y style for image buttons must match with the home
page style.
Mid Tier
SW00380696
Inline view fields do not support Right-to-left (RTL) formatting if the parent
form is using the Left-to-Right (LTR) mode and vice versa.
Note: IFrame supports this functionality.
Mid Tier
SW00428855
7.6.04,
8.0.00,
8.1.00,
9.0.00
For Internet Explorer or Firefox browsers in a distributed mid tier environment,
8.0.00,
the following error message occurs for a user attempting to log on to a central
mid tier
and use a remote mid tier to display a form that resides on a remote server
in a new browser session if a different user previously performs the same task
on the same central
and remote mid tiers, but closes the displayed form by clicking the X button
without
logging off and then logs off from the central mid tier:
A current session exists for a different users - userName.
8.1.00,
9.0.00
Log off the existing session and try again. (ARERR 9361)
Workaround:
In Firefox, clear the cache and cookies in the central mid tier.
In Internet Explorer, close and reopen the browser instance of the
central mid tier.
Page 39 of 4705
Home
Component
Issue
Description
Affected
versions
Mid Tier
SW00342716
If you place a table in a panel, set the panel's Layout Style property to Fill,
7.6.03,
7.6.04,
8.0.00,
8.1.00,
9.0.00
and set the table's Auto Fit Columns property to True, the table columns will
shrink to fit into the panel's initial size (possibly making the columns
unreadable), and the panel is not filled as it grows and extra slack is left
behind.
Corrected
in
Workaround: Set the table's Auto Fit Columns property to False.

Mid Tier
SW00463451
In BMC Remedy Mid Tier, the RTF field does not expand to accommodate the
9.0.00
content according to the content size, resulting in bad display of the content.
Mid Tier
SW00466918
When you upgrade from BMC Remedy Mid Tier 7.6.04 Service Pack 1 to BMC
Remedy Mid Tier 9.0, the user defined values in server.xml file are not
retained.
Mid Tier
SW00465413
8.0.00,
8.1.00,
9.0.00
9.0.00
If you select the Sync in cluster check box and set the Definition change
interval to 0, BMC Remedy Mid Tier does not open any forms, and the
following error message is displayed:
500: Exception created : java.lang.ArithmeticException:
Mid Tier
SW00465528
The following error is displayed in Microsoft Internet Explorer 9 or 10 when the

value of arsystem.emit_X_UA_compatible_mode variable is set to 10 in the
Mid-tier configuration file:
8.1.01,
9.0.00
ARERR [9506] Unable to display form

Workaround:
Change the browser compatibility settings of the Microsoft Internet Explorer
manually. In Internet Explorer, go to Tools > Compatibility view settings,
and deselect the Display intranet sites in compatibility view option.
Mid Tier
SW00455982
In Asset Management Console, the Status Reason field for CIs is left blank
when you run the Report.
Mid Tier
SW00464696
The following issues were identified with the Remedy Knowledge

Management Application (RKM) and BMC Remedy Service Request
Management forms when using JAWS:
9.0.00
8.1.00,
9.0.00
When you open a knowledge entry from the Request Entry form, the
dialog box that appears is different and does not read the knowledge
entry data correctly.
On Service Request forms, all the answer fields are identified as edit
fields regardless of their type.
When you cancel a Service Request form, the confirmation dialog box
shows unwanted string of text before displaying the message Are you
sure.
Mid Tier
SW00467049
In BMC Remedy Mid Tier versions 7.6.04, 8.1 and 9.0, that use Java 1.8 with
any version of Apache Tomcat web server, you cannot run any web report.
The following error occurs:java.lang.ClassCastException:
9.0.00
org.apache.xerces.parsers.XML11Configuration cannot be
cast to
org.apache.xerces.xni.parser.XMLParserConfiguration
Page 40 of 4705
Home
Component
Issue
Description
Affected
versions
Mid Tier
SW00469539
If you create Web Reports using the BIRT report designer tool, and then
import the report to AR System, and then export the report to MS Excel using
Mid Tier, the heap memory usage rises until either you get an Out of
8.1.01,
9.0.00
Corrected
in
memory error or you get an Invalid row number error from the BIRT
runtime. You cannot export the report to MS Excel.
Mid Tier
SW00485019
While accessing the applications using BMC Remedy Mid Tier, you can open
multiple browser windows using workflows. All the forms opened using the
workflows are closed after you log out. But if you make any changes to open
the forms (for example, change the URL in web address bar or refresh the
page or access any other forms by typing form name) or if a new browser
window or tab is opened and other forms are accessed. Such windows are not
closed by the mid tier after you log out, but a session timeout error is
displayed if you perform any operations on them.
9.0.00
RTF fields
SW00363909
When users select multiple table cells in an RTF field, editing operations do
7.6.03,
not work correctly in Internet Explorer browsers. For example, users cannot
delete text in multiple table cells in an RTF field; they must delete the text in
each cell individually.
7.6.04,
8.0.00,
8.1.00,
9.0.00
RTF fields
SW00363912
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. Only the Collapsible and Accordion panels are
affected.
7.6.03,
7.6.04,
8.0.00,
8.1.00,
9.0.00
RTF fields
SW00379854
Inline RTF fields are not supported on floating panels.
7.6.04,
8.0.00,
8.1.00
Workaround: Use non-inline RTF fields.
RTF fields
SW00383294
In an RTF field with an append menu option, irrespective of where the cursor
is set, the menu value is always added at the end of the text.
7.6.03,
7.6.04,
8.0.00,
8.1.00,
9.0.00
Page 41 of 4705
Home
Component
Issue
Description
Affected
versions
RTF fields
SW00415604
The following are the Rich Text Formatting (RTF) fields open issues for the
release:
8.0.00,
8.1.00,
9.0.00
Corrected
in
SW00414089: When you select the text in the RTF editor and press the
Delete key, an empty box appears in the editor.
SW00411835: After adding an Expand section and typing some text in
the RTF editor, if you expand and close the section on Internet Explorer
9, the text appears twice for some time and then the field refreshes.
Also, if you expand the section again, the text might not display for
some time.
SW00410112: When you open a form with an RTF field in Internet
Explorer 8 and create a table, if you then use the mouse to select the
table, the table is not highlighted to identify the selection. On Firefox,
the table border changes to light blue to indicate the selection.
SW00414748: After you click the Spell Checker option on the RTF
editor, if you move the RTF editor to the browser borders, the Spell
Checker window moves or appears outside the browser.
SW00414538: When you enable the Show/Hide Hidden Elements
option in an RTF field in Safari 5.0.5 and close the RTF editor, the
option is not enabled when you re-open the editor.
SW00414535: The Spell Checker option is enabled even when there is
no text in the RTF editor.
SW00402639: Even though the font size is 14, on Internet Explorer 8
the text appears with font size 10 in the Expand section Header and the
text area.
SW00412246: The Line spaces appear small in the RTF fields and the
line space between the lines differs in the RTF field and RTF editor.
Also, the spaces between the text and line display differently in edit
mode and display mode.
SW00415767: The spell checker removes some special characters on
Internet Explorer 8.
SW00411837: You cannot cut, copy, and paste the RTF field Expand
section easily on Internet Explorer 9.
SW00411557: You must copy the RTF field Expand section precisely
on Firefox to copy and paste the section, otherwise the section is not
pasted correctly.
SW00416496: In Firefox browsers, the spell checker does always not
highlight all instances of misspelled words. Also, when you click the
Spell Checker option for the second time, sometimes the Spell
Checker window does not display a message about no misspelled
words found. (These issues only occur when you copy and paste from
an outside editor such as Word.)
SW00414056: Sometimes the cursor is automatically set to the second
line when you open an RTF editor or set focus to an RTF field.
SW00418290: The spell checker deletes the leading white space above
the Expand section in Internet Explorer.
SW00419728: When you copy the text from an RTF field and pasted in
an another RTF field, the font size appears different. Also, the font size
differs in the Display mode and Edit mode. The font size is smaller in
the Display mode.
Page 42 of 4705
Home
Component
Issue
Description
Affected
versions
RTF fields
SW00424720
The following are the Rich Text Formatting (RTF) fields open issues for the
release:
8.0.00,
8.1.00,
9.0.00
Corrected
in
SW00417023: The spell check feature does not work correctly on

double byte characters. For example, if you add some Chinese words
in RTF field, the correct words are also highlighted.
Note: If you provide space in between the words, the spell check works
. But, the sentence in Chinese must not contain space between words.
SW00417266: The spell check feature does not work correctly on
Russian locale. If you add some Russian words in RTF field, the correct
words are highlighted and also does not display words in the
suggestion list with the correct spelling.
SW00424712: If you open RTF editor on Internet Explorer 8 and press
Enter while typing text in the table or the Expand section, the cursor
does not appear or move to the next line.
SW00425010/SW00423983: If you click the strikethrough or underline
options to apply text formatting in the Expand section and again click
the options to remove formatting, the options does not work correctly on
Firefox or Safari.
On Firefox, to remove the formatting you must highlight the text
again and include empty line on top and bottom of the text.
On Safari, the strikethrough option applies underline formatting
and the underline option applies strikethrough formatting to the
text.
SW00425333: On Firefox, after you delete an Expand section by
selecting the small delete icon on the border of expand section, if you
add a new Expand section, the section is not added.
None: Double click on the suggestion list in Spell Checker causes
unexpected results. You must always perform single click to select a
word from the suggestion list.
RTF fields
SW00425997
The data length in RTF fields has been increased to support the text
formatting in the fields.
8.0.00,
8.1.00,
9.0.00
RTF fields
SW00466155
The Cut, Copy, Paste toolbar options are supported only by Internet Explorer.
Other browsers like Firefox, Safari, and Chrome support only the keyboard
8.1.02,
9.0.00
shortcuts for these options (Ctrl+X, Ctrl+C, Ctrl+V).

Report
Console
SW00353206
After deleting fields from a Web report with the Report Console report
designer, an exception is issued when you run the report. Also the Web report
is not updated after you remove, add, or rename fields. Instead, deleted fields
still appear as a report column, added fields do not appear in the available
field list, and field names do not change after being renamed.
7.6.03,
7.6.04,
8.0.00,
8.1.00,
9.0.00
Assignment
Engine
SW00465674
When you modify the thread count from the Server Settings in the
Assignment Engine Administration Console, and run any process that invokes
the AE_CACHE DoCache command, the Assignment Engine Cache thread
8.1.01,
9.0.00
process never finishes. For example, if you modify the thread count and run
the Assignment Engine sanity check, the check fails.
Workaround:
When you change the thread counts in Assignment Engine, shut down and
restart the AR System Server. This process terminates the Assignment Engine
server and the armonitor restarts the Assignment Engine server.
Page 43 of 4705
Home
Component
Issue
Description
Affected
versions
Flashboards
SW00438995
If you manually deploy version 9.0 flashboards on the same computer and in
the same path and folder where you have an earlier version of the flashboards
binaries already deployed to support remote flashboards, the BMC Remedy
Flashboards 9.0 installation fails.
8.0.01,
8.1.00,
9.0.00
Corrected
in
Workaround:
Perform either one of the following actions:
Stop the earlier flashboards service before installing BMC Remedy
Flashboards version 9.0.
Install BMC Remedy Flashboards version 9.0 in a different location.
Encryption
Security
SW00481606
The BMC Remedy Encryption Performance or BMC Remedy Encryption

Premium installation is not required on java clients if the AR System server
9.0.00
uses RC4 with a 128-bit key for data encryption.

Migrator
SW00466921
9.0.00
In BMC Remedy Migrator, after you create a migration script with the Form
Data Only option selected, you cannot view or edit the field mappings,
because the source form is not listed. If you try to open the Field Mappings
dialog, the following error occurs:
Unable to start Field Mappings, error in loading Source
Fields.
Migrator
Migrator
SW00436853
SW00362555
When an object's permission is set to Additive overlay and new permissions

are added to the overlay object, the destination server displays duplicate
8.0.01,
8.1.00,
entries for the existing base permissions after migration.

For example, if a Struct Admin permission exists for a base form and you add
the Struct Subadmin permission in the additive overlay, after migration
Developer Studio displays a duplicate entry for Struct Admin as added-in
overlay.
9.0.00
The BMC Remedy Migrator Command Line Interface (CLI) takes a long time
7.5.00,
7.6.04,
8.1.00,
9.0.00
to generate the .migrator file on the BMC Remedy IT Service Management (

ITSM) stack. The size of the .migrator file cannot exceed 2 GB.
Workaround: Instead of creating the .migrator file for the whole stack, create
it in chunks based on object types.
Migrator
SW00412690
Delta Data Migration (DDM) reports the No Activity Currency code

found message in the APR: Approver Lookup and APR:Sys-Approval
Definition forms.
7.6.04,
8.1.00,
9.0.00
Workaround: If there is a difference in data on the following forms, you do not

create or update the forms:
APR:Approver Lookup (approval mappings)
APR:SYS-Approval Definition (approval process definition)
9.0.00 enhancements
This section provides information about the following enhancements in this release:
BMC Remedy AR System enhancements in version 9.0.00
Page 44 of 4705
Home
BMC Remedy Migrator enhancements in version 9.0.00

Watch video on YouTube at http://www.youtube.com/watch?v=d5Ksm0Ze0uk
BMC Remedy AR System enhancements in version 9.0.00

This section provides information about the following enhancements in this release:
Separate online documentation for installation and upgrade
API enhancements in version 9.0.00
BMC Remedy AR System server enhancements in version 9.0.00
BMC Remedy Developer Studio enhancements in 9.0.00
BMC Remedy Mid Tier enhancements in version 9.0.00
Other enhancements in version 9.0.00
Separate online documentation for installation and upgrade

Starting with the 9.0.00 release, the installation and upgrade information of BMC Remedy Action
Request (AR) System is available through the new BMC Remedy ITSM Suite 9.0 Deployment
online documentation.
The BMC Remedy ITSM Suite 9.0 Deployment online documentation contains consolidated
information of installation and upgrade procedures for all the components in the BMC Remedy IT
Service Management (ITSM) Suite. This online documentation categorizes the components as:
Platform components: BMC Remedy AR System components and BMC Atrium Core
components
Application components: BMC Remedy ITSM core components, BMC Service Request
Management, BMC Service Level Management, and BMC Remedy ITSM Process Designer
The installation and upgrade information for BMC Remedy AR System is no longer available in the
BMC Remedy AR System online documentation.
Continue to refer to the BMC Remedy AR System online documentation for information about
configuring after installation.
API enhancements in version 9.0.00

This topic provides information about the following API enhancements in this release.
C API support for associations

Starting with this release, BMC Remedy AR System provides C API support for the new
associations object. You can use the API for all the following CRUD operations:
CREATE
SET
Page 45 of 4705
Home
GET
DELETE
For more information, see ARCreateAssociation.
RESTful API to simplify integrations between platforms

BMC Remedy AR System now implements RESTful API, which eliminates the need to use VPN
solutions. RESTful API for AR System is built on a REST framework and supports the following
operations:
GET
POST
PUT
DELETE
AR System RESTful API can be used to create, update, and delete data. For more information, see
REST API.
BMC Remedy AR System server enhancements in version 9.0.00

This topic provides information about the following BMC Remedy AR System server enhancements
.
Improved Archiving
Restrictions for users and groups
Service failover
AR System server queue threads configuration changes
Limiting entries in a report
API call monitoring
Full-Text Search enhancements
New AR System Server Object Association
Improved Archiving
The new improved archiving offers the following:
All the forms are archived on a common global schedule.
Related data in multiple forms can be archived in a single transaction.
The archive definition includes an age qualification.
An archive management console has been introduced.
For more information, see Archiving Concepts.
Page 46 of 4705
Home
Note
In version 9.0, archives must be of type copy and delete or delete. Any archives
that are of type copy at the time of upgrade will be converted to copy and delete.
This ensures that records in the archive form are unique.
Starting 9.0, vendor form and join form cannot be archived. Any existing archive
defined for join form and vendor form is ignored for archiving.

Starting with this release, you cannot create other users with more administrative rights than
yourself, and you cannot modify your own rights.
The new restrictions prevent:
Creation of an administrative user by a nonadministrative user.
Creation of an administrative user with access to more overlay groups than the
administrative user who created them.
The following restrictions apply before and after you create or modify any user in the User and
Group form.
Only an administrator can create, modify, or delete other users belonging to the
Administrator, Sub-Administrator, Struct Admin, or Struct Sub-Admin groups.
A user must have Group ID 1, AR System Administrator rights, and Fixed License in
the group list to create, modify, or delete another user of any of the four administrative
class groups in their group list.
No administrator user can create or modify a user (themselves included) with lesser
administrative restrictions than themselves.
For example, an administrator user with Overlay Group 1 rights cannot create or modify
users who are not a part of overlay groups. Consider a situation where you have created an
ABCGroup with an Overlay Group set to 1. User ABCAdmin is part of the Administrator
group and the ABCGroup. However, ABCAdmin is restricted only to the ABCGroup.
ABCAdmin can change (create/modify/delete) any user belonging only to the ABCGroup.
For more information about creating a group as an overlay group, see Creating groups.
A user cannot create another administrator with the ability to modify base objects if
they themselves cannot do it.
Only an unrestricted administrator can create, modify, or delete groups that restrict a users
administrative capabilities.
Page 47 of 4705
Home
Only an administrator without an overlay-specific groups can create, modify, or remove

overlay-specific groups.
For information about creating and modifying user information, see Adding and modifying user
information.
Before this release, BMC Remedy AR System components stored their configuration data in
separate files. Configuration data for the AR System server and the BMC Remedy Approval Server
was stored in the ar.cfg (ar.conf) file; the data for Mid Tier was stored in the config.properties file;
the data for the BMC Remedy Email Engine was stored in the emaildaemon.properties file; and
the data for the Java plugin server was stored in the pluginsvr_config.xml file. Because the
configuration data was dispersed across files, it was difficult to share the data across servers, or to
backup or restore data. This decentralized structure also led to maintenance issues, data
redundancy, and low data security.
Starting with this release, configuration data is stored in new centralized configuration forms and
reflected in the ar.cfg configuration file (for backward compatibility). Centralized configuration not
only makes configuration data easier to manage, but also makes it easy to share the configuration
settings across servers. Also, because configuration data is stored directly in the database, it is
more secure.
With this release, the configuration data for the following components is centralized:
BMC Remdy AR System server
BMC Remedy Mid Tier
BMC Remedy Approval Server
BMC Remedy Email Engine
BMC Remedy Java plug-in server
For more information, see Centralized configuration.
Service failover
Before this release, companion services were dependent on, and shared the state of the AR
System servers. If the AR System server failed, all the dependent services also failed.
Starting with this release, the servers in the group cooperate together to manage service failover.
The server group manages when the companion services become active to perform tasks and
when they are suspended. Also, the companion services are tracked and can fail over
independently of any AR System server.
For more information, see Service failover.
Page 48 of 4705
Home
AR System server queue threads configuration changes

The AR System server scheduler has many work queues, such as queues for archiving, for
escalation pool 1, for escalation pool 2, and so on. Before this release, each queue had its own
dedicated thread. When jobs were triggered, they were automatically put in the appropriate queue
to make sure that they were serialized with the other jobs in the same queue.
Starting with this release, AR System server uses threads from a thread p ool. A scheduled request
is received by the first available thread. After the request is processed, the thread returns to the
pool and becomes available for another request.
Note
The Fast, List, and Private queues do not use threads from the thread pool.
For more information, see Configuring AR System server queue threads for scheduler jobs .

You can now monitor the number of emails sent and received from AR System server in an hour.
For more information, see Monitoring service operations.
Limiting entries in a report

Starting with this release, you can add the new maxEntriesInFileReport parameter to the <
ARInstallationFolder>\pluginsvr\pluginsvr_config.xml file (BMC Remedy AR System server
reporting plug-in) to limit the number of entries in a BMC Remedy Action Request System (AR
System) report. For more information, see Limiting entries using a published report .
API call monitoring

You can now monitor the API calls between an AR System server and its clients and capture
information such as the number of API calls based on the client type, the total amount of data sent
to the client, the number of successful API calls, and so on.
For more information, see Monitoring API calls.

BMC Remedy AR System now provides the following enhanced logging features:
Feature
Description
Page 49 of 4705
Home
Feature
Description
Logging
configuration
Modify the logging parameters such as log file name, log file size, logging level and so on, without restarting the
process. Modifications to the logging parameters are applied immediately, without an interruption to the service or
to the business.
The logging configuration enhancements are available in:
BMC Remedy Action Request System Plug-in Server
See Configuring Plug-in Server logging.
Logging
restriction
Restrict logging to specific criteria.

Typically, you turn on logging to troubleshoot issues. Generally, log files capture all the information for an area
being logged, which impacts the system performance. The log files capture more information than required and
their large size consumes additional disk space. The logging restriction feature allows you to capture only the
required information in a log file, so that it has less impact on system performance, and extra information is not
recorded. You do not have to parse through large log files to find the source of an issue.
The logging restriction enhancement is available in:
BMC Remedy Mid Tier logging Enhanced capability to include logging for multiple users at the same time
.
See Restricting BMC Remedy Mid Tier logs for multiple users .
BMC Remedy Action Request System server (AR System server) logging New capability added to
restrict logging based on users, client types, and RPC queues.
See Configuring AR System server logging.
Logging
consistency
Format log files consistently. Data is presented in a familiar format to help you parse log files and find root cause
issues easily.
The formats of following log files are consistent with the AR System server log files:
BMC Remedy Mid Tier log files
See BMC Remedy Mid Tier log file format.
BMC Remedy Assignment Engine log files
See Assignment Engine log file format.
Full-Text Search enhancements

The following enhancements for Full Text Search (FTS) are available:
FTS
enhancement
Description
High Availability
for FTS
In a server group environment, Full Text Search (FTS) can be configured for High Availability so search
requests are completed even when a server in the group becomes unavailable. Under the FTS HA model:
Every server with valid FTS Server Group Operation ranking acts as an indexer server.
Each indexer has its own copy of indexes.
The searcher server sends the search requests to indexer servers.
During failover of an indexer server, a search request is routed to the highest ranking available indexer
server to complete the search request.
For more information, refer to Enabling FTS high availability.
Page 50 of 4705
Home
FTS
enhancement
Description
FTS indexing
with
schema-specific
files improved
AR System uses the Lucene 4.9 search engine for Full Text Search (FTS) and uses a schema-specific multi file
index format to optimize read/write operations, resulting in searches that are about three times faster and
indexes that are about 40 percent smaller than the Lucene 2.9 index used in earlier releases.
For more information, refer to FTS index migration.
FTS
components
upgraded to
latest releases
FTS index
migration utility
Engine
Old
version
New
version
Description
Apache
Lucene
2.9
4.9
Enables high-performance full-text search.
Apache Tika
1.2
1.6
Detects and extracts metadata and text from a wide variety of file
formats.
The Full Text Search (FTS) index migration utility arftsutil migrates the single-file Lucene 2.9 index into a multi
file schema-specific index compatible with the Lucene 4.9 search engine. The arftsutil utility is embedded in
the interactive GUI AR System installer, so existing Apache Lucene 2.9 single-file indexes are automatically
migrated to the Lucene 4.9 schema-specific multi file format. Automatic migration can be skipped when you use
the silent installer. The arftsutil utility can be run from the command line to migrate an existing Lucene 2.9
index to the 4.9 format.
For more information, refer to FTS index migration.
BMC Remedy Developer Studio enhancements in 9.0.00

This topic provides information about the following BMC Remedy Developer Studio enhancements
in this release.
Reconciling AR customizations
Associations object
Restricting developer studio modes
Adding an alias for the server name
BMC Remedy Developer Studio now allows you to reconcile your changes by comparing existing
definition, overlay definition, and new definition of the objects.
After upgrading your BMC Remedy Action Request (AR) System Staging server, you can reconcile
your overlays from the reference server so that your customizations are not lost and you can use
the latest features that BMC provides with every new release.
You can copy and merge the changes from the new definition to your previous overlay definition.
BMC Remedy Developer Studio allows you compare your old base definition with the new definition
and the overlay definition. Based on the comparison results, you can copy the changes from your
new definition to the overlay definition.
Page 51 of 4705
Home
Note
Only the Overwrite type of overlay is used for comparison.
For more information about reconciling AR customizations, see Reconcilizing AR customizations

in BMC Remedy ITSM 9.0 Deployment space and Comparing and reconciling objects using objects
list.
Associations object
Before this release, two forms were associated by configuring individual workflows in BMC Remedy
Developer Studio. For example, if you wanted to archive the audit form entries when any form is
archived, you had to manually create a workflow to archive the audit form along with that form.
Starting this release, BMC Remedy Developer Studio now provides a new association object. An
association is a BMC Action Request (AR) System server object that describes relationships
between entries in BMC Remedy AR System forms. These relationships enable you to support
referential integrity, cascade deletes, and archiving related entries.
An association describes a relation between entries in two or more forms. The relationship can
have three cardinality options: One to One, One to Many, and Many to Many. For One to One and
One to Many relationships, an association between two forms is defined by specifying one form as
primary and another form as secondary. For these relationships, the primary form can have only
one entry in the relationship. For Many to Many relationships, there are no primary and secondary
forms.
For more information about associations, see Associations overview.

Starting with this release, you can select specific forms that should be archived along with the main
form based on the associations. You have the option to select associations that ensure related
forms are also archived with the main form in BMC Remedy Developer Studio. For more
information, see Defining associations to follow.
Restricting developer studio modes

Starting with this release, you can use the Dev-Studio-Development-Mode configuration setting to
enable the Base Development mode, Best Practice mode, or both in BMC Remedy Developer
Studio. When you install BMC Remedy AR System, you can choose to work in the Best Practice
mode, Base Development mode, or both modes. To configure modes, you must modify the
Dev-Studio-Development-Mode configuration settings.
Configuration settings C-D
Page 52 of 4705
Home
Development modes
Access restrictions for administrators
Updating configuration settings by using the AR System Configuration Generic UI form
Adding an alias for the server name

Starting with this release, you can add an alias when you add a new server in BMC Remedy
Developer Studio. A new parameter named Server Alias is in the Edit Server List so that when you
have multiple servers, you can identify them using alias, such as Dev Server and QA Server. For
information about configuration, Starting and logging on to BMC Remedy Developer Studio .
BMC Remedy Mid Tier enhancements in version 9.0.00

This topic provides information about BMC Remedy Mid Tier enhancements and new features.
Skins administration for users

Starting with this release, you can monitor the following parameters for mid tier response time:
Bandwidth
Latency
Page load time
Last transaction time
For more information, see Monitoring mid tier response time.

Starting with this release, mid tier can run in an Apache Tomcat cluster environment, which has the
following features and benefits:
Configures easily
Supports In Memory session replication
Supports high availability
Enhances reliability, availability, and serviceability
Provides seamless failover
Provides the ability to add extra mid tiers to the cluster dynamically
For more information, see Tomcat cluster architecture and Configuring a cluster.
Page 53 of 4705
Home

Starting with this release, mid tier can be used as a multitenant application. With this enhancement,
mid tier can be configured as a shared service so that mid tier can serve requests from multiple
customers. Multitenant mid tier provides the following benefits:
Allows you to isolate resources per tenant
Provides scaling to manage load
Ensures resiliency
Optimizes costs
Controls the data flowing through the service
For more information, see Configuring the mid tier as a shared service .
Skins administration for users

Starting with this release, you can enable any user to configure and modify skins on the form views
by using the Skin Designer role in BMC Remedy AR System. In a multitenant environment, you
may enable tenants to configure skins for their environment. For more information, see Enabling
skins administration for users.

Starting with this release, you can view a large number of search results in pages instead of single
large list. For more information, see Setting pagination properties.
Other enhancements in version 9.0.00

This topic provides information about the following enhancements and new features in this release:
Role based access

Starting form this release, all the system forms are moved to a single deployable application. The
access permission to the deployable application is based on roles. For more information, see
Role-based access overview.
New utility to promote data or code from development to production environment

The BMC IT Service Management version 9.0 introduces the utility to enable you to promote
standard changes effectively and reliably across environments. The BMC Remedy Deployment
Application provides better control to promote the AR System object customizations and code
across environments.
For more information, see BMC Remedy Deployment Application

This topic provides information about the following enhancements and new features in BMC
Remedy Migrator:
Page 54 of 4705
Home
Support for associations object

Starting this release, you will be able to migrate your associations objects using the UI and CLI
commands as well. For more information, see Selecting objects to migrate.
Locating white papers, guides, and technical

bulletins
Use the information in the following sections to locate content in the online documentation that was
previously provided in PDF format. In many cases, the content has been distributed among several
sections in the BMC Remedy Action Request (AR) System space, depending on the task being
performed.
BMC Remedy AR System online documentation
BMC Remedy Encryption online documentation
BMC Remedy Migrator online documentation
BMC Remedy IT Service Management Preconfigured Stack online documentation
White papers online
BMC Remedy AR System online documentation

Document
Online section
Release Notes

BMC Remedy Action Request System known and corrected issues in version 9.0
C API Reference
Developing an API program
Concepts Guide
Key concepts
Page 55 of 4705
Home
Document
Online section
Configuration Guide
Key concepts
BMC Remedy AR System client server architecture
License overview
Configuring after installation
Configuring a Unicode server
Configuring AR System servers
BMC Remedy AR System cache management
Administering
Navigating the BMC Remedy AR System Administration console interface
BMC Remedy AR System configuration files
AR System server components and external utilities
Defining your user base
Setting user preferences
Capturing server events for workflow or API calls
Defining business schedules using Business Time
Enabling alert notifications
Assigning requests with the Assignment Engine
Importing data into BMC Remedy AR System forms
Enabling full text search
Troubleshooting
Troubleshooting alert activity
Troubleshooting full text search
Database Reference
Administering
Understanding the AR System database
Error Messages Guide
Troubleshooting
BMC Remedy AR System diagnostic messages
Working with error messages
Form and Application Objects Guide
Developing an application
Packing lists
Creating packing lists
Version control in BMC Remedy AR System
Using object reservation
Using the object modification log
Defining and managing an application
Developing the application interface
Securing your application
Customizing applications using overlays and custom objects
Defining and managing form views
Customizing the home page and entry points
Localizing an application to other languages
Moving to production
Locking objects
Installation Guide
Planning
Installing old
Upgrading
Page 56 of 4705
Home
Document
Online section
Integration Guide
Integrating
Making applications licensable for integration system vendors
Publishing the BMC Remedy AR System functionality as a web service
Introduction to Application Development

with BMC Remedy Developer Studio
Application development with BMC Remedy Developer Studio
Understanding the AR System Navigator
Working with perspectives
Creating objects
Working with existing objects
Finding objects
Using working lists
Using the Outline tab
Using the Messages tab
BMC Developer Studio frequently asked questions
Differences between BMC Remedy Administrator and BMC Remedy Developer
Studio
Development modes
Optimizing and Troubleshooting Guide

Performance benchmarks and tuning
Troubleshooting
Troubleshooting
Workflow Objects Guide
Using menu options in BMC Remedy Developer Studio
Event Navigator
Using buttons and menu bar items to execute active links
Modifier keywords for use in workflows
Defining workflow to automate processes
Troubleshooting
Using Analyzer to find problems in your applications
Working with the Analyzer View tab
Launching the Analyzer from a command line
Troubleshooting BMC Remedy Developer Studio issues
Page 57 of 4705
Home
Document
Online section
BMC Remedy Approval Server Guide
Key concepts
How BMC Remedy Approval Server automates approval-driven business
processes
Installing
Configuring the approval servers in a server group
Starting and stopping the Approval Server
Approval Server post-upgrade procedures
Using
Opening Approval Central
Approving requests
Configuring after installing
Configuring the BMC Remedy Approval Server
Administering
Setting up the approval process
Adding approvals to an application
Configuring BMC Remedy Approval Server logging and loopback calls
Troubleshooting
BMC Remedy Approval Server logging
BMC Remedy Approval Server installation and upgrade issues
BMC Remedy Approval Server file locations
Troubleshooting BMC Remedy Approval Server
Adding approvals to an application
BMC Remedy Distributed Server Option

Guide
Key concepts
How BMC Remedy Distributed Server Option manages distributed business
requests
Configuring DSO for a server group
Configuring BMC Remedy Distributed Server Option
Setting up DSO to synchronize data across multiple AR System servers
Troubleshooting
Configuring BMC Remedy Distributed Server Option logging
BMC Remedy Distributed Server Option logging
Page 58 of 4705
Home
Document
Online section
BMC Remedy Email Engine Guide
Key concepts
How BMC Remedy Email Engine enables email-driven business processes
BMC Remedy Email Engine architecture
Installing
BMC Remedy Email Engine internationalization support
Preparing to install the Email Engine
Configuring the Email Engine for a server group
Configuring BMC Remedy Email Engine
Securing incoming and outgoing email
Configuring SSL for the email engine
Stopping and starting the Email Engine
Administering
Controlling BMC Remedy AR System through email
Troubleshooting
Configuring BMC Remedy Email Engine logging
BMC Remedy Email Engine logs
Debugging options for the BMC Remedy Email Engine
BMC Remedy Email Engine locations
Troubleshooting BMC Remedy Email Engine
BMC Remedy Flashboards Guide
Key Concepts
Data flow in flashboards
Configuring flashboards for server groups
Monitoring reports by using flashboards
Configuring BMC Remedy Flashboards
Using BMC Remedy Flashboards
Adding graphics to an application with flashboards
BMC Remedy Flashboards overview
Creating flashboards
Planning a flashboard
Creating flashboard variables
Creating and managing flashboards
Adding a flashboard to a BMC Remedy AR System form
Flashboard fields
Troubleshooting
Creating flashboards to collect server statistics
Troubleshooting BMC Remedy Flashboards
Page 59 of 4705
Home
Document
Online section
BMC Remedy Mid Tier Guide

BMC Remedy Mid Tier configuration
Configuring reporting
Mid Tier cache configuration
Using
Using the AR System Object List
Running and saving searches
Reporting on BMC Remedy AR System data
Using customized style sheets
Mid tier application development guidelines
Master Index
Use Search in place of the master index.
C API Quick Reference
This document is obsolete.
Installation Quick Reference
Developer Studio Quick Reference
BMC Remedy Encryption online documentation

Document
Online section
BMC Remedy Encryption Security Guide
Key concepts
How BMC Remedy Encryption Security enables secure communication between the
client and server
Planning
BMC Remedy Encryption Security options
Security policy impact on client-server communication
BMC Remedy Encryption Security compatibility
Installing
Installing BMC Remedy Encryption Security
Upgrading
Upgrading encryption security
Configuring BMC Remedy Encryption Security
Troubleshooting
Troubleshooting encryption security
BMC Remedy Encryption Security

Release Notes

BMC Remedy Encryption Security enhancement in version 8.1
BMC Remedy Encryption Security known and corrected issues in version 8.1.00
Page 60 of 4705
Home
BMC Remedy Migrator online documentation

Document
Online section
BMC Remedy Migrator Guide
Key concepts
How BMC Remedy Migrator automates migration of data and objects between AR System
servers
Installing
Installing BMC Remedy Migrator
Configuring BMC Remedy Migrator
Administering
Migrating applications and data between AR System servers
BMC Remedy Migrator Release

Notes

BMC Remedy Migrator known and corrected issues in version 8.1.00
BMC Remedy IT Service Management Preconfigured Stack

online documentation
Document
Online section
Preconfigured Stack Installation Notes
Installing the BMC Remedy ITSM Suite Preconfigured Stack
Preconfigured Stack Installation Quick Reference
White papers online

Document
Online section
BMC Remedy IT Service Management Suite Service Pack 2 Upgrade

Procedures and Guidelines
Planning to upgrade BMC Remedy AR System

Upgrading old
Performance Benchmarking Tutorial Using SilkPerformer with BMC Remedy

Mid Tier
Using SilkPerformer to measure and optimize

application performance
KITE Scripting for BMC Remedy AR System Mid Tier
Measuring mid tier performance with KITE

scripting
BMC Remedy Action Request System Enterprise Quick Reference White

Paper
Planning BMC Remedy AR System installation in

an enterprise environment
Remedy Application Performance Benchmarking Best Practices
Performance benchmarking BMC Remedy

applications
BMC Remedy AR System Server 7.6 Performance Tuning for Business

Service Management
Performance tuning for BSM
BMC Remedy IT Service Management Suite Delta Data Migration Server

Setup and Implementation
Migrating delta data after an upgrade
BMC Remedy Action Request System Behavioral Differences Between BMC

Remedy User and Browser Clients
Page 61 of 4705
Home
Document
Online section
BMC Remedy Action Request System Designing BMC Remedy applications

for Section 508 compliance
Making your application accessible (Section 508

compatibility)
BMC Remedy Action Request System Web Application Security Assessment

and Vulnerability Mitigation Tests
BMC Remedy security certification
BMC Remedy IT Service Management Suite Installing and Configuring

Server Groups
Installing a server group
Integrating BMC Remedy Action Request System with Single Sign-On (SSO)
Authentication Systems and Other Client-Side Login Intercept Technologies
Single sign-on authentication systems integration
BMC Remedy Action Request System Using the Certificate Database Tool
Using a Hardware Load Balancer with BMC Remedy Action Request System
Configuring a hardware load balancer with BMC

Remedy AR System
Supporting Compliance Audits with BMC Remedy Approval Server
Supporting compliance audits with BMC Remedy

Approval Server
Displaying an AR System Form in a Portlet
Available as a PDF at http://documents.bmc.com/

supportu/documents/56/86/65686/65686.pdf
Using Oracle CLOBs with BMC Remedy Action Request System
Using Oracle CLOBs with BMC Remedy AR

System
Page 62 of 4705
Home
Getting started
The following topics help you to get started with the BMC Atrium CMDB product documentation.
Orientation
Key concepts
User goals and features
If you are a system administrator and looking for information on installing or upgrading the product,
you should navigate to the BMC Remedy ITSM Deployment documentation.
About BMC Remedy AR System

BMC Remedy AR System is a professional development environment that leverages the
recommendations of the IT Infrastructure Library (ITIL) and provides a foundation for Business
Service Management (BSM) solutions. Using BMC Remedy AR System, nonprogrammers can
build powerful business workflow applications and deploy them simultaneously in web, Microsoft
Windows, UNIX, and Linux environments.
Applications built with BMC Remedy AR System can automatically track anything that is important
to the processes in your enterprise. Companies use BMC Remedy AR System applications to track
such diverse items as stock trades, benefits data, inventory assets, spare parts, and order
fulfillment. One of the most common uses of BMC Remedy AR System is to automate internal
service desks.
Orientation
Use the information in this section to understand the primary milestones for getting orientated with
the BMC Remedy AR System product documentation, the table below helps you to locate the
information to effectively work with the product.
Goal
Where to go
Where do I begin?
You can begin with learning the Product overview, the key concepts. A Learning path is available for you
to get started on the product.
What are the key

components of the
product?
The BMC Remedy AR System components section gives an overview of all the components and their
value.
Where is the install

and upgrade
information?
The install and upgrade information resides in the Deployment documentation area. The Deployment
documentation assists you with the install and upgrade tasks for all the products that are a part of the
BMC Remedy IT Service Management suite.
Below are some direct links to the Atrium CMDB specific topics from the deployment documentation.
However, it is recommended that you go through the preparing section if you are working with install or
upgrade.
Page 63 of 4705
Home
Goal
Where to go
Installing BMC Remedy AR System
Upgrading BMC Remedy AR System
How do I configure
Refer to the configuration tasks section to complete the configuring tasks after the BMC Remedy AR
the product after

installation?
System product is installed or upgraded.
Start using the
Access the Using section to perform tasks related to navigating the infrastructure, reporting, approving
product, navigating
the User Interface
requests, and using flashboards .
Administer
Refer to the Administering branch to perform the following admin tasks and many more :
Manage user preference.
Manage security.
Full text search, Assignment Engine.
Setting DSO.
Managing data.
Developing
Refer to the Developing and Application and Developing an API program sections to develop applications
using the AR System platform.
Troubleshoot
Troubleshooting section has information on resolving errors related to logs, performance, AR System
components, and so on.
Key concepts
Consult the following topics to learn about the BMC Remedy AR System :
Product overview
Use the following topics to understand how you can use BMC Remedy Action Request System (
BMC Remedy AR System) to address your business needs.
How BMC Remedy AR System enables business process automation
How BMC Remedy AR System products and related products enable additional value and
BSM
How BMC Remedy Migrator automates migration of data and objects between AR System
servers
How BMC Remedy Encryption Security enables secure communication between the client
and server
How BMC Remedy Distributed Server Option manages distributed business requests
How BMC Remedy Approval Server automates approval-driven business processes
How BMC Remedy AR System integrates with third-party products
Page 64 of 4705
Home
How BMC Remedy AR System enables business process automation

Every company, whether it makes bicycles or provides worldwide telecommunications services, has
its own business needs and processes. BMC Remedy Action Request System (BMC Remedy AR
System) enables you to automate many business processes without learning a programming
language or using complex development tools.
BMC Remedy AR System is a professional development environment that
Leverages the recommendations of the IT Infrastructure Library (ITIL)
Provides a foundation for Business Service Management (BSM) solutions
Using BMC Remedy AR System, non-programmers can build powerful business workflow
applications and deploy them simultaneously in web, Microsoft Windows, UNIX, and Linux
environments.
Applications built with BMC Remedy AR System can automatically track anything that is important
to the processes in your enterprise. Companies use BMC Remedy AR System applications to track
such diverse items as stock trades, benefits data, inventory assets, spare parts, and fulfillment
orders. With sufficient planning, even workflow-intensive procedures can be automatically
maintained in an orderly manner.
How BMC Remedy AR System can help manage a service desk

One of the most common uses of BMC Remedy AR System is to automate internal service desks.
The following example illustrates a service desk solution in which BMC Remedy AR System solves
an employee's problem.
Example
Ramona's printer would not work, so she logged on to her company's BMC Remedy AR
System service desk portal and entered information about the problem. The system
automatically offered several knowledge base articles that might apply to her problem, but
none resolved the issue for her.
Ramona then opened a service desk request through the portal to get further assistance from
the IT department. When she entered her phone number into the blank request form on her
screen, details of her configuration and location automatically appeared in the form. Ramona
filled in the remaining details about her problem and submitted the request. She immediately
received a message informing her that the case had been assigned to Becky.
Becky was automatically paged and used her computer to review the problem. Using her
knowledge of similar problems, she fixed the printer and marked the case closed. Ramona
was then notified that the problem was fixed.
Page 65 of 4705
Home
If Ramona's problem had been an emergency that was not handled within an hour, the system
would have automatically paged the appropriate support personnel and sent an email
message to Ramona, informing her of the request status.
In this example, BMC Remedy AR System automated the offer of knowledge base articles, the
entry of information in the form, the assignment notification, the paging system, the closure
notification, and the emergency response.
A service desk application and other ready-to-use BMC Remedy AR System applications are
available from BMC and its partners (see BMC Remedy add-on products). You can also create
your own custom solutions.
How BMC Remedy AR System facilitates adaptability

BMC Remedy AR System is a simpler solution than hard-coded applications, which are typically
inflexible, and development toolkits, which often require extensive technical knowledge and time to
use. Instead, BMC Remedy AR System provides a platform from which even nonprogrammers can
modify ready-to-use BMC applications or create custom applications to fit their unique enterprise.
(Click the image to expand it.)
Perhaps the best way to understand the adaptability of BMC Remedy AR System is through an
example.
Example
Paul owns a small video store and installs BMC Remedy AR System to help track inventory.
Initially, he builds a simple application that has one form. The form collects the video title,
rating, format, number of copies, and rental fee. When his business grows and he needs to
track employees, he adds a form that collects the employee number, salary, start date, training
, and time card.
Next, Paul links his application to a credit/debit verification system by using the BMC Remedy
AR System open API. Later, he adds an order tracking and purchasing application to
automatically order items through web services. He then creates a website to enable
Page 66 of 4705
Home
customers to order movies and pay rental fees online, and to store their rental history in a
knowledge base. He further automates the system to provide proactive movie suggestions
based on this rental history.
How BMC Remedy AR System products and related products enable additional
value and BSM
The core BMC Remedy Action Request System (BMC Remedy AR System) products are the
foundation for the BMC Remedy product line. These BMC Remedy products and features add
functionality to the core BMC Remedy AR System environment:
BMC Remedy Distributed Server Option (DSO) Enables you to send and receive data
from forms that reside on physically separate servers. See Distributed environments provide
scalability and How BMC Remedy Distributed Server Option manages distributed business
requests.
BMC Remedy Encryption Security products Enables the BMC Remedy AR System server
and its clients to communicate securely over a network by encrypting the messages sent
between them. See How BMC Remedy Encryption Security enables secure communication
between the client and server.
BMC Remedy Encryption Standard Security is built into the BMC Remedy products.
(Optional) BMC Remedy Encryption Performance Security and BMC Remedy

Encryption Premium Security are sold separately. The optional encryption products
provide a higher level of security than standard encryption. They also enable you to
comply with Federal Information Processing Standards (FIPS ) 200. All BMC Remedy
Encryption Security products use third-party encryption technology software
developed by the OpenSSL Project for use in the OpenSSL toolkit (see http://
www.openssl.org/).
BMC Remedy Full Text Search (FTS) Provides a search mechanism that is typically much
faster than the native database searching functionality for searching in long text fields. FTS
is the only search method available in BMC Remedy AR System for searching text within
documents that are attached to requests. See Performing searches with FTS.
BMC Remedy Migrator Provides a fast, easy way to move forms and applications
between BMC Remedy AR System servers, servers and files, or files. This tool helps you
transfer data and workflow objects from a development environment to a production server,
while ensuring the integrity of all migrated changes. See Performing migrations.
BMC Atrium products

Together, BMC Remedy AR System and BMC Atrium Core provide the foundation for BMC
Business Service Management (BSM) solutions. The following BMC Remedy AR System-based
BMC Atrium Core components address the recommendations for configuration management.
These products also support IT Infrastructure Library (ITIL) defined processes such as, change and
service management.
Page 67 of 4705
Home
BMC Atrium Configuration Management Database

BMC Atrium Integration Engine
BMC Product Catalog
Although not based on BMC Remedy AR System, the following BMC Atrium applications provide
powerful visualization, decision support, and data discovery capabilities. They are pre-integrated
with BMC solutions for BSM and are ready to use out of the box.
BMC Analytics for BSM
BMC Dashboards for BSM
BMC Discovery Solution
BMC Remedy AR System-based solutions

The following BMC Remedy solutions for IT service and customer relationship management are
built on BMC Remedy AR System platform:
BMC Remedy IT Service Management (ITSM) Suite Offers a complete, integrated
solution to technology life cycle management. The suite applications compress business
cycles with custom routing of approvals and consistent enforcement of business rules. The
suite includes:
BMC Asset Management
BMC Change Management
BMC Service Desk (includes BMC Remedy Incident Management and BMC Remedy
Problem Management)
BMC Service Level Management
BMC Service Request Management Enables IT to define its services, publish them in a
Service Catalog, and give users self-service options, which reduce the requests that must be
handled by service desk support staff
BMC Knowledge Management Gives call center support staff easy access to a vast array
of information needed to resolve problems
Other BMC products

Many other BMC products such as, BMC Atrium Orchestrator, BMC Service Impact Manager, and
BMC Performance Manager integrate with BMC Remedy AR System or applications based on BMC
Remedy AR System. Together, these products provide a complete solution to BSM.
For more information about these products and solutions, see the BMC Software website at http://
www.bmc.com.
How BMC Remedy Migrator automates migration of data and objects between AR
System servers
BMC Remedy Migrator can migrate BMC Remedy Action Request System (BMC Remedy AR
System) objects and data to and from the same server, from one server to another, or to many
servers. It can also migrate from a server to a file, from a file to a server, or from a file to a file, and
Page 68 of 4705
Home
can migrate data from one form to another as well as to a file.

If you have two or more servers in your BMC Remedy AR System environment, you might need to
transfer or synchronize definitions or data between servers.
By using BMC Remedy Migrator, you can migrate objects and data to and from servers quickly
while still having all clients connected and running. BMC Remedy Migrator checks for the integrity
of objects, such as groups, active links, forms, and so on. It migrates only those objects that have
changed after the initial migration.
BMC Remedy Migrator automates the process of transferring objects and data from one source (
server or file) to another. For example, you can develop workflow applications on a development
server (source) and use BMC Remedy Migrator to transfer the applications to a production server (
destination), ensuring the integrity of all migrated changes.

BMC Remedy Email Engine provides a service that transforms email into an interface that
communicates with the AR System server. The Email Engine service does not require an additional
license. The Email Engine enables users to instruct the AR System server to perform queries,
submissions, or modifications to entries, all by using email. This feature is particularly useful for
users without direct access (a high-speed network link) to an AR System server. The Email Engine
also returns the results of such requests in email messages in plain text, HTML, or XML.
Additionally, the Email Engine can process notifications by using workflow actions such as filters or
escalations.
Note
To send notifications from the AR System server, you must install BMC Remedy Email
Engine.
The Email Engine is a standalone client program that you can install and run on any computer
system as an independent service. It provides the following capabilities:
Receiving mail The Email Engine receives email messages from an email account on
your company mail server. These email messages can include instructions that are
interpreted by the Email Engine and translated into API calls to your AR System server.
These instructions can involve modifying form entries, submitting entries, or retrieving
multiple entries from your AR System server.
Sending mail You can use the Email Engine to send email messages, which can include
the results of queries, submissions, or modifications to entries contained on your AR System
server. You can format these emails by using templates that specify the layout of a message
in plain text, HTML, or XML.
Page 69 of 4705
Home
Processing notifications If you choose email when creating a Notify filter or escalation,
you can use the Email Engine to send text messages, contents of select fields, or
attachments when workflow is triggered.
You can connect the Email Engine to mail servers by using the following protocols:
Internet Message Access Protocol (IMAP4) Used for incoming mails. When mail arrives
, copies of messages are downloaded from the mail server to your local computer and the
copy of each message remains on the server. However, when Email Engine is used, this
copy is removed from the server.
Post Office Protocol (POP3) Used for incoming mails. When mail arrives, messages are
downloaded to your local computer and removed from the mail server.
Simple Mail Transfer Protocol (SMTP) Used for outgoing mail transmissions.
MBOX Used for storing mail messages on a UNIX platform. Messages are stored in a file
of type mbox under the user name.
Messaging Application Programming Interface (MAPI) Used primarily with the
Microsoft Exchange Server (Windows only), as an interface that enables different email
applications to work together to distribute email.
Note
The MAPI protocol for incoming and outgoing mail is disabled for the 64-bit Oracle Java
Virtual Machine (Oracle JVM).
All Email Engine settings and all logging information (including error messages, incoming emails,
and outgoing emails) are stored in forms within the AR System server. The Remedy Email Engine
only stores the location of the AR System server where the forms are stored.
Note
You can configure the logs to be stored in a local text file by specifying a handler property
in the logging.properties file. For more information, see Debugging options for the BMC
Remedy Email Engine.
The Email Engine provides additional options, including the ability to create a variety of templates
and to include attachments with email messages. It supports Multipurpose Internet Mail Exchange (
MIME) types for attachments.
Page 70 of 4705
Home
How BMC Remedy Encryption Security enables secure communication between

the client and server
Cryptography protects important data as it passes through an unsecured medium such as, a
computer network. The services provided by BMC Remedy Encryption Security are data
confidentiality, integrity, and authentication.
Encryption enables the BMC Remedy Action Request System (BMC Remedy AR System) server
and its clients to communicate securely over a network by encrypting the messages sent between
them. At the beginning of every client and server connection, a key exchange protocol negotiates
shared encryption keys between the client and server. These keys encrypt all communication
between the client and server, ensuring that the communication is secure and that third parties
cannot decipher the messages in transit. The encryption options do not encrypt the communication
between the browser and the BMC Remedy Mid Tier. The encryption between the browser and mid
tier requires the X.509 certificate to be installed on the mid tier or on the load balancer depending
upon your deployment and security requirements. Data encryption is invisible to users.
The BMC Remedy AR System client libraries provide built-in encryption capabilities that can be
enabled to secure the connection to the AR System server. Higher levels of encryption are
available from BMC if you need stronger encryption. BMC Remedy AR System is also tested with
database encryption products from your database vendor to ensure that this connection can be
encrypted. The communication between the AR System server and the database are not natively
encrypted. The encryption is subject to the capabilities provided by the database vendor.
BMC Remedy Encryption Security includes:
Standard security This level of encryption is built into the BMC Remedy AR System 8.1
API. You do not purchase or install it separately. Its algorithm is 56-bit Data Encryption
Standard (DES ) using Cipher Block Chaining (CBC ) mode. It uses a 512-bit RSA modulus
to exchange keys and MD5 MAC to authenticate messages. By default, standard security is
disabled. To enable it, see Configuring BMC Remedy Encryption Security .
BMC Remedy Encryption Performance Security (BMC Remedy Encryption
Performance) This optional product is installed separately and it provides the following
types of encryption:
RC4 with a 128-bit key for data encryption and a 1024-bit modulus for the RSA key
exchange.
AES CBC with a 128-bit key for data encryption and a 1024-bit modulus for the RSA
key exchange. It uses SHA-1 for message authentication. This option supports the
minimum Federal Information Processing Standard (FIPS) 140-2 encryption
requirements. See FIPS encryption options.
BMC Remedy Encryption Premium Security (BMC Remedy Encryption Premium)
This optional product is installed separately and it provides the following types of encryption:
RC4 with a 2048-bit key for data encryption and a 2048-bit modulus for the RSA key
exchange.
Page 71 of 4705
Home
AES CBC with a 256-bit key for data encryption and a 2048-bit modulus for the RSA
key exchange. It uses SHA-1 for message authentication. This option supports
premium FIPS 140-2 encryption requirements. See FIPS encryption options.
To install BMC Remedy Encryption Premium or BMC Remedy Encryption Performance, see
Installing BMC Remedy Encryption Security. To configure encryption, see Configuring BMC
Remedy Encryption Security.
BMC Remedy Encryption Security includes third-party encryption software developed by the
OpenSSL Project for use in the OpenSSL toolkit (see http://www.openssl.org/ ).
How BMC Remedy Distributed Server Option manages distributed business

requests
BMC Remedy Distributed Server Option (DSO) enables you to transfer requests between servers
and to keep copies of a request synchronized across multiple servers, even if those servers are
geographically dispersed. DSO is available for Microsoft Windows and UNIX platforms.
DSO has many uses, including:
Transferring requests to the location where they are processed
Example
Suppose your company repairs office furniture. Desks are repaired in San Francisco,
and chairs are repaired in Chicago. When a request for a chair repair is submitted to the
San Francisco site, DSO can automatically transfer the request to a server in Chicago.
If the request needs the attention of a specialist, such as an upholsterer, DSO can
transfer the request to a different Chicago server that handles upholstery repairs.
Transferring requests between regions in a customer support environment that operates 24

hours a day, 7 days a week
Example
Suppose your company has customer support centers in San Francisco, Paris, and
Tokyo. You could configure DSO to forward open requests from San Francisco to
Tokyo at the end of San Francisco's business day, from Tokyo to Paris at the end of
Tokyo's business day, and so on. This helps alleviate employee down time and
increases the speed at which requests are processed.
Important
Page 72 of 4705
Home
Depending on your environment, using DSO as a database synchronization engine

might not provide real-time distribution of all data to all users. Before you
implement DSO for this use, your environment should be evaluated to verify that
DSO can perform as expected in it.
Creating a distributed knowledge base
Example
To ensure that problem-solving information is accessible from any location, you can
create filters or escalations that instruct DSO to forward requests closed on one server
to all other servers in the environment. All servers then have access to the
problem-solving information and solutions contained in the closed requests.
Archiving old requests

If you have a server dedicated to archiving, DSO can send closed requests to the that server
.
How BMC Remedy Approval Server automates approval-driven business

processes
BMC Remedy Approval Server is a self-contained, shared module that can be attached to any BMC
Remedy Action Request System (BMC Remedy AR System) application. It is a flexible solution for
automating any approval or signature-driven process across any organization. You can have
multiple instances of an approval server running with multiple instances of the AR System server on
one computer. BMC Remedy Approval Server includes built-in contingency handling, which makes
sure that approvals are completed quickly and correctly within the system.
When a BMC Remedy AR System application triggers an approval process, an approval server
routes a request to collect signatures within a defined approval process, handling all notifications
and requests for more information as it collects each response (approval or rejection). The approval
server then reactivates the original application and reports the result of the approval process.
Page 73 of 4705
Home
Approvals in business processes

An approval indicates an agreement to or rejection of a request or decision. In business, an
approval represents the signature or acknowledgment of an individual where required in a process.
Approvals must often be recorded to provide an audit trail and proof of authenticity associated with
a signature. The approval server provides this functionality in BMC Remedy applications and also
allows you to add any type of approval or signature-driven process to your own AR System
applications. You can use the approval server for processes with the following requirements:
Workflow that includes need for agreement or acknowledgment from others
Processes that must be auditable
Signatures that must be authenticated
Notification with feedback

Although you can use built-in BMC Remedy AR System functionality to exchange simple
notifications, using BMC Remedy Approval Server to do so enables you to build a feedback loop.
You can use this functionality to support business processes for which you must make sure that the
workflow has been seen and approved, acknowledged, or signed by all the relevant parties.
Flexibility and common experience

You can use BMC Remedy Approval Server to define or modify how each approval process should
work. You can set up new processes and adapt existing processes as changes occur in your
organization. Customizing BMC Remedy Approval Server does not require programming expertise.
For every stage of the approval process, you can define notifications to inform interested parties of
the status of an approval request.
BMC Remedy Approval Server allows approvers to gather more information about a request from
any BMC Remedy AR System user. You do not need to build custom workflow or separate
solutions for each application. All processes can share the same approval engine, providing a
common approval experience across applications.
Page 74 of 4705
Home
Related topics
Iinformation to configure the BMC Remedy Approval Server
How BMC Remedy AR System integrates with third-party products

BMC Remedy Action Request System (BMC Remedy AR System) is a platform on which you can
build applications for automating a wide range of support and business processes. BMC Remedy
AR System is designed to be used with third-party products to create an integrated solution. In
many IT organizations, BMC Remedy AR System-based applications are the central applications
for tracking information. Therefore, the opportunities to integrate BMC Remedy AR System with
other applications are endless, ranging from simple access to diagnostic utilities to large-scale
integration with manufacturing, customer interaction, and financial accounting systems.
Note
A strength of BMC Remedy AR System is its rich and robust API. All prospective product
partners are encouraged to integrate with BMC Remedy AR System at the API level
whenever possible. For more information, see Developing an API program.
Many customers purchase BMC Remedy AR System as a development platform to create their
own business applications and automate their business processes. BMC also develops and sells
specific applications such as BMC Service Desk, BMC Asset Management, or BMC Change
Management. These BMC applications are built on top of BMC Remedy AR System.
BMC recommends integrating at the API level because your integrated applications can more
easily be adapted to customers who use applications that are purchased from BMC and to BMC
customers who build their own custom applications. BMC Remedy Mid Tier and BMC Remedy
Developer Studio are built on the BMC Remedy AR System Java API.
Integration defined
In the context of software applications, integration means linking products together to provide
increased functionality and efficiency. In other words, two products together do more (or do it faster
) than the products by themselves.
BMC Remedy AR System is a powerful foundation and development environment for applications
that automate business processes. Its flexible multiplatform, multidatabase architecture and highly
customizable user interface enable BMC Remedy AR System to be adapted to the unique business
processes of a particular company and to evolve as those processes change. However, BMC
Remedy AR System alone cannot perform all of the functions in an environment. Instead, BMC
Remedy AR System applications can be integrated with other applications and tools to form
complete business solutions.
Page 75 of 4705
Home
Integration benefits
The primary intent of business software is to enable users to do their jobs more quickly with fewer
resources. Using two products separately is usually less efficient than using them in an integrated
fashion.
For example, a user might have to enter the same information into two different applications, which
often results in errors. Or the telephone number of an incoming call might be manually entered by a
customer service representative rather than automatically captured. Application integration can
provide improved efficiency and effectiveness.
Areas for integration

The two primary areas for integration between applications are:
Data sharing Passing data structures back and forth or jointly accessing a common
database.
Process linking One application (App1) automatically launches another (App2) "in context
" so that App2 "knows" everything entered into App1, and the user is immediately focused at
the part of App2 that continues the process. Or App2 automatically does its job in the
background based on directions from App1, and the user does not even know it is running.
The overall environment behaves as if it were one large application, and yet the company
can choose the discrete pieces that best meet the business requirements.
Real-time versus asynchronous

Products are sometimes integrated for real-time interaction.
Example
In a help desk environment, a user calls a support person with a question. During the call, the
support person enters information about the user and the question into the call tracking
application. If the best way to answer the question is for the support person to walk the user
through a process on the user's workstation, the support person could click a button on the call
tracking application interface that runs a remote control application. The remote control
application opens a window on the support person's workstation that is a copy of the user's
screen, and the support person can take control of the keyboard and mouse functions of the
user's system to step through a process. The user gets an answer and the support person
never leaves his or her desk.
In contrast, some integration is done asynchronously. This means that an application can be
updating another application on an ongoing basis so that the second application is up-to-date the
next time it is accessed.
Page 76 of 4705
Home
Example
Suppose a Human Resources application contains the names and office numbers of all of the
current employees of a company. Every night, the HR application writes a file that contains an
alphabetical list of all of the employees to a defined place on a file server. Whenever the help
desk starts the call tracking application, the application reads this file and dynamically builds
menus of the employee names so that the support personnel can fill in their forms quickly.
Conversely, whenever a change request to move an office is processed by the help desk, a
notification is sent to the HR system that contains the affected employee name, the new office
number, and an effective date.
For complete information about integrating with third-party products, see Integrating.
License overview
AR System licensing grants the legal use of BMC Remedy AR System and is necessary for
performing unlimited operations that change the database (for example, updating requests).
Note
You do not need a license to install BMC Remedy AR System features, such as BMC
Remedy Developer Studio.
Use this section to get information about the types of licenses, license charges, and obtaining your
license key for the AR System server.
License notes
License types overview
To add any license to a BMC Remedy AR System 7.1.00 server or later server, you must first add
an AR System server license (see Adding or removing licenses).
To add an AR System server license, you need a license key (see Obtaining BMC Remedy license
keys).
After installing your server and adding its license, you can:
Use all the BMC Remedy AR System features
Add any other application licenses without obtaining a key
Page 77 of 4705
Home
Because servers in a server group use the same database, they share licenses. Each server must
have its own AR Server license and license key, but it shares all other licenses with the other
servers in the group.
For more information about server groups, see Configuring server groups.
Differences in licensing in earlier versions

This table lists the differences between licensing in BMC Remedy AR System 7.1.00 and later
releases and licensing in pre-7.1.00 releases:
Differences in licensing
Component
Previous releases
BMC Remedy AR System 7.1.00 and later
License
keys
Every license required a key.

Before you could add any
license to an AR System server,
you had to contact BMC to get a
key.
Only AR System server licenses need keys. Customers can add all nonserver
licenses without the need for a key.
Server
All AR System server and user
No license qualifiers are required.
groups
floating licenses used by server

groups needed a license
qualifier.
All licenses used by a server
group had to be applied to every
server in the group.
Each server must have its own AR Server license and license key, but it shares
all other licenses with the other servers in the group.
Dedicated
Dedicated server licenses were
Dedicated server licenses are not used. When you upgrade to 7.1.00 or later
server
licenses
provided for common

components such as the BMC
from a pre-7.1.00 release, dedicated server licenses are upgraded to full AR

System server licenses at no cost. In addition, licenses for any applications
Atrium Definitive Software

Library or CMDB.
associated with the dedicated server are automatically added to your system.
License notes
The following notes apply to BMC Remedy AR System licensing:
BMC Remedy AR System server, server option, and application licenses
Each instance of an AR System server, server add-on, and an application must be licensed.
An instance is defined as an AR System server or group of servers (that is, server group)
sharing a common database.
In addition, each AR System server must have its own AR Server license key, but the server
group feature shares all other BMC product licenses with all of the servers in the group. See
Licensing for server groups for more information.
User fixed licenses
When you add AR System or application user fixed licenses to a server, you specify the
number of such licenses that can be concurrently assigned in the Number of Licenses field
(see Adding Licenses). This number is the maximum number of licenses available for
assignment. This number does not have to be the same as the number of licenses you
Page 78 of 4705
Home
purchased. The peak number of user fixed licenses assigned to users in each billing period
is tracked and used for auditing purposes, whether or not the assigned users ever log in.
Fixed user licenses are considered site licenses, where a site is defined as all of the AR
System servers licensed under a single Support ID. Fixed user licenses are assigned to a
named user who is entitled to use the same fixed user license anywhere within the site.
If the fixed user license is entitled only as a development fixed user license, it may be used
only on development servers.
User floating licenses
When you add AR System or application user floating licenses to a server, you specify the
number of such licenses that can be concurrently used in the Number of Licenses field.
This number is the maximum number of licenses available for use. This number does not
have to be the same as the number of licenses you purchased. The peak number of user
floating licenses in use at the same time during each billing period is tracked and used for
billing purposes.
A floating user license is associated with a single instance at any given time. While it can be
transferred between instances, it cannot be associated with two instances at one time.
User license limits

You can make any number of user licenses available on your server regardless of the number you
purchased. For example, if you purchased 10 AR System User Fixed licenses but need to use 15,
you can immediately update the Number of Licenses field. If, during an audit, BMC finds that your
usage exceeded your purchased license count, you will be billed for the additional use.
Important
To remain in compliance with your purchased licenses, be sure to set the appropriate use
limits in the Number of Licenses field for each license.
License types overview

To use BMC Remedy AR System fully, you need several types of licenses in addition to an AR
System server license:
BMC Remedy AR System User The following types of licenses provide users write
access to an AR System server:
AR User Fixed
AR User Floating
See License types for users to access BMC Remedy AR System server .
Page 79 of 4705
Home
Server options Optional server components, such as Distributed Server Option (DSO),
require separate licenses.
Application To be run on an BMC Remedy AR System server, most applications must be
licensed on the server.
Application user To use BMC Remedy AR System-based applications, each user needs
the following licenses:
BMC Remedy AR System user (fixed or floating)
Application user (fixed or floating)
An BMC Remedy AR System server with no server license enables you to assign these licenses:
Three fixed user licenses
Unlimited user read licenses
Unlimited user restricted read licenses
You can evaluate BMC Remedy AR System without purchasing or activating any licenses. You are
limited, however, to a maximum of 2000 requests per form.
To purchase additional licenses, contact your BMC Remedy product sales representative or an
authorized reseller.
For information about licensing applications that you create using BMC Remedy products, see
Making applications licensable for integration system vendors .
Access control overview

This section describes user and group access, role-based access, multitiered access, and how
licensing affects access control.
User and group access overview
Role-based access overview
Multitiered access control model
How licensing affects access control
BMC Remedy AR System provides a rich set of features that protect your data from unauthorized
access. In addition, it has a logical, multitiered access control structure that is straightforward for
you to implement and for users to understand.
Keeping information secure can be a major undertaking in client/server environments. It is
sometimes a balancing act for administrators. You want to rigorously control who can access data,
yet you do not want security to be so complex that it intrudes on your user community or is difficult
for you to implement or maintain.
BMC Remedy AR System enables you to meet these seemingly opposing security goals. It enables
you to control which users can access data and perform certain actions such as modifying a
request or triggering an active link. User access is determined by these conditions:
Page 80 of 4705
Home
The groups to which users belong

The licenses users are granted
BMC Remedy AR System uses a multitiered approach to control access at these points:
Server
Form (or table)
Field (or column)
Active link and active link guide
Request (or row)
This approach provides a wide range of control over data access, enabling you to restrict access
broadly at the highest levels (server and form) and narrowly at the request and field levels.
Because you can refine your data access criteria so precisely, you can use a single form for many
different purposes simply by setting the appropriate permissions.
When users start an BMC Remedy AR System client, they must enter a user name and a password
, which are checked against every AR System server with which the client is trying to connect. After
a connection is made, each request that goes between the client and the server has the current
user name and password checked to verify that the values are still valid.
In addition to having a unique user name and password on a server, every user is a member of
zero or more groups. Groups are defined and maintained with the Group form, where each record
is a different group definition. For example, there might be groups defined for First-Level Support,
Back-Line Support, and Support Management. Groups are used to control information access to
forms, requests, fields, and active links/guides. As a practical matter, most users are likely to
belong to the Public group.
You could use group access to forms so that a particular form is visible to users in the Support
Management group, but not to users in the First-Level Support and Back-Line Support groups. For
a particular form, an administrator can determine that certain requests are accessible only by
members of one group and that other requests are accessible by members of a different group.
In addition, every field on a form has access control. You set field permissions when you define the
field properties in BMC Remedy Developer Studio. Each field can have a list of groups that can
view the field and the data entered into it. Some or all of the groups with View permission might
also have "change" access so that they can enter and modify the data. If a user opens a form on
his or her workstation and the groups he or she is a part of do not have View access to some of the
fields, those fields are not displayed on the form. A field can also be visible to users or hidden so
that it is accessible only through workflow.
Finally, each active link and active link guide has its access control assigned when it is created. A
user who has access to an active link does not automatically have access to the field associated
Page 81 of 4705
Home
with it. Similarly, a user who has access to a guide does not automatically have access to the active
links in the guide.
Access control in BMC Remedy AR System is additive. That is, each user starts out with no access
permissions; administrators then add permissions as needed. In this way, BMC Remedy AR
System implements strict access control. Administrators must make a conscious decision to grant
access to specific groups on a case-by-case basis. However, if desired, the default permissions
can be changed.
Only BMC Remedy AR System administrators or subadministrators can modify security parameters
.
User and group access overview

Individuals who need to access BMC Remedy AR System are registered as users by an
administrator. The administrator then assigns the users to access control groups.
Each access control group is defined for a particular server. An access control group has
permissions that determine whether and how its members can access application components,
such as forms, requests, fields, active links, and active link guides. (Administrators can also set
default permissions for each component type so that whenever they create a component, selected
groups automatically have access to it.)
Users are assigned to groups according to their need to access information. For example, you
might create a group called Employee Services Staff whose members are permitted to view and
change only certain fields in an Employee Information form. You might have another group called
Employee Services Managers whose members are permitted to view and change all fields in the
Employee Information form, including salary information. You can also configure a hierarchical
relationship between groups to allow the parent group to inherit the permissions of the child group.
BMC Remedy AR System has predefined groups that perform specific functions (see Types of
access control groups). In addition, you can create any number of custom groups in BMC Remedy
AR System to enforce access control. You can also permit unregistered users to access BMC
Remedy AR System as guests. Guests are members of the predefined Public group.
Types of access control groups

This table lists the types of access control groups. BMC Remedy AR System provides the
predefined groups, but you must add custom groups to your system.
Access control group types
Page 82 of 4705
Home
Type
of
access
control
group
Description
Explicit
A group to which you must assign users.
Predefined groups
Administrator
Sub
Administrator
Customize
Custom groups
Any regular and computed groups that you create.

Regular groups are groups to which you assign a
specific list of users. Computed groups are groups to
which users are assigned based on their
memberships in 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 users who are
members of both groups A and B, or members of
group C, but not members of group D.
Implicit
A group to which a user automatically (or

implicitly) belongs by virtue of the contents
of certain fields in a request. You cannot
assign users to implicit groups. All users
are members of Public. You use the other
types of implicit groups to control access
to requests (row-level database access).
Public
Submitter
Assignee
Assignee
Group
Any dynamic groups that you create.Dynamic

groups use the contents of special fields to
determine group membership.
For more information, see Licensing BMC Remedy AR System.
Additive access control

Access control in BMC Remedy AR System is additive. This means that each user in BMC Remedy
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 "Additive permissions", the user
has permission to access the object. As you add permissions to various BMC Remedy 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.
In this example, Lydia Lan is a member of two groups: Engineering and Engineering Managers.
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.
Additive permissions
Page 83 of 4705
Home
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.
Membership in multiple groups

Users often belong to multiple groups in an organization. They inherit permissions from each of the
groups to which they belong.
If a group has permission to access a form, field, request, active link, or active link guide and a user
belongs to that group, the user has access, even if the user belongs to other groups that do not
have access.
How permissions work
Page 84 of 4705
Home
Role-based access overview

The system forms are added to a single deployable application. In deployable applications, access
permissions are based on roles. Like groups, roles have permissions to access forms, fields, active
links, and so on. Unlike groups, however, roles are defined for an application and are then
associated with groups on the server where the application is deployed.
Roles make deployable applications easy to install on multiple servers. You can assign users to
groups, then associate the groups with roles. This enables you to install an application on servers
that have different groups without redefining the application's object permissions for each server.
The following table lists the roles used to access the deployable applications:
Type of roles
Description
Alert Administrator
Manages alerts in the user alerts list.
AR Definition
Administrator
Allows read access to the AR System metadata forms. The AR Definition Administrator also has the ability to
modify definitions through configurations.
Archive
Administrator
Configures and manages the archive policies. The Archive Administrator performs the following tasks:
Accesses the AR System Archive Manager console
Enables and disables system-wide archiving
Enables and disables individual archive policies
Runs an on-demand archive process
Exports and deletes archive data
Email Engine
Administrator
Configures the Incoming and Outgoing mailboxes to work with the mail server and manages email templates.
Home Page
Administrator
Specifies the default home page for a server and configures the AR System Customizable Home Page.
Configures and manages system, user and application licenses
Page 85 of 4705
Home
Type of roles
Description
Licensing
Administrator
Logging
Configures and manages the system logs
Administrator
Reporting
Administrator
Defines who has access to view a report. Views and manages the reports shared by all users.
User
Administrator
Adds and deletes users in the AR System server, manages user permissions and user preferences.
Note
To simplify, user access is usually described in terms of group permissions. For the
deployable applications that use role permissions, the user access is ultimately
determined by the groups that are mapped to the roles.
For more information, see Creating and mapping roles.
Multitiered access control model

BMC Remedy AR System uses a multitiered approach to control data access. At each access level,
a user's permissions are checked. If access is permitted, the user proceeds to the next level. If
access is denied at any point except active links and active link guides (workflow), the user cannot
proceed. (If access is denied at workflow, the user might be able to proceed, but his data access
capabilities will be limited.)
For example, if a user is denied access to a form, the user cannot see any fields associated with
the form. For another example, a user's ability to access a request depends on whether he belongs
to a group that has access to the Request ID field.
Access control in BMC Remedy AR System
Page 86 of 4705
Home
Access control levels

The access control model comprises the following levels:
Access
level
Description
BMC
Remedy
AR
System
server
Users must pass an initial checkpoint when they start an BMC Remedy AR System client, such as a browser. At this
point, users must enter a valid user name, a password, and, as an option, an authentication string. BMC Remedy AR
System servers check the user name, password, and authentication string each time a client requests a transaction,
such as when opening a form or changing a field. If your BMC Remedy AR System server is configured to allow guest
users, such users can log in to the server without a valid user name or password. See User form access.
Form
As an administrator, you give groups access to forms according to each group's need to view or change information in
the form. Visible access enables users to access a form from the Object List. Hidden access makes a form available
only through workflow. Static permissions inheritance and dynamic permissions inheritance properties control access to
the form for parent groups. If a group is not given access to a form, members of that group cannot view the form or
change the requests that it contains.
Field
You can control access to each field on a form, including nondata fields such as trim fields, table fields, and active link
control fields. You can make a field visible to users or hide the field so that it is accessible only through workflow. For
data fields, you also specify whether a group can only view field information or also change it. If a group cannot access
a field, the field does not appear when members of the group open the form.
Active
link
In addition to controlling access to form and field data, you can control access to active links, which trigger a variety of
workflow actions. For example, you might allow support staff to trigger several active links appropriate to their work but
not allow other users to trigger those active links. Groups do not automatically have access to the field associated with
an active link. You must grant them access to the active link and to the field. For active links that fire when users click a
button or choose a menu item, the users must have access to both the button or menu item and the active link to
trigger the active link.
Active
link
guide
When you create an active link guide, you specify the groups that have access to it. To access an active link guide, a
user must have permission to each active link in the guide and to the guide itself. If a user has access to all active links
in a guide but not to the guide, the guide does not appear.
Request
Page 87 of 4705
Home
Access
level
Description
You can strictly control who can access requests associated with a form. For example, you might want only managers
to access requests with confidential employee information. Or you might provide an outsourcing service in which you
use BMC Remedy AR System as the central service desk for several companies, and you do not want one company to
see requests from another company.
How licensing affects access control

In addition to obtaining a license to run the BMC Remedy AR System server and other components
, you must specify a license type for each BMC Remedy AR System user.
Note
BMC Remedy AR System includes a setting that enables you to permit users who are not
recognized users to access to BMC Remedy AR System applications as a member of the
Public Group. For more information, see User and group access overview.
Although licensing is not a component of access control, licensing can affect a user's ability to
perform an operation that you grant the user permission to perform. For example, if a user is a
member of a group that has Change permission to a field but you did not give appropriate write
license, the user cannot change the field.
Application development overview

BMC Remedy AR System provides extensive authoring capabilities for applications built for web
and Windows environments. Applications developed with BMC Remedy Developer Studio are fully
customizable and extensible. You can add your own fields, objects, and templates to any
application, whether it is created by you, purchased from BMC, or acquired from a third party.
This section describes application types and components, describes localization features for the
applications, and provides an example of the BMC Remedy AR System application.
BMC Remedy AR System application types
BMC Remedy AR System application components
Application localization
An example BMC Remedy AR System application
Archiving overview
BMC Remedy AR System application types

You can create the following types of applications:
Deployable applications are designed to be used in multiple server environments. These
applications use permissions based on roles defined in the application. When the application
is deployed, the administrator maps the roles to groups on the local server. Other features
Page 88 of 4705
Home
available to deployable applications include the ability to gather statistics about the
application and to map the same role to different groups for different application states, such
as test or production.
Local applications use permissions based on groups defined on the local server. Therefore,
these applications are usually used on a single server.
BMC Remedy has developed a number of applications, including BMC Remedy Help Desk, BMC
Asset Management, BMC Change Management, BMC Remedy Service Level Agreements, BMC
Remedy Quality Management, BMC Remedy Customer Support, and BMC Remedy Citizen
Response. These applications are used to track information such as trouble tickets, change
requests, asset records, purchase orders, stock trades, and service level agreements.
BMC Remedy AR System application components

This topic introduces the main components of an BMC Remedy AR System application.
Form The main BMC Remedy AR System application component that users interact with
is a form. Each form is composed of fields. Forms display information in fields. A field can be
a unit of information, such as an employee's last name, or it can be a visual element, such
as a line or a box. You can design different field arrangements, or views, of forms for
different user functions.
Each data field on a form has a set of properties that define the size of the field, the type of
data that the field stores, and any access permissions. There are also several fields that
don't contain data but instead organize data or improve the appearance of the screen: active
link control fields (buttons and hotlinks), table fields, trim fields, and panel fields. Fields from
existing forms can be combined into join forms.
Adding fields to a form causes the AR System server to create columns in a database table.
When a user fills in the fields and saves the data, the system creates a request to track. In
database terms, each request is a record.
You can bundle related forms into an application. For example, a human resources
application might include forms for basic employee data, health benefits, and salary
information. You can deploy the application to multiple servers to make it accessible to
employees in different locations. You can also display your application on the web to allow
access from a browser on any platform, as shown in the following figure.
Console application viewed in a browser
Page 89 of 4705
Home
Menu Menus are lists that you create to guide the user in entering information in fields on
forms. Menus are attached to fields on forms as fill-in aids. They can provide suggestions for
entering data into a field, or can be mandated as the only possible choices. Menus can be
statically defined, dynamically built by querying other AR System database tables, read from
text files written by other applications, or created from SQL queries to external databases. A
menu can contain all possible values for a field, or it can contain some possible values,
enabling users to enter text that is not on the menu. You can design dynamic menus, which
change their contents based on the data already entered in the form. See Field menus.
Workflow While forms provide the mechanism to structure data capture and menus offer
options for specific field data, additional components (active links, filters, and escalations)
act on the data to automate business processes, or workflow. These components trigger
actions in response to execution options that you define. In BMC Remedy AR System,
workflow generally refers to the operations triggered by these components, but BMC
Remedy AR System also addresses the broader meaning of workflow, which consists of the
processes that your organization uses to run itself. See Workflow overview.
Association If you want to create a relationship between two different forms in BMC
Remedy AR System, you can create an association. Association is a new object added in
BMC Remedy Developer Studio which is used for creating relationships. These relationships
are used in various BMC applications.
BMC Remedy AR System forms overview

Forms are the foundation of BMC Remedy AR System. A form captures and displays information
and a set of forms can be grouped into an applications. An AR System application is a server object
that contains references to one or more forms. When an application references a form, BMC
Remedy AR System automatically includes all the workflow and other components (such as menus)
associated with the form in the application.
Sometimes a single form can contain all of an application's functionality. For example, a small
application that tracks product defects can use a single defect-tracking form to capture and display
all required information.
Page 90 of 4705
Home
Most applications, however, need several forms to capture, track, and organize information. One or
more forms make up the application's main forms (sometimes called primary forms) that users
interact with directly. Often, the main form is a console that serves as a navigation and information
center. The application can also have other forms, called supporting forms, which supply
information needed by the main forms.
For example, a service desk form captures information needed to fix a user's computer problem. A
purchase requisition form captures the information needed to purchase an item. The following
figure illustrates a BMC Remedy AR System form.
Each form contains fields. Some fields, known as data fields, capture a certain type of information,
such as a user name or problem details, and have their own set of rules about who can view or
modify that information (see Field types). Some fields can have attached menus that help users fill
in the form (see Field menus).
Example of a BMC Remedy AR System form
Each form in an application is like a template to capture or present information. When a user opens
a form to perform a task, the template is presented to help the user complete the task. When the
form is filled in and submitted to BMC Remedy AR System, the system creates a request, also
known as a record in database terms.
Forms are stored as tables in the database. Each data field on the form corresponds to a column in
the table. A request corresponds to a row (or record) in the table.
A form from the view of the database
Page 91 of 4705
Home
Form types overview

You can create the following types of forms, as illustrated in the following figure:
Form types
Form type
Description
Regular
Information submitted through and displayed in regular forms is stored in database tables. These forms are typically
the main forms in applications. They are also called data forms.
Display-only
These forms contain display-only fields that enable users to accomplish specific tasks. These forms are typically
used to create control panels, which are launch points from which users choose other tasks. Display-only forms can
also be used to create dialog boxes, which prompt users as they fill out a form. Display-only forms do not contain
data, so no database tables are associated with them.
Join
These forms are composed of fields from two or more existing forms. Join forms are useful when you have
information in multiple forms that you want to display in a single form. Join forms do not contain data, so they have
no database tables associated with them. The data is contained in the underlying forms that make up the join form.
View
These forms enable users to connect to database tables created outside of AR System. These forms enable you to
bring data from other applications that is stored in a database into AR System without replication or programming.
Vendor
These forms enable users to connect to external data sources such as text files, spreadsheets, or database tables
residing on local or remote servers through an ARDBC plug-in. Some programming is required to connect to the
data source.
Types of AR System forms

Page 92 of 4705
Home
Form views overview

A view is a visual representation of a form. To reuse a form for diverse groups while
accommodating each group's unique needs, you can create a different view of the form for each
group. This enables you to customize the interface of an AR System application so that each group
sees the system as its own.
You can create as many views of a form as you need. For example, you can provide views
customized according to the following criteria:
Users' roles (requesters, managers, and so forth)
Size of the screen (for example, laptop or desktop)
Language or locale (for example, Brazilian Portuguese)
When creating form views, you can:
Change the layout of the form
Use different fields in different views
Tailor views to provide the best result in the target display environment, such as browsers
Use terminology or language specific to the group using the view
Workflow overview
The function of workflow is to process the data captured in forms in accordance with your business
needs. In BMC Remedy AR System, workflow automates your company's processes through the
use of active links, filters, and escalations. In general, workflow can be defined as the set of
processes that your company uses to run itself for example, tracking defects or administering
employee benefits.
You use the workflow components of BMC Remedy AR System to enforce business rules in a
Page 93 of 4705
Home
variety of ways, including notifying people of events, escalating problems to a higher level,
automatically routing information, and checking whether key data is correctly entered. For example,
if your organization decides that purchase orders for amounts above a certain level need director
approval, you can design workflow that allows only correctly approved purchase orders to be
automatically forwarded to the purchasing department.
If a workflow definition is triggered and the qualification is met, one or more actions can be taken by
BMC Remedy AR System.
Some of the actions that workflow components can take to automate processes and ease data
entry include:
Opening new windows for data entry or display
Copying data from other forms or sending data to other forms
Sending messages to users or sending notifications using email or other methods
Manipulating a form (for example, enabling or disabling fields, or changing menus
associated with fields)
Making DDE or OLE connections to other applications
Running an external process
Managing dialog boxes, which are fields that are displayed to users who are filling out forms
Error checking
Logging information to a file, usually to maintain an audit trail
Running an SQL command
Overriding user-entered values by changing them to values that you specify
Communicating with users by means of onscreen messages or notifications sent by email, or
other methods
Running an active link guide or a filter guide as a subroutine (a predefined sequence of
commands)
Types of workflow components
Workflow actions and execution options
Workflow qualifications
Types of workflow components

Following are the workflow components in BMC Remedy AR System:
Active link An active link is an action or group of actions performed on the client. Active
links are triggered by user actions in a form. They can be used to perform a variety of tasks,
such as giving quick responses during data entry and auto-filling fields. For example, an
active link can verify a value entered in the Employee ID field of a request and then pull
information from a supporting People form to fill in other fields on the request, such as
Requestor Name, Department, and Phone Number, dramatically reducing the time
required for support staff to fill out a request.
Page 94 of 4705
Home
Filter A filter is an action or group of actions performed on the AR System server. Filters
are used to enforce business rules and to ensure system and data integrity. As the server
processes a request, the filters associated with that form and action evaluate the data in the
request. For example, you can verify the values in a completed form by using a filter to
compare them against your business rules and return an error if the request violates any of
those rules.
Escalation An escalation is an action or group of actions performed on the server at
specified times or time intervals. Basically, an escalation is an automated, time-based
process that searches for requests that match certain criteria at specified times and takes
actions based on the results of the search. For example, an escalation can trigger AR
System to notify the next level of management if a problem is not assigned to a technician
within one hour of submission.
This following example illustrates how the workflow objects work together with other BMC Remedy
AR System application components. In the example, when Ramona entered her telephone number
into the Telephone # field, the following sequence occurred, as illustrated in the following figure:
1. An active link searched the Employee form to retrieve the name, configuration, and location
associated with the telephone number.
2. After Ramona finished entering information into the form and submitted it, filters triggered an
external paging system integrated with AR System to notify Becky that Ramona's printer was
not working.
3. Becky fixed the problem.
4. Becky changed the status of the request, and a filter notified Ramona that her problem was
solved.
Example of an automated workflow
If the situation had been flagged as an emergency and no one was assigned to the request within
an hour, an escalation would have paged all required support personnel, and a filter would have
sent Ramona an email message informing her of the status of her request.
Collections of workflow components

You can collect active links and filters and run them as procedures. These collections are called
active link guides and filter guides.
Page 95 of 4705
Home
The workflow components in guides are organized in a processing sequence. Using guides enables
you to give a name to a set of workflow operations that accomplish a specific task.
In addition, interactive or navigational active link guides can interact with users by requesting
information and then waiting for input. This enables you to create tasks that guide users through
application processes in a way similar to wizards.
An active link guide is a group of active links. Because active link guides run on a client, they can
augment training by leading users through the steps necessary to fill in one or more forms to
accomplish a specific task. For example, when an employee clicks a *Request Business Cards*
button on a human resources form, an active link guide might open a business cards form and then
display input instructions, field by field, until the card request is complete and ready to submit.
Active link guides can also be used as subroutines to accomplish common tasks.
A filter guide is a group of filters that can be used as a subroutine in workflow. Because filter
guides run on the server, they cannot be used like active link guides to lead users through a form.
This table summarizes how and where you use filters, active links, and escalations:
How and where workflow components are used
Component
Triggered by
Where action is performed
Active link
Events
Client
Filter
Events
Server
Escalation
Time
Server
Workflow based on events versus time

Filters and active links are triggered by events, such as a user action or a change in the state of
some data, whereas escalations implement time-based business rules.
For example, a filter can notify a support manager whenever a request is submitted with a priority of
High or Critical. The submission of the request is the event. Other events that can trigger filters are
updating, deleting, and retrieving requests. Actions that can trigger active links include opening or
closing a window, displaying a request, clicking a button on a form, pressing Enter when the cursor
is in a field, or selecting a menu item.
Escalations are triggered by the passage of time. The trigger (or execution option) can be either
absolute time, such as "every day at 2:00 p.m.," or a time interval, such as "one hour between
escalation runs." For example, an escalation can warn a group of users that in one hour their
manager will be notified that a problem has been unsolved for too long.
Workflow running on clients versus servers

Active links are executed on the client side in response to actions that users perform in forms,
whereas filters and escalations are executed on the server.
Page 96 of 4705
Home
For example, active links can change how a form looks or behaves, validate data entered by users,
or use data in a form to find other data for the form. Unless an active link queries the AR System
server for information or runs a process on the server, it can complete its operation without sending
a request to the server. This capability helps decrease overall network traffic and improves the
performance of an application.
Filters and escalations implement business rules by examining newly created or changed requests
and taking actions based on the new data and the business rules. For example, if your business
wants to avoid handling purchase orders that are not properly approved, you can create a filter that
stops AR System from processing such purchase orders after they are submitted to the server and
then notifies the requester accordingly.
Actions associated with filters and escalations take place after the transaction is transferred to the
server for processing. Then, processing can return to the client, where more active link actions can
take place.
Note
API calls to the server trigger filters but not active links. If a business rule must be fired on
any input (including user input and input from an integrated process using an API), the
business logic must be in both an active link and a filter.
Workflow actions and execution options

You define workflow by specifying the actions that active links, filters, and escalations should
perform under specified circumstances. The circumstances are called execution options. You can
create workflow components for a single form, or you can share workflow components with multiple
forms. (Workflow components cannot exist independently of forms.)
The basic questions about workflow are "What can I do, and when can I do it?" The actions that
workflow can take are the what, and the execution options are the when.
For example, users could click a button labeled Display My Active Cases to display a list of all
requests assigned to the user.
Example of a basic workflow
Page 97 of 4705
Home
You can refine execution options by specifying a qualification that must be met before an action is
taken. Qualifications are often required to ensure that workflow actions apply only to certain
requests. In addition, carefully designed qualifications make workflow components more efficient
and powerful.
You can specify a primary action and an alternative action. If an operation meets the qualification,
the primary ("if") action is performed; if not, the alternative ("else") action is performed, as shown in
the following figure.
Example of a workflow with qualification
For more information about workflow actions, execution options and qualification, see
Workflow actions
Workflow execution options
Workflow actions
The following table lists some of the actions that active links, filters, and escalations can perform.
For a complete list, see the Types of workflow actions topic.
Workflow actions
Action
Description
Active
Filter
Escalation
link
Change
Field
Changes the appearance of fields. For example, a Change Field action can perform
one or more of these actions:
Moves the cursor or keyboard focus to a field.

Hides or displays a field. For example, an active link might hide all fields related
to telephone problems when users report network problems.
Changes a field's accessibility to read-only, read/write, or disabled.
Changes the color of a field label or trim text.
Changes the menu attached to a character field. For example, if a form for
scheduling a meeting has a field for the building, the menu of meeting rooms
attached to the meeting room field might change to match the specified building.
Refreshes the data in a table field.
Changes the label of a field.
Expands or collapses a collapsible panel field.
Page 98 of 4705
Home
Action
Description
Active
link
Close
Window
Closes the current window.
Message
Prompts with advice, gives reactive information, warns of a particular situation, or

presents an error message and stops the processing of current workflow. Active links
Filter
Escalation
execute on the client, so they can display messages immediately. For example, when
users fill in a particular field, an active link could warn that a related field must be filled
in first. Active link messages can appear in different display formats, such as a dialog
box, the Prompt Bar, or a tooltip. Filters execute on the server, so they are useful for
checking entire transactions and sending error messages or informational messages.
For example, a filter could display a message indicating that the support staff has been
notified about a problem.
Notify
Sends event notifications to users or groups by email, or a custom mechanism, such as

a Windows service that pages users. For example, a filter might notify support staff
when they are assigned a request. Or an escalation might notify the service department
when an asset warranty has expired.

Open
Window
Opens a window of any type in the client. The action can open a New window and load
some default data. Or it can open a Modify window with requests matching a specified
qualification. This action can also open a dialog box. Data can be passed between the
dialog box and the window that calls it. Processing of active links from the calling
window is suspended until the dialog box interaction is completed.
Push
Changes the values of fields in another request to the values in the current request (that
Fields
is, it "pushes" the values from the current request to another request). This action can
also change the value to a keyword or a function. You can use Push Fields to set
values in related requests or to create requests that are associated with the current one.
For example, you can use this action to create multiple work orders for a telephone
connection, a network address, and new furniture when an employee is hired.
Run
Process
Runs a separate process (program) on the server for filters and escalations or on the
Windows client or server for active links. For example, a filter can send a page, or an
active link can launch a browser on a user's desktop.
Service
Works with an AR System web service to obtain external services or with a Set Fields
filter action to consume an internal AR System service.

Set
Fields
Sets fields on a form to specified values. For example, a filter can automatically set the
Status field to Assigned every time a name is entered into the Assigned To field. The
value set in a field can be static (always the same), a keyword value, or a value
retrieved from another data source.
Workflow execution options

Execution options determine when workflow runs. For active links and filters, you specify what
event triggers the workflow; for escalations, you specify the execution schedule for the workflow.
For all workflow components, you can refine the execution option by adding a qualifying statement
that tells the system which set of actions to run if the additional criteria are met and which set to run
if the criteria are not met.
Active link and filter execution options
The following table lists examples of execution options for active links and filters. For a complete list
, see Defining workflow execution options.
Page 99 of 4705
Home
Execution options for active links and filters

Execution
option
Description
Active
link
Button/Menu
Executes when a user selects the button or menu item associated with the active link.
Gain Focus
Executes when a user or a Change Field action moves the cursor to a field.
Display
Executes after a request is loaded into a form but before the request appears in the Details
Filter
Field
pane.
Hover on Field
Executes when a user hovers the mouse pointer over a field, field data, or a field label. To
Hover on Data
Hover on Label
display tooltips, use a Hover execution option to trigger a Message action.
Lose Focus
Executes when a user or a Change Field action moves the cursor out of a field.
Menu Choice
Executes when a user chooses an item from a character menu associated with a specified
field.
Modify
Executes after a user modifies an existing request but before the request is sent to the AR
System server (for active links) or to the database (for filters). An active link with this
execution option does not run during a Modify All operation.
Service
Enables filters to be called by the Service action.
Submit
Executes after a user submits a new request but before the request is sent to the AR System
server (for active links) or to the database (for filters).
Table Refresh
Executes when a user updates a table's contents by loading the field, sorting, refreshing, or
displaying the previous or next part (chunk) of the table.
Window Open
Executes when a user opens a form or dialog box or changes a form to a different mode.
This is especially useful for establishing initial environments. It executes before any data is
loaded into the window.
+
+
Execution options and user actions
Some execution options depend on how a user interacts with fields on the form. For example, if the
user does not click a particular button, that active link does not fire (the user "controls" whether the
active link fires). Use "user-controlled" execution options to provide additional helpful information,
such as a list of nearby printers.
Active links that are not under a user's control, however, fire whenever the user finishes a task.
That is, if the user follows the normal steps, from opening a window through closing the window,
the active links not under explicit user control always fire. (Of course, if a user does not submit or
modify the request, the active links that fire on Submit or Modify do not execute.) Use execution
options that are not controlled by users to ensure that consistent, complete data is maintained
regardless of whether users perform certain actions. For example, to guarantee that every
submitted request includes the host name, an active link could retrieve the host name of the client
and copy it into a field in the form whenever a request is submitted.
Execution order of active links and filters
Page 100 of 4705
Home
Active link execution options have an implicit order in relation to one another and to the interaction
between the client and server. You can use this order to control when the active link runs. For
example:
If field values were required for workflow processing before a request is displayed, you
would set them on Window Open. However, to set any values that you want the user to see
when a request is displayed, you would use the Display execution option.
An active link that runs on Window Open might check the user's permission to open a Modify
All window and, if the user does not have permission, generate an error message,
preventing the window from opening.
More than one active link or filter can run on the same execution option. In this case, you can
specify the order that you want it to fire in relation to the other active links or filters. One reason to
do so is that the output of one active link can affect another active link. By carefully ordering a
group of active links, you can perform very complex operations.
When active links and filters are bundled into guides, execution order within the guides is ignored.
Instead, workflow executes in positional order within a guide. This enables a guide procedure to run
without affecting the order of workflow outside the guide.
Escalation execution options
In contrast to active links and filters, which react to events, escalations respond to the passage of
time. You can trigger an escalation at a specific time, such as every Monday at 6 a.m., or at a time
interval, such as eight hours after each run of the escalation.
When the specified time arrives, the server searches for requests in the database that meet the
escalation's qualification. If it finds any, the server runs the escalation's primary ("if" ) actions for
each matching request. If no requests meet the qualification, the server runs the escalation's
alternative ("else" ) actions, if any, once. The following figure illustrates how escalations work.
How escalations work
Page 101 of 4705
Home
An alternative ("else") action for the example in the figure might be to notify the manager that all
requests comply with the assignment rule. This action would run only if no requests meet the
escalation qualification.
Workflow qualifications
Qualifications in active links, filters, and escalations enable you to define the data condition that
causes the workflow component to take action.
You can use qualifications to check values in fields, the amount of time that has passed since a
specified event occurred, and many other factors. For example, a qualification might check whether
the priority of a request is High or Critical or whether the day is a weekend day.
Qualifications with active links and filters work differently from qualifications with escalations:
Page 102 of 4705
Home
Active link and filter qualifications control which actions, if any, are run for the current request
. For example, an active link can run actions whenever a specific field is filled in (execution
option), or it can run actions whenever the field is filled in and the value in the field is invalid (
qualification).
Escalations are run whenever the scheduled time arrives. The qualification is an essential
part of most escalations, not simply a refinement. It determines the requests on which the
primary ("if" ) escalation actions are run. Without a qualification, the primary actions are run
on every request (record) in the form to which the escalation is attached. For example, if an
escalation simply sent a notification every hour (execution option), the notification would be
meaningless. A meaningful escalation, however, might check every hour (execution option)
whether three or more hours have elapsed since a request was submitted and the request is
unassigned (qualification), and then send a notification listing the unassigned requests to a
manager. If no requests meet the qualification, the escalation might specify alternative ("else
" ) actions that are executed once, such as sending the manager a notice that all requests
comply with the assignment rule. For an illustration of how qualifications are used in
escalations, see How escalations work.
For filters, the qualification can check the value of a field in the database, in the current transaction,
or both. This makes it possible to check whether the value of the field is changing. For example, if
you have a business rule that service desk requests can be closed only if they have been fixed, a
filter could check all transactions that change the status of a request to Closed. If the database
value of the status is Fixed, the request can be modified; otherwise, the change is not allowed.
Keywords in qualifications
A keyword is a variable whose value is defined by AR System. Keyword names are uppercase and
enclosed in dollar signs. For example, $USER$ represents the name of the user who is currently
logged in, $TIMESTAMP$ represents the current date and time, and $OPERATION$ represents the
operation currently in progress.
Keywords are used to build qualifications. Keywords can be used almost anywhere a qualification
can be defined or a value specified:
Defining qualifications for search menus and for workflow. For example, workflow can check
the value of the keyword $OS$ to ensure that the operating system can run a process that
you specify in workflow.
Specifying a value in the Set Fields action.
Defining searches and macros.
For a complete list of keywords, see Keywords.
Fields overview
Fields enable you to control how information is captured and displayed in forms. You can add as
many fields as you need to a form (within the limits of your database) to capture and display the
information required by your application.
Page 103 of 4705
Home
You can use workflow to manipulate the attributes of fields. For example, you can set permissions
for a group of trim fields or active link control fields so that they are inaccessible to certain groups of
users, or you can add tabs in a panel field that are visible to some users (such as managers or
support staff) but not to others.
Use this section to get information about the core fields, field types and its characteristics:
Core fields in a regular form
Field types
Field characteristics
Fields have properties that determine their structure within BMC Remedy AR System. For an
alphabetical list of field properties, see Field properties.
Core fields in a regular form

A regular form automatically contains these core fields.
Request ID Unique tracking number assigned to each request by AR System
Submitter Logon name of the user who submits a request
Create Date Date and time that a request is created
Assigned To Person assigned to handle the request
Last Modified By User who last modified the request
Modified Date Date and time that the request was last modified
Status Current status of the request
Short Description Brief description of the request
Status History Time the request's status was last changed and who changed it. This field
does not appear in forms. To view the information in this field, users must display a request
and choose View > Status History.
These fields provide basic capabilities that most application designers need. For more information,
see Core fields.
BMC Remedy AR System has templates for blank forms and forms with core fields. You cannot
delete core fields from a form created with them, but you can hide them from a user's view and
change their labels, location, and appearance.
The following table shows the meaning of the field label styles :
Field label styles
Style
Description
Bold
Field requires a value default, user-entered, or from workflow when a user submits a request
Italic
Field is automatically populated by AR System
Plain
Field is optional; users can enter information in it or leave it empty
Page 104 of 4705
Home
Field types
The following table provides information about different field types. For more details, see Creating
and managing fields.
Field type
Description
Data
Contains data values stored in database tables. You can set these characteristics of data fields:
Whether users can access the field and, if so, whether they can only view the field or also change its
contents
The type of data that the field can contain (such as characters, integers, dates, or times)
The amount of information that the field can contain (field length)
Whether the field is visible or hidden
Whether the field is enabled or disabled
Whether the field is required, optional, or display-only (A display-only field is a temporary field for which no
space is allocated in the database.)
Where the field appears on the form
How the field is displayed (for example, its label and physical appearance)
How information is entered into the field (for example, by typing or by selecting items from a list or a menu)
The field's default value
Whether fields are indexed for faster searches
Table
Displays data from other requests in the context of the current request. Table field styles are list view, tree view,
cell-based, results list, and alert list.
Attachment
Attaches files to requests
View
Provides a browser window in a form. The browser can display any URL, HTML content, or file format (including
contents of attachments) that is compatible with a browser.
Data
visualization
Augments BMC Remedy AR System with HTML-based content such as web pages, flashboards, and other
graphics that can interact with the field's parent form through workflow
Application
list
Displays a list of entry points. An entry point is a link that users click to open forms on the correct server in the
required mode (New or Search). BMC Remedy AR System automatically generates the contents of the application
list. The entry points that a user sees in the list are only those to which the user has access. Any form that contains
an application list field can be used as a home page . A home page is a single point of access into BMC Remedy
AR System.
Horizontal
and vertical
navigation
Enables users to navigate to the correct screen in an application quickly and easily
Control
Triggers active links. Control fields include buttons, menu items, and toolbar buttons.
Panel
Organizes other fields on forms into smaller containers that can be hidden when not needed. Panel fields can have
various formats, such as tabbed, collapsible, splitter, and accordion.
Trim
Adds boxes, lines, and text to enhance the visual appearance of forms
Field characteristics
All fields in BMC Remedy AR System share the following characteristics in common:
They can be disabled (dimmed) or hidden.
They have a unique field ID and field name.
They can be used in workflow.
Page 105 of 4705
Home
They can have context-sensitive help associated with them to help users learn more about
them.
Their display properties (including their location on a form and their appearance) can be
changed.
Permissions can be set to specify which users can access them.
BMC Remedy AR System automatically records their history, including their owner (the user
who created them), the user who last modified them, and the date and time that they were
last modified.
Field menus overview

Field menus help users enter data and ensure that the data is consistent. You can attach a menu to
any character field (character fields are data fields that hold alphanumeric characters). Menus can
be statically defined, dynamically built by searching BMC Remedy AR System databases and
external databases, or read from text files written by other applications.
Menus are separate objects stored independently of a form. This means that you can create a
single menu and use it for multiple forms and for multiple fields in one form.
BMC Remedy AR System defines these types of menus:
Menu types
Menu
type
Description
Character
Stored and maintained as a list of items in BMC Remedy AR System. These menus are useful for fields that have a
predefined series of choices that change infrequently. They can have submenus.
File
Contains items that are created and maintained in a plain text file. The file can be stored on the system where a client
is running or on the AR System server. File menus are convenient when you do not want to store the data in the AR
System database. To change a file menu, simply update the file; the changes are applied when the menu is refreshed
. File menus can have submenus.
Search
Retrieves information from requests stored in AR System databases. The information is used to build a menu
dynamically in the current form. Search menus are often used when the choices in a menu depend on values entered
in fields on the current form.
SQL
Also retrieves information from databases, but the databases can be outside BMC Remedy AR System. When you
access an SQL menu, BMC Remedy AR System uses an SQL query to extract the data and then generates the menu
from that data.
Data
dictionary
Retrieves lists of fields and forms from an AR System server. These menus are useful for creating special
configuration interfaces. They are generally not used to help users perform their work.
Associations overview
An association is a BMC Action Request (AR) System server object that describes relationships
between entries in BMC Remedy AR System forms. The association enables you to manage
relationships between entries in two forms to support referential integrity, cascade deletes, and
archiving related entries.
Page 106 of 4705
Home
An association defines a relationship between entries in two forms. The relationship can have three
cardinality options: One to One, One to Many, and Many to Many. For one-to-one and one-to-many
relationships, an association between two forms is defined by specifying one form as primary and
another form as secondary. For these relationships, the primary form can have only one entry in the
relationship. For many-to-many relationships, there are no primary and secondary forms.
Note
BMC Remedy AR System associations are used in BMC Remedy ITSM application
primarily for archiving. You can also use these associations with RESTful APIs to get
related entries. For more information, see Operations on entry objects.
The following sections are provided:

Understanding the value of associations
Cardinality
Relationships
Type of associations
Qualifications
Permissions
Understanding the value of associations

Associations can be used to describe the data model for an application. You can understand an
application easier with associations. Enforced associations can eliminate the need to create
workflow to restrict operations or to remove related data when an entry is deleted. Reducing the
amount of workflow needed for an application again makes it easier to understand your applications
.
Associations can also be used to govern the behavior of archive definitions. For more information,
see Defining associations to follow.
Cardinality
Each association has cardinality, which dictates how the entries in the two forms are related. The
options are:
One to One This cardinality describes a relationship in which an entry from the primary
form can be related to exactly zero or one entry in the secondary form.
One to Many This cardinality describes a relationship in which an entry from the primary
form can be related to zero or more entries in the secondary form.
Many to Many This cardinality describes a relationship in which an entry from the primary
form can be related to zero or more entries on the secondary form and an entry from the
secondary form can be related to zero or more entries on the primary form.
Page 107 of 4705
Home
Note
All cardinality options may have an entry that is related to no other entries. For example, a
one-to-one relationship between an employee and email address includes the possibility
that an employee might not have any email addresses.
Relationships
Data relationships defined by associations may be enforced (strong) or not enforced (weak).
Enforced associations
Page 108 of 4705
Home
If an association is defined as enforced, the BMC Remedy AR System server ensures data integrity
is maintained. Data integrity means that the server will enforce the cardinality of the association and
will ensure referential integrity. Thus, an entry will not be able to refer to another entry that does not
exist.
Note
Associations enforced on forms are also enforced on the archives of those forms.
Only one-to-one and one-to-many cardinality can be enforced. You cannot create an enforced
many-to-many relationship in BMC Remedy AR System. The server performs the following
functions for the enforced association:
If an entry is deleted from the primary form, the server deletes all related entries from the
secondary form (cascade delete).
Server does not allow duplicate primary key values in the primary form. For example, each
employee must have unique ID.
Server does not allow entries in the secondary form with invalid foreign key values. For
example, an entry in the contact form must reference a valid employee.
Server does not allow changing primary key values in the primary form if they are referenced
in a secondary form. For example, you cannot change an employee ID if that employee is
referenced in a birth information form.
For one to one associations, the server does not allow creation of entries in the secondary
form if that breaks the cardinality defined by associations. For example, it will not allow
creation of a second birthday entry for the same employee.
Note
If an enforced association is created between forms that already contain data, it is not
necessary that the existing data should have referential integrity. However, any changes
to the data after the association is created will follow enforcement and should have
referential integrity.
Unenforced associations
If an association is not enforced, the BMC Remedy AR System server allows creation of records
even if the creation breaks the cardinality defined by the association or the referential integrity. If an
association is not enforced, the server does not perform the actions listed above for enforced
associations.
Page 109 of 4705
Home
Unenforced associations provide a way to describe data relationships that are not directly enforced
by the server. These associations may be otherwise enforced, by defining workflows in BMC
Note
BMC Remedy Data import tool has an option to disable association enforcement while
importing data. For more information, see Form mapping data options. ARMergeEntry api
provides an option to disable association enforcement as well. For more information, see
ARMergeEntry.
Type of associations
Entries in forms may contain direct references to each other, or may be related through a third form
that contains references to each of the related entries. The association type describes which of
these approaches is used.
Association
type
Cardinality
Can be
Enforced
?
Description
Direct
One to
One
Yes
Direct associations are primary key and foreign key associations between two forms.
Multiple fields from main form can be used as a primary key and similarly multiple fields
from the secondary form can be used as a foreign key. In other words, each field of the
primary key maps to a field in the foreign key and is called direct association.
One to
Many
Indirect
One to
One
Yes
One to
Many
Many to
Many
No
These types of associations are called external associations where the associations are
created by using a third form. This third form, called an association form, stores the
foreign key for both the primary and secondary forms. Multiple fields from the primary
form can be mapped to the same number of fields on the association form and similarly
multiple fields from the secondary form can be mapped to the same number of fields on
association form.
Direct associations
Direct associations involve only two forms, and require that references from one form to the other
use only data that is present on the forms. Direct associations can be used for one-to-one and
one-to-many relationships. They cannot be used for many-to-many relationships. In the following
example, the Employee Phone form directly holds reference to Emp ID of the Employee form.
Employee
Emp details
Employee Phone
Emp ID
Emp ID
Phone details
Indirect associations
Page 110 of 4705
Home
Indirect associations include a third form that contains references to each of the related forms.
Entries in the two related forms in an indirect association do not have references to each other.
Indirect associations can be used for any kind of relationship, and only an indirect association can
be used for a many-to-many relationship. In the following example, the Employee-Department form
(third form) contains references to the two related forms: Employee and Department.
Note
Whether the association is enforced or not, for an indirect association, the server will
always delete related entries from association form if an entry is deleted either from
primary or secondary form.
Employee
Emp details
Emp ID
Employee-Department
Department
Emp ID
Dept ID
Dept ID
Dept Info
Qualifications
When defining an association, you have the option of specifying a qualification for each of the forms
involved. Qualifications allow different relationships between entries in the same two forms or the
storage of multiple relationships in a single indirect association form.
When you specify qualifications, only entries matching the qualification are related to the
association. For example, you might have a Phone details form that includes a Phone Type field
indicating that an entry is an office phone number or another type of phone number. You could then
create different associations between an employee form and the phone details form:
one-to-one association between an employee and an office phone
one-to-many association between an employee and all other phones
You would add a qualification in the first association requiring that the field on the telephone
number form be office phone option.
Permissions
An Association object does not have any permissions. Only administrators are allowed to create,
modify and delete associations. All other users can view an association, if they have access for
viewing the all the fields and forms used in that association.
Video: Introduction to the Association Server Object

This video explains how the Association Object can be used to establish relationships between
entries in two BMC Remedy AR System forms to support referential integrity, cascade deletes, and
archiving related entries.
Page 111 of 4705
Home
Six minutes 25 seconds.
Related topic
Using associations
Application localization
Localization is the process of customizing an application for use in various languages, countries,
and cultures. BMC Remedy AR System provides an internationalized environment for building,
testing, and localizing applications.
A locale describes the language, country setting, and other characteristics of the local system's
user interface. You can create a BMC Remedy AR System application to run in a particular locale,
or you can make your application simultaneously available in multiple locales.
The development environment enables you to localize all aspects of the user interface:
Language used for labels, messages, help text, reports, menus, and any other words that
are part of a form's user interface
Separator symbol for decimal numbers that include a fraction
Separator symbol for numbers greater than 999
Format for dates and times
Layout, colors, and images
You can store each localized version of a form as a view. Therefore, the same application can
provide separate user interfaces (views) for British English, Australian English, Mexican Spanish,
and Peruvian Spanish.
Note
Page 112 of 4705
Home
Although the user interface is tailored to each user's locale, the data and workflow are the
same for all users. Therefore, you need to agree on the language for the data before the
application is made available.
The localization features are automatic for the user and easy to implement for the application
builder. To localize an application for a given locale, an administrator need create views only for
that locale and add corresponding messages to the message catalog. Utilities are available to
assist with this work. See Localizing an application to other languages.
An example BMC Remedy AR System application

This section explains the basic concepts of BMC Remedy AR System by showing how a sample
organization - a wild animal park - might plan and design an BMC Remedy AR System application.
Like any business, the park needs to take a systematic approach to automating its processes. This
section walks you through the planning process that the hypothetical park staff uses to evaluate
and address its business needs.
Considerations
Goals of the animal tracking application
About the wild animal park
Putting the example application to work
Considerations
After defining the application goals, the staff begins more detailed planning. This section discusses
various questions that any organization needs to consider to create a useful application, including
data analysis, workflow analysis, identifying the business rules to be enforced, mapping the
business rules to workflow components, and considering whether any integrations are required.
Note
The planning and design process is thoroughly covered in the "BMC Remedy AR System
7.x: Application Requirements Analysis, Design, and Development" course offered by
BMC. See http://www.bmc.com/education.
Analyzing data
Analyzing workflow
Defining business rules
Mapping business rules to workflow components
Considering integrations
Page 113 of 4705
Home
Analyzing data
As the park staff members begin to plan their animal management application, they analyze the
data by answering these questions:
What types of data do they need to capture?
How is this data stored in their current system (for example, in a legacy database or in paper
forms)?
What forms (main and supporting) and fields need to be created?
Should they include menus on the forms and, if so, which kinds are most appropriate to help
staff members fill in fields?
The staff determines that they need these forms (shown in the following figure) to capture
information:
Animal form Contains detailed information about each animal. The staff considers using
panel fields to organize the form modularly, keeping related fields together.
Species Info form Contains details about a particular species, such as feeding
requirements, life span, medical needs, and whether it is endangered. This is a supporting
form.
Feeding form Contains information about each animal's feeding schedule.
Enclosure form Contains information about the number and types of animals each
enclosure can hold and so forth.
Medical History form Contains the complete medical history of each animal.
Former Resident form Contains information about animals that no longer reside in the
park.
Forms for animal tracking application
Page 114 of 4705
Home
Analyzing workflow
Next, the staff considers the park's current organizational processes:
What are the processes?
What are the stages or steps of each process?
Which groups of people participate in the processes?
To manage, access, and track the processes, what information do the groups need?
Some of the BMC Remedy AR System groups or roles that the park needs are:
Veterinarians, who provide health care for the animals.
Animal handlers, who provide day-to-day care for the animals.
Curators, who handle acquisitions and transfers.
Horticulturists, who maintain the animals' naturalistic habitats.
Researchers, who conduct animal-related studies.
Appropriate permissions will be assigned to each group or role according to the information that
they need to access.
Page 115 of 4705
Home
Defining business rules

After examining their business processes, the staff members also consider their business rules, the
fundamental policies that govern day-to-day life at the park. The rules frequently provide the basis
for making important decisions.
For example, one of the rules might be that every animal must be checked by a veterinarian within
24 hours of arrival. If the rule is broken, that might indicate a need to hire more medical staff or to
increase clinic capacity.
Questions about business rules include:
What conditions and events require decisions and actions?
What should happen when various conditions or events occur?
What is the flow of information through the existing systems?
Business rules for the park include:
Animals will be not be kept in temporary enclosures longer than 48 hours.
Specially trained animal handlers will be notified immediately if a dangerous animal escapes.
Every animal must be checked by a veterinarian within 24 hours of arrival.
Mapping business rules to workflow components

Next, the park determines how to translate its business workflow (rules and processes) into BMC
Remedy AR System workflow components:
Which processes can be accomplished by using active links?
When would it make more sense to use a filter?
What types of escalations are needed to enforce business rules?
Some of the workflow components that the park needs are:
A filter to notify animal handlers whenever an animal needs to be moved.
Active links that help users fill out forms.
An escalation to enforce the rule that animals must be checked by a veterinarian within 24
hours of arrival.
An escalation to notify keepers when an animal has not been fed within one hour of its
scheduled feeding time.
Considering integrations
The staff considers what other software products or databases must initially be integrated into the
application and what future integrations are desirable:
The staff must be able to enter data while they are out in the park, perhaps using handheld
devices.
Page 116 of 4705
Home
Future integration with a sister zoo must be possible.

Integration with an international database of endangered species is also necessary, partly to
locate new individual animals that can contribute to the gene pool at the park.
Eventually, the staff might want to integrate information about the botanical gardens at the
park, although this could be maintained separately.
Goals of the animal tracking application

The park needs to accomplish these goals with the animal tracking application:
Track the type and number of animals grouped together in enclosures.
Track births, deaths, acquisitions, trades, and sales.
Track daily observations of each animal, including behavior and medical condition.
Track the complete medical history of each animal, including preventive care such as dental
work, vaccinations, and parasite checks.
Track animal feeding.
Immediately alert the veterinary staff about medical emergencies.
Alert the animal handlers if any animal escapes its enclosure.
All these goals relate to tracking animals throughout their life at the park, as shown in the following
figure.
Animal tracking overview
Page 117 of 4705
Home
About the wild animal park

For many years, the wild animal park grew successfully with paper-based record keeping combined
with isolated computer-based procedures. Recently, however, employees noticed a number of
redundant or inefficient processes, so the park staff decided to use BMC Remedy AR System to
automate the following processes:
Tracking and managing animals associated with the park
Tracking and managing public relations, such as attendance statistics, public inquiries,
membership renewals, and group tour information
Tracking and managing the maintenance of on-site visitor facilities, including snack bars,
restrooms, first-aid stations, and park transit systems
Managing the botanical gardens adjacent to the park
This section focuses on the first application, managing and tracking animals.
Page 118 of 4705
Home
Putting the example application to work

After the planning and design process, the park develops an application that covers its diverse
requirements. When staff members begin using the application, they note which features work well
and which ones need adjustment. Developers make changes to the application based on that
feedback.
Example application - A tiger is acquired
Example application - The tiger is injured
Example application - The tiger is traded to another zoo
Example application - A tiger is acquired

This section describes an example in which the hypothetical wild animal park acquires a tiger. This
scenario illustrates a complete process, but not every component of the process is discussed in
detail.
As shown in the following figure, when a Sumatran tiger named Karuna is obtained, a staffer fills in
the Animal form, and then clicks a button called List Enclosures. An active link opens a dialog box
displaying the Enclosure form with a table field that lists enclosure information, including availability
and habitat. The staffer can double-click any enclosure in the list to get more information.
Next, the staffer selects an appropriate choice in this case, enclosure 16 and submits the
request. A filter notifies the Animal Handlers group and sends a message to inform the staffer that
the appropriate persons have been notified. In addition, the Status field changes from New to Move
Pending.
During trial runs of the system, the application developer realizes that the animal handlers are
frequently away from their computers and rarely check email. The developer integrates the
application with a paging program and has the filter notify the handlers about new animals with a
page. Handlers can then use their cell phones to get information about their assigned tasks.
Gary from Animal Handlers receives a page that says a new tiger must be moved from the
temporary cages to enclosure 16.
After he transfers the tiger, Gary changes the Status field from Move Pending to Permanent. When
he saves his changes, workflow components create new requests in related forms and notify the
Veterinarian group and the Animal Handlers group to begin the care and feeding of the new animal.
These requests and notifications illustrate one way of handling work orders in AR System.
Active link and filter in the animal tracking application
Page 119 of 4705
Home
Tip
This example is similar to moves, adds, and changes (MAC) in an employee services
application.
Example application - The tiger is injured

This section describes an example in which the tiger at the hypothetical wild animal park is injured.
This scenario illustrates a complete process, but not every component of the process is discussed
in detail.
One morning when the keepers are making their daily rounds, they notice that the tiger, Karuna,
has been injured, so they notify the veterinarians. A veterinarian looks at the Animal form and
checks a table field that contains data from the Medical History form, as illustrated in the following
figure. She discovers that Karuna has no history of serious injury or illness.
To be treated, Karuna must be tranquilized and moved to the veterinary hospital for surgery. He
Page 120 of 4705
Home
has been tranquilized before without incident as indicated by the Tranquilizer Notes field on the
Animal form, so the veterinarian computes the dosage and sets out with several animal handlers to
bring in the tiger.
Table field in the animal tracking application
During the prototyping phase, staffers had to open the Medical History form separately to learn
about Karuna's record with tranquilizers. The veterinary staff pointed out that they wanted that
important information readily available during an emergency. So the Tranquilizer Notes field was
added to the Animal form, and a filter that executes on Submit was added to post a message to the
veterinarians, reminding them to update the Tranquilizer Notes if necessary.
Tip
This process is similar to handling a customer call in a technical support application. The
technical support representatives might decide that they need important information about
a customer on a main form rather than on a supporting form.
Example application - The tiger is traded to another zoo

This section describes an example in which the tiger, named Karuna, at the hypothetical wild
animal park is transferred to a different zoo. This scenario illustrates a complete process, but not
every component of the process is discussed in detail.
After several years, the animal park determines that it should have a different male tiger to maintain
genetic diversity in its tiger population. By examining a database maintained by zoos worldwide, the
staff discovers a tiger that is available and has no common ancestors with Karuna or with the park's
female tigers. They decide to trade Karuna, and a staffer changes Karuna's status from Permanent
to Trade Pending, thereby triggering the same notification filter that was used when Karuna arrived.
This time, it notifies the animal handlers to move Karuna to a temporary cage, as shown in the
following figure.
Page 121 of 4705
Home
Notifications in the animal tracking application

After Karuna leaves the park, his status is changed to Traded. When the changed request is
submitted, a filter uses a Push Fields action to move all of Karuna's data from the Animal form to
the Former Resident form, as shown in the following figure.
Push Fields action used in the animal tracking application
The Medical History form is not archived or changed because the staff might, at any point, want
information from the medical records. For example, they might want information about all tiger
surgeries performed at the park.
Tip
This process is similar to retiring an asset in an asset management application: you need
to track the problem history of an asset during its active use and after its retirement.
Archiving overview
The archive feature of BMC Remedy AR System provides a convenient way to periodically store
data (not definitions) from a form to an archive form; this reduces the amount of data accessed
during searches on the main form, thus improving system performance. Archiving applies to all
Page 122 of 4705
Home
types of forms, except display-only forms, vendor forms, and join forms. You can manage the
production system efficiently and utilize the available infrastructure and resources optimally. When
you archive your data, you can improve system performance and enable data retention.
By archiving, the main application has fewer records which results in quicker searches and better
performance, while the records are still archived. You can also reduce the database size by
periodically extracting archived data.
The main form is the form on which archive is set (data is read from this form), and the archive form
is the form to which data is copied. It is important that when you archive the main form, the related
forms are also archived. For providing ability to archive related data, you can explicitly create
associations between forms in the Developer Studio. For more information, see Defining
associations to follow.
The following image displays the concept of archiving in BMC Remedy AR System.
Page 123 of 4705
Home
Related topics
To know more about these concepts, see BMC Remedy archiving concepts.
To know more about properties for form level changes, see Configuring data archiving for a
form.
Archiving concepts
This topic provide information about the archiving concepts introduced in BMC Remedy AR System
9.0.
AR System Archive Manager console
Age qualification
Page 124 of 4705
Home
Associations to follow
Include in archive policy
Archive interval
AR System Archive Manager console

Starting 9.0 release, you can manage archive definitions through forms. A new AR System
Archive Manager console uses the AR System Archive Policy form to allow authorized users to
enable, disable, describe, and control the age of archived records. It also allows the user to perform
an archive on demand, even if the console has disabled the archive.
The Archive Manager console displays the values from the archive definition, and allows the user to
override or accept those values. The archive definition controls the appearance of an archive in the
console, which is an element of the form definition that can be accessed using BMC Remedy
Developer Studio.
You can also export and delete your archived data directly from your application using the AR
System Archive Manager console now. For more information, see Managing the archiving process.
Age qualification
This is a new parameter added in the archive definition, which specifies that the records should be
archived when they have reached a specific age. The definition includes the field on the form that is
used to determine the records age, and the age in number of days after which records should be
archived. You can set this definition on the archive panel for each form. For more information, see
Configuring data archiving for a form.
The age specified in the definition appears in the Archive Manager console as well. You can
choose to override the value from the console.
Note
Before 9.0 release, the archive qualifications included specification of the age at which
entries were archived, along with other information that indicated which records should be
archived.
After upgrading to 9.0 release, the existing archive definitions will be updated so that they
appear in the Archive Manager console with an age specified as zero. Because the
qualification still includes an age component, the records are archived at the greater age
in the qualification and at the age specified in the console. By default, the archiving
happens as before, but the age of the archived records will not be entirely controlled from
the console. To resolve this issue, you can adjust the definitions so that the age of records
is not added in the qualifier.
Page 125 of 4705
Home
Associations to follow
The archive definition includes a list of associations that will be followed when an entry on the form
is archived. The associated records in other forms will be archived with the original entry in a single
transaction, so that a parent and all of its related child records can be archived together. For more
information about understanding associations, see Associations overview.
For more information and examples about associations to follow, see Defining associations to
follow.
Note
Indirect associations having Many to Many cardinality cannot be followed for archiving.
Even if you select those associations, they will be ignored during the archiving process.
Include in archive policy

This flag indicates that an archive should be exposed in the Archive Manager console and its
records are examined at the scheduled interval. The flag should be set for definitions that describe
the entries that will not be archived through associations from other entries.
If a form contains some records that are archived because they are associated with other records,
and others that are not associated then the form definition should include a qualifier that applies
only to the unassociated records.
If records in a form are archived only because they are associated with other records, then this flag
should not be set.
When records in the form are archived because they are associated with other records, the
qualification in the forms archive definition is ignored.
Archive interval
Before 9.0 release, each archive definition in a form included a schedule on which the archive was
run.
Starting 9.0 release, this definition is removed and all archives in the policy form are archived at the
same time, based on the single archive interval specified for all archives. For more information, see
Setting global archive interval for forms .
Architecture
Use this section to understand the architecture of BMC Remedy AR System and its related
components.
BMC Remedy AR System architecture
Page 126 of 4705
Home
AR System server architecture and scalability

AR System database server
BMC Remedy Mid Tier architecture
BMC Remedy Migrator architecture
BMC Remedy AR System web services architecture
BMC Remedy AR System API architecture

Use this section to understand the BMC Remedy AR System architecture and its components.
BMC Remedy AR System functional components
BMC Remedy AR System client server communication
BMC Remedy AR System clients
BMC Remedy AR System functional components

BMC Remedy AR System is based on a client/server architecture and includes the following
functional environments:
Presentation The presentation piece of BMC Remedy AR System is responsible for
presenting services and displaying data to clients through various interfaces. These
interfaces include:
browsers
cell phones
PCs
Personal Data Assistants (PDAs)
BMC Remedy Developer Studio
API programs
All these interfaces enable you to access BMC Remedy AR System. Clients can be
thought of as consumers of services that the AR System server provides.
Business processing This portion of the architecture includes:
BMC Remedy Mid Tier
AR System server
Server functions such as the Distributed Server Option (DSO), and BMC Remedy
Approval Server
The BMC Atrium Integration Engine (AIE) or Atrium Integrator (AI)
Web services
The business processing piece of BMC Remedy AR System is responsible for
providing services to clients and processing the data entered through clients.
Applications that reside within the business processing environment act as liaisons for
the clients and the database, enforcing the rules of your business processes.
Page 127 of 4705
Home
Data storage The data storage element contains the actual data for the system. BMC
Remedy AR System supports DB2, Oracle, Sybase, and Microsoft SQL Server databases.
For each of the relational databases, tables owned by other systems can be referenced as if
they were owned by BMC Remedy AR System. In addition, ARDBC plug-ins can be created
and configured to enable access to data stored outside the database as if it were in tables
owned by BMC Remedy AR System.
Within these functional environments, several system components work together to provide power,
flexibility, and scalability.
The following figure depicts the relationship among the components that reside within each of the
functional environments of the BMC Remedy AR System architecture. Notice that no definitive
starting and ending point separates the environments because their functions sometimes overlap.
BMC Remedy AR System components
Distributed environments provide scalability

Use BMC Remedy Distributed Server Option (DSO) to build large-scale, distributed environments
that behave like a single virtual system. DSO enables you to share common information among
servers and to keep that information consistent.
For example, as illustrated in the following figure, you can transfer copies of a request to other
servers and ensure that any changes made to the copies are also made to the original request. The
way that you define the processes for transferring information is similar to the way that you define
business processes for an application. First, managers at each site must agree on what information
to transfer from one application to another, what conditions drive transfers, and which sites control
the ability to update a record. An administrator at each site then uses DSO to implement these
decisions.
Page 128 of 4705
Home
BMC Remedy AR System in a distributed environment

Heterogeneous environment provides flexibility

Because the multiple layers of BMC Remedy AR System are independent of one another, you can
combine operating system platforms to fulfill different functions. The heterogeneous environment
enables you to mix and match client and server platforms. For example:
BMC Remedy Developer Studio on a computer running Windows can manage forms on a
UNIX or Linux server.
Browsers can use a Windows-based mid tier to access forms on a UNIX server.
An AR System server on Windows can interact with a database on UNIX.

Use this section to learn about the overall architecture of BMC Remedy AR System and understand
the conceptual overview of the components in BMC Remedy AR System.
BMC Remedy AR System is based on a multitiered client/server architecture that includes the client
tier, the mid tier, the server tier, and the data tier. The following figure shows the different tiers of
Page 129 of 4705
Home
Client tier Contains AR System clients. Most clients present information to application
users and receive input from them, but the tools for migration and application development
are also clients.
Mid tier Contains components and add-in services that run on a web server, enabling
users to view applications on the web.
Server tier Contains the BMC Remedy AR System server, which controls workflow
processes and access to databases and other data sources in the data tier. This tier also
contains server-side applications (such as Approval Server, Email Engine, and the BMC
Remedy Flashboards server) and the C and Oracle Java plug-in servers with plug-ins.
Data tier Contains database servers and other data sources that can be accessed by the
BMC Remedy AR System server. The database server acts as the data storage and retrieval
engine.
AR System clients provide the user interface. The BMC Remedy Mid Tier makes the user interface
available in browsers. The AR System server implements the workflow functions, access control,
and flow of data into and out of the database. The database server acts as a data storage and
retrieval engine. (For information about supported platforms, see Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation.)
BMC Remedy AR System multitier architecture
Page 130 of 4705
Home
BMC Remedy AR System client server communication

The following section explains how BMC Remedy AR System communicates with clients and server
.
Communications between clients and the AR System server
Communications between AR System servers and database servers
Many-to-many connections
Communications between clients and the AR System server

All clients of the AR System server communicate with the server by using remote procedure calls (
RPCs) on top of a TCP/IP transport stack. The type of RPC is the Oracle ONC RPC. TCP/IP
networks are the de facto standard for corporate and Internet communications. The RPC
mechanism is used because it is a "lightweight" transport that uses minimal network bandwidth, yet
provides robust communications services. It can function over slower dial-up network links and
high-speed internets and intranets, and is supported over most of the wireless networking
technologies. The AR System web server communicates with the browsers using HTTP (Hypertext
Transfer Protocol) or HTTPS (Secure HTTP).
Communications between AR System servers and database servers

From the perspective of the database server, the AR System server is a database client. BMC
Remedy AR System uses the database client libraries from the various databases. When an AR
System server is installed, the installer specifies the type and location of the database server, and
the proper database client is enabled. AR System servers communicate with the database servers
through whatever inter-process communications (IPC) mechanism the database client uses.
Examples include SQL*Net for Oracle and OpenClient for Sybase. Some database engines are
Page 131 of 4705
Home
multithreaded. This means that the database can perform multiple transactions simultaneously. In
BMC Remedy AR System, the arserverd server process is also multithreaded. Each of these
arserverd threads is connected to a different thread in the database engine. This provides
tremendous data throughput and system scalability.
Many-to-many connections
In an BMC Remedy AR System environment, one AR System server can theoretically support any
number of AR System client connections (limited by network bandwidth and server host and
database performance). The clients can be on any mix of platforms. Similarly, an AR System client
can be connected to any number of servers at the same time. These servers can be any mix of
server hosts and underlying database engines. In an environment with multiple AR System servers,
the Distributed Server Option (DSO) can be added to share common information among servers
and keep that information consistent. DSO also enables records to be forwarded between servers if
workflow determines that the record should be transferred. This permits building large-scale
distributed support environments that behave as a single virtual system. Some of the many uses of
DSO include:
Transferring requests to the location at which they can be processed.
Transferring requests between regions in a 24-hour, 7-days-per-week customer support
environment.
Creating a distributed knowledge base so that problem-solving information can be
referenced at any location.
Archiving old requests to a reporting server to maximize the performance of the production
server.
Many-to-many architecture

BMC Remedy AR System clients provide user interface facilities available from various platforms,
including the Web. BMC Remedy AR System clients are available for a number of operating system
environments, as listed in BMC Remedy AR System client server architecture . For each operating
systems, the client is composed of a set of native applications (tools) that use the standard user
interface conventions for that environment. Individual users can run these tools as necessary.
Page 132 of 4705
Home
BMC Remedy AR System clients can be broadly divided into user client and developer clients.
User clients
Through the BMC Remedy Mid Tier, users can access BMC Remedy AR System in a browser.
Using the web-based interface, users can submit and modify new requests, to search for
information about requests, and to generate reports. Web pages are written in JSP and rendered in
JavaScript and HTML.
The following table summarizes the main clients used to perform administrative, user and
development tasks.
Client
Tasks
Administrator tasks:
browser
Create groups and roles.
Create users and assign licenses.
Manage AR System server settings and licenses.
User tasks:
Access BMC Remedy AR System forms and applications to create, submit, search and modify requests.
Receive and respond to AR System notifications
Chart data
Generate reports
Display alerts in the Alert List form, which can be refreshed automatically at specified intervals or manually at
any time.
Search records, run or generate reports, view flashboards
Developer clients
The developer clients are used to create, modify, and extend BMC Remedy AR System
applications.
Client
Tasks
Developer tasks:
Create and update application, forms, and workflow.
BMC Remedy Mid Tier

Configuration Tool
Modify mid tier settings for AR System servers, passwords, logging, caching, and
authenticating web services.
Specify home page and preference and catalog servers.
BMC Remedy Data Import
Import AR System data from one AR System server to another.
Load external data into the BMC Remedy AR System database.
Map between the columns in the external data set and the fields in the BMC Remedy
AR System form.
BMC Remedy Data Import is available for Windows.
Page 133 of 4705
Home
Client
Tasks
Import/export command line

interface (CLI)
Connect to the AR System server to import and export object definitions without the
graphical user interface of BMC Remedy Developer Studio.
Automate tasks.

Command Line Interface (CLI)
Connect to the AR System server to import data without the graphical user interface
of BMC Remedy Data Import.
Automate tasks.
BMC Remedy Migrator

Migrate applications, objects, and data between servers, servers and files, or files.
Reduce the difficulty and time required to synchronize AR System servers in
development and production environments.
Note
For limitations on using BMC Remedy Migrator with other BMC applications,
see BMC Remedy Migrator known issues in version 8.1.00.
Integration clients
BMC and its partners also offer the following tools for expanding the capabilities of core BMC
Remedy AR System. These tools act as clients of BMC Remedy AR System.
BMC Atrium Integration Engine (AIE )
BMC Knowledge Management
Network management platform integration accessories
Systems management integration utilities
See AR System and web services introduction .
AR System server architecture and scalability

BMC Remedy AR System uses servers to manage data. The following table summarizes the main
servers.
Server
Use
AR System
server
Processes data it receives from AR System clients, and passes the data to the database server to be stored.
Database
Stores definitions and data for the AR System server.
Web server
Serves as a repository for web applications. Displays the appropriate page to an authorized user.
For more information about AR System server, see:

AR System server architecture components
Page 134 of 4705
Home
AR System server multithread architecture

AR System server queues
AR System server threads
AR System server processes
For more information about configuring AR System servers, see:
Configuring server groups
AR System server architecture components

The main components of the AR System server architecture are:
Application programming interface (API) A set of functions and data structures that
provide application programmers with access to the full functionality of a product. Developers
can create clients written in C or Java. The BMC Remedy AR System APIs are documented
in the Developing an API program and in the ardocVerNum.jar file located in the
ARSystemServerInstallDir\Arserver\api\doc folder (Windows) or the
ARSystemServerInstallDir/Arserver/api/doc folder (UNIX).
Access control and data validation A security feature in which BMC Remedy AR
System administrators limit user access to forms, to specific fields within a form, to specific
functions within the system, and to data stored within the system.
Alerts A client program that functions as a "desktop pager." This component of the AR
System server supports desktop pages such as flashing icons, audible beeps, sound files,
and message windows. For example, it can display a message alerting help desk personnel
that a problem was assigned to them.
For more information about alerts, see Using alerts.
Filters Actions performed on the AR System server, which is the portion of the software
that controls the flow of requests to an underlying database. As a request is processed by
the server, the filter actions take place. Filters enable you to implement constraints, make
decisions, and take action when operations are performed on data stored in BMC Remedy
AR System.
Escalations Actions performed on the server at specified times or time intervals. They
are automated, time-based processes that search for requests that match certain criteria and
take action based on the results of the search.
BMC Remedy AR SystemFilter (AR Filter) API Plug-In A filter that offers a
programming interface directly invoked by filter workflow. This provides a flexible and
efficient mechanism for communicating with various applications or web services. Use of
plug-ins reduces system overhead. AR filter plug-ins also apply to escalations.
See AR filter API plug-ins introduction.
BMC Remedy AR SystemExternal Authentication (AREA) A process that accesses
network directory services and other authentication services to verify user login name and
password information. When you use an AREA plug-in, you do not need to maintain
duplicate user authentication data in the BMC Remedy AR System directories because the
Page 135 of 4705
Home
AR System server can access user identification information and user passwords at many
locations.
See AR System external authentication.
View form A form that enables BMC Remedy AR System to point to and access data in a
database table created outside BMC Remedy AR System. The table can be in the same
database or in any other database accessible from the current BMC Remedy AR System
database.
See View forms.
Vendor form A form that enables BMC Remedy AR System to access arbitrary external
data sources through the use of an ARDBC (BMC Remedy AR System Database
Connectivity) plug-in. This type of form provides for easy integration with external data
without replicating the data.
See Vendor forms introduction.
Database servers The BMC Remedy AR System uses standard relational databases for
storing and retrieving data. Architecturally, the database server is a set of processes that are
completely separate from the AR System server processes. Physically, the database server
processes can be running on the same computer as the AR System server or on a different
computer. The database server can be run on any platform that the particular database
supports.
The following figure depicts the infrastructure of the AR System server.
AR System server infrastructure
Page 136 of 4705
Home
AR System server groups

To provide scalability and increase reliability, you can connect a group of AR System servers to the
same database and manage them as a unit by configuring a server group. Server groups act as a
single server to support the applications that they run. Servers in the server group can be
configured to spread the load of shared services, and they can provide backup to each other to
ensure that those services are always available.
AR System server multithread architecture

BMC Remedy AR System is built to handle high loads and a large user base. It supports clustered
configurations with multiple AR System server instances serving a single user base, as well as a
distributed architecture where you can set up independent or groups of clustered servers in
separate locations.
The AR System multithreaded server is scalable from a single thread performing all server
functions to multiple threads, each performing specific functions. The threads adapt to the
configuration parameters defined, and they distribute the load. You determine what amount of
operating system resources to dedicate to BMC Remedy AR System.
The following figure shows multithreaded architecture uses queues and threads. The following
sections describe how queues and threads function in the AR System server.
Multithreaded server architecture
Page 137 of 4705
Home
64 bit AR System Servers

AR System server binary is compiled as a native 64-bit executable for Windows x64, Oracle Solaris
, HP-UX on Itanium, AIX, and Linux and can now take advantage of the 64-bit address space on 64
-bit operating systems. This provides enhanced server reliability in enterprise environments.
Note
For 64-bit Windows operating systems and production environments, the 64-bit Windows
version of AR System is required.
3 GB switch for Microsoft Windows 2003

While processing any administrative operations, AR System server creates a copy of the server
cache, if the cache size is more than 1 GB (typically when the entire ITSM Suite is installed). On a
32-bit Windows operating system, the copy cache operation exceeds the 2 GB limit of user-mode
process memory and server gets malloc error. It is recommended to increase the user-mode
process memory to 3 GB, by using the operating system startup switch to avoid or reduce malloc
errors. The 3 GB switch is used for this allocation change. The switch is entered in the system's
boot.ini file and takes effect after a operating system restart.
Note
The 3 GB switch is applicable for a 32-bit operating system only.

The 32-bit Windows version of AR System is only supported on 32-bit Windows
operating systems and in non-production environments (e.g. Proof-of-Concept,
Demo, Development etc.).
AR System server queues

A queue is a meeting point where remote procedure calls (RPCs) wait to be handled by the worker
threads that process the RPCs. When a queue is created, it automatically starts the minimum
number of threads specified for its thread type. The default for this setting is 1. See BMC Remedy
AR System Threads.
The following table lists the types of BMC Remedy AR System queues. Each queue has an RPC
program number associated with it.
Queues and related RPC program numbers
Page 138 of 4705
Home
Queue type
RPC program number
Admin
390600
Alert
390601
Full Text Indexing
390602
Escalation
390603
Fast
390620
List
390635
Private
390621-390634, 390636-390669, 390680-390694
Note
Administration, alert, escalation, fast, and list queues use a fixed RPC program number.
Private queues, however, can be configured to use any RPC program number within the
ranges of RPC program numbers reserved for private queues.
The following sections describe the different types of queues.

Administration queue
Alert queue
Full Text Indexing queue
Escalation queue
Fast queue
List queue
Private queues
Administration queue
The administration (admin) queue is the only BMC Remedy AR System queue that can perform
every operation within the system. It performs all administrative restructuring operations,
guaranteeing the serialization and integrity of all restructuring operations. This queue can have only
one thread.
All servers include an admin queue, which is the default server setting. Because an admin queue
has a single thread available to handle requests, a server that has only an admin queue (and no
fast or list queues) functions as a single-threaded server. While the admin queue handles all
administrative functions, it can also perform the functions of all other queues if no other queues are
configured. If no other queues are configured, all requests are placed in the admin queue.
Page 139 of 4705
Home
Alert queue
The alert queue handles all alerts sent to registered clients. The alert queue handles only internal
requests, not requests from outside the AR System server. The threads in this queue do not open
database connections, so they do not use many resources.
The minimum thread count for the alert queue is 1. If the server is supporting Remedy Notifier 4.x
clients, set the maximum number of alert threads no higher than 5 because those client versions
cannot handle more than 5 simultaneous connection requests. If the server is supporting Remedy
Notifier 3.x or earlier clients, set a maximum of 1 alert thread because those client versions do not
correctly handle simultaneous connection requests.
To configure an alert queue, see Defining queues and configuring threads.
Full Text Indexing queue

The Full Text Indexing queue handles all indexing tasks for fields selected for full text indexing. The
queue is created only when the server is licensed for full text searching. The full text indexing
queue handles only internal requests, not requests from outside the AR System server. The
threads in this queue provide the full text search engine with data to index as updates are made to
the field values on BMC Remedy AR System forms or when fields with existing data are chosen for
full text indexing.
One or more threads can serve the full text indexing queue. The default is 1 minimum and 1
maximum.
Escalation queue
All servers automatically create an escalation queue unless Disable Escalations is configured. The
escalation queue handles only internal requests, not requests from outside the AR System server.
It handles escalations specified by the administrator and performs all escalation processing. The
escalation queue is multithreaded.
Fast queue
The fast queue handles the operations that generally run to completion quickly without blocking
access to the database. The fast queue handles all server operations, except for:
Administrative operations that restructure the database. These operations use the
administration queue.
The ARExport, ARGetListEntry, ARGetListEntryWithFields, and
ARGetEntryStatistics, and other API calls (which use the list queue).
For more information about API calls, see the Developing an API program.
One or more threads can serve the fast queue if a fast queue is configured. To configure a fast
queue, see Defining queues and configuring threads.
Page 140 of 4705
Home
List queue
The list queue handles BMC Remedy AR System operations that might require significant time,
block access to the database, or both. Examples of these operations include ARExport,
ARGetListEntry, ARGetListEntryWithFields, and ARGetEntryStatistics.
One or more threads can serve the list queue if a list queue is configured. To configure a list queue,
see Defining queues and configuring threads.
Private queues
Administrators can also create private queues for specific applications or users that require
dedicated access. For example, you might create a private queue for the BMC Remedy Approval
Server or other plug-in application, or for a user who is performing critical operations that you do
not want blocked by other users. Private queues guarantee a certain bandwidth dedicated to clients
using these queues.
Private queues support all operations except restructuring operations. Restructuring operations are
supported only by the administration queue (see Administration queue). To configure a private
queue, see Defining queues and configuring threads.
Each private queue can be supported by one or more threads. To connect a user to a private
queue, see Configuring clients for AR System servers .
For more information on Private Queues, see the blog Utilizing Private Queues shared on BMC
Communities.
AR System server threads

The term thread is short for thread of execution. Threads enable the server to process concurrent
client requests. Each thread within the multithreaded server can carry out a client request before
returning to the queue to process the next one. Start only as many threads as your database and
system resources can reasonably support. The total number of threads cannot exceed the number
of database connections available to the AR System server.
All threads within a process share network and system resources; therefore, consider carefully the
available resources of your system and network when establishing the minimum and maximum
thread settings for your server queues.
BMC Remedy AR System uses the following types of threads:
Dispatcher thread
Worker threads
Thread manager
Page 141 of 4705
Home
Dispatcher thread
The dispatcher thread routes requests to the appropriate queues. This thread receives connection
requests from clients. The dispatcher thread then places the requests into the appropriate queue
where each request can be handled by one of multiple worker threads.
Every call that the dispatcher thread receives is assigned an RPC ID that can be used to identify
the call from the time the call is placed into a queue until a response is sent to the client.
In general, the dispatcher thread uses the following logic to dispatch calls:
If no other queues are defined, the dispatcher thread routes all requests to the admin queue.
If, however, fast and list queues are created in addition to the admin queue, the dispatcher
routes client requests according to the type of operation being performed. If private queues
are created, the dispatcher directs the call to the appropriate private queue based on the
RPC program number of the request.
A request is routed to the appropriate queue based on its RPC program number. For
example, a call that has RPC program number 390600 is routed to the admin queue.
If a call with RPC program number 390620 (fast) or 390635 (list) is received and no fast or
list queue exists, the dispatcher thread routes the call to the admin queue. If only a list queue
exists, the dispatcher thread places the call in that queue. If only a fast queue exists, the
dispatcher thread directs the call to that queue. If both fast and list queues exist, the
dispatcher routes the call to the appropriate queue based on the call number.
If a call is received with RPC program number 390601 (previously supported by the
Notification server, which is now merged with the AR System server), the dispatcher routes
the call to the fast queue.
If a call is received with an RPC program number other than those specified for admin, fast,
list, and Flashboards queues, the dispatcher identifies the call as destined for a private
queue. If a private queue supporting the RPC program number exists, the dispatcher thread
routes the call to that queue. If no private queue exists but a fast or list queue exists, the call
is routed to the appropriate queue based on its RPC program number. If no fast or list queue
exists, the call is routed to the admin queue.
The escalation and alert queues do not receive calls from the dispatcher.
Worker threads
Worker threads respond to the RPCs dispatched to individual queues. Each queue creates one or
more worker threads. The worker threads within a queue are identical and can handle any request.
Only the worker thread started by the admin queue, however, can handle calls that modify
definitions or server configuration settings.
On startup, each thread creates a connection to the database that it uses throughout its existence.
If the thread is unable to establish a connection, it terminates itself, notifying the queue that no
more threads are to be started. The database connection is dedicated to the thread, even when
that particular thread is not busy.
Page 142 of 4705
Home
Any available worker thread can remove the request from the queue, read the request, process it,
and return results to the client before returning to the queue to respond to another request. When a
request is placed in a queue and no existing threads are available to handle it, a new thread is
started until the queue reaches the maximum number of threads allowed for its thread type.
Thread manager
The thread manager is responsible for ensuring that a thread is restarted if it dies.
Determining thread count and type

A major benefit of a multithreaded server is not having fast operations held up behind a slow list
operation. Deciding how many fast and list threads you need depends on your particular setup and
situation. For example, not specifying enough list threads might mean you have idle fast threads
but an overloaded list queue.
Another consideration is that list threads require more memory than fast threads. For example, a
complicated query might require a great deal of memory at a given moment. A few of these large
queries can temporarily exhaust your system resources.
To determine how many threads of each type you need, start by examining the types of API calls in
your API log file. If your system processes many fast operations, you might decide to increase the
number of fast threads. A different rule of thumb is to specify a larger maximum of list threads than
fast threads, simply because fast operations are generally performed more quickly than list
operations.
Do not specify an artificially high number of maximum threads because the threads would
essentially get in one another's way by consuming resources that other threads need. To set the
number of minimum and maximum threads, see Setting ports and RPC numbers.
Related Topic
Defining queues and configuring threads
AR System server processes
The AR System server is a set of processes that run on an application's server host. The server is
available for each of these operating systems :
Hewlett Packard HP-UX
IBM AIX
Linux (Red Hat and Novell SuSE)
Microsoft Windows Server
Oracle Microsystems Solaris
Note
Page 143 of 4705
Home
For the most accurate information about supported platforms and software, see
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation.
The server is implemented as several service processes that are normally started automatically
when the server host is powered up.
The AR System server has no direct user interface. Clients, such as the mid tier and other
applications, communicate with BMC Remedy AR System by means of a well-defined application
programming interface (API). An API is one possible way to integrate with BMC Remedy AR
System. The APIs use remote procedure calls (RPCs) to communicate with the server. Both a C
interface and a Java interface are available.
The AR System server processes all data entered through a client. As the workflow engine
between client and database, the server writes data to the database when a request is created and
retrieves data from the database when a client requests it. The server verifies that a user has
permission to perform each transaction, thereby enforcing any access control defined in an
application. The server also continuously evaluates the data in the database and each transaction
to determine whether the server should perform workflow. The server might also perform workflow
on a timed basis.
When a client submits a request to the server, the request enters through the API, goes through
access control and data validation, filter processing, and then transactions are committed to the
data repository as appropriate.
Following are the key processes in the AR System server:
arserver process arserverd is for UNIX or arserver.exe on Windows; the primary AR
System server process. It handles requests from the clients and interacts with the database.
Plug-in server process A companion process to the AR System server. It loads
configured plug-in modules to interface with external data while processing vendor forms,
validates users with external authentication sources, and extends filter workflow. When the
AR System server needs to access a plug-in, it interfaces with the plug-in server to perform
the operation.
Email engine process Java on UNIX or aremaild on Windows; the process that links
arserver process with email systems. For example, users can submit service requests to an
AR System server by sending an email message to an email account. In addition, workflow
can cause email messages to be sent to particular email addresses as a notification option.
AR System database server

BMC Remedy AR System uses standard relational database engines for the actual storage and
retrieval of data. Architecturally, the database server is an independent set of processes that are
completely separate from the AR System server processes. Physically, the database server
processes can be running on the same server host as the AR System server or on a different host.
Page 144 of 4705
Home
The database server can be any platform that the database engine supports.
BMC Remedy AR System can also work with data stored in external databases and other data
sources that are not managed by BMC Remedy AR System. BMC Remedy AR System accesses
these data sources through view forms . In addition, BMC Remedy AR System can use BMC
Remedy AR System database connectivity (ARDBC ) to work with data not stored in databases as
if the data were locally owned.
Because the AR System server manages all workflow, applications are independent of the
database. Therefore, applications created on an AR System server running one type of database
can easily be moved to a server running a different type of database. BMC provides a simple export
/import utility for this purpose.
BMC Remedy AR System is not a database application in the typical sense. All of the workflow is
managed by the AR System server, so proprietary database features such as triggers and stored
procedures are not used. An application created on an AR System server running one type of
database engine can easily be moved to a server running a different database engine through a
simple export/import process.
The user or administrator of AR System clients does not need to know anything about SQL or the
underlying database.
BMC Remedy AR System workflow components can search for records (requests) in the AR
System database and act on the results of the search. Clients can use the following types of
searches:
Query-by-example (QBE)
Advanced search
Predefined
Recent
An administrator can create and store searches that are commonly performed by users. A user can
define personal searches for forms to which the user has access.
BMC Remedy Mid Tier architecture

Use this section to understand the BMC Remedy Mid Tier architecture and its components.
BMC Remedy Mid Tier functional components
BMC Remedy Mid Tier scalability
Multiple browser sessions in a distributed mid tier environment
Page 145 of 4705
Home
BMC Remedy Mid Tier functional components

Use this section to learn about how to present application data and how to interact with the user.
For information about the BMC Remedy AR System architecture, see BMC Remedy AR System
architecture.
BMC Remedy Mid Tier serves as a client of the AR System server and as a server to the browser.
The mid tier enables you to view BMC Remedy AR System applications on the web and access the
AR System server from a web server. It also provides instructions to the browser in the form of
document markup and downloadable scripts. These instructions describe how to present
application data and how to interact with the user.
BMC Remedy Mid Tier translates client requests, interprets responses from the server, handles
web service requests, and runs server-side processes that bring BMC Remedy AR System
functionality to web and wireless clients. A browser is a generic client that has no inherent
knowledge of any application that might run within it. By acting as an interpreter, the mid tier allows
a browser to become a fully functional BMC Remedy AR System client.
Note
While accessing the applications using BMC Remedy Mid Tier, you can open multiple
browser windows using workflows. All the forms opened using the workflows are closed
after you log out. But if you make any changes to open the forms (for example, change
the URL in web address bar or refresh the page or access any other forms by typing form
name) or if a new browser window or tab is opened and other forms are accessed. Such
windows are not closed by the mid tier after you log out, but a session timeout error is
displayed if you perform any operations on them.
The BMC Remedy Mid Tier requires a Oracle Java Server Pages (JSP) engine, that is supported
by AR System. For a list of supported engines, see Compatibility matrix in the BMC Remedy ITSM
Deployment online documentation. Apache Tomcat is bundled with the mid tier and is installed with
the mid tier by default.
The mid tier leverages a Java servlet engine and includes a collection of servlets plugged in to the
web server to serve forms, images, and other resources. The servlet engine facilitates
communication between the browser and the web server. It provides components and add-in
services that run on the web server.
The web server manages the transfer of all HTML content to the browser. Infrastructure
components, such as servlets and other services (special Java classes), translate client requests
and interpret responses from the AR System server.
The main components of the mid tier infrastructure are:
Page 146 of 4705
Home
Web server
Oracle JSP engine
Oracle JSP servlets
JAVA API
BMC Remedy Mid Tier Configuration Tool
Report Console overview
Crystal reports and mid tier architecture
Web server
A server that receives requests for a web page and maps the uniform resource locator (URL) to a
local file or servlet on the host server. The server then loads the content and serves it across the
network to the user's browser.
Oracle JSP engine

An engine that handles the .jsp files and the basic request and response interface in the browser
environment.
Oracle JSP servlets

A small piece of Java code, often translated from a .jsp file, that runs on a web server.
JAVA API
An API used to communicate with the AR System server. The object model provides a set of
classes representing the data structures and functions of the API.
BMC Remedy Mid Tier Configuration Tool

BMC Remedy Mid Tier Configuration Tool enables you to configure mid tier property settings. The
settings are written to the file config.properties on the mid tier server.
Settings include the list of AR System servers to access, session time-out interval, directory
locations, reporting tool options, logging options, cache policy options, connections for load
balancing, flashboard options, home page server options, and user authentication for web services.
BMC Remedy Mid Tier Configuration Tool is accessible through a .jsp file in a browser using a
separate login. The tool knows 1 unnamed user and the password can be changed within the tool.
The standard password is arsystem.
Report Console overview

To use the Report Console, the plug-in server, the mid tier and web server, and a JSP engine must
be running. The Report Console is an ARDBC plug-in application that is installed with BMC
Remedy AR System. It works with the components that support Web reports, which are installed
with the BMC Remedy Mid Tier, and with the installed JSP engine. By default, the Tomcat JSP
Page 147 of 4705
Home
engine is installed with BMC Remedy AR System, but you can use other compatible JSP engines.
For the most current information about supported web servers and JSP engines, see Compatibility
matrix in the BMC Remedy ITSM Deployment online documentation.
Crystal reports and mid tier architecture

To make Crystal reports available to BMC Remedy AR System Web users, the mid tier uses the
AR Web ReportViewer to communicate with the Central Management Server (CMS). The AR Web
ReportViewer passes the report query, user credentials, and other report information to the CMS
for processing.
The CMS is the server component of BusinessObjects Enterprise and Crystal Reports Server. It
listens for and executes report requests, using the BMC Remedy AR System ODBC driver to
retrieve the BMC Remedy AR System data, publishes the report in the Crystal environment and
renders it for display in the browser.
The AR Web ReportViewer is a component of the mid tier. It can be installed together with the mid
tier or as a separate component, but it must reside on the same computer as the CMS.
Once the necessary components have been installed together and configured, any authorized BMC
Remedy Mid Tier can direct requests for Crystal reports to the mid tier or AR Web ReportViewer on
the Crystal reports server.
You must use one of the following configurations:
Install BMC Remedy Mid Tier on the same Windows computer as the CMS. In this case the
AR Web ReportViewer is installed as part of the mid tier.
Install the mid tier on a separate computer (any supported platform), and install only the AR
Web ReportViewer on the same Windows computer as the CMS.
BusinessObjects Enterprise or Crystal Reports Server and the AR Web ReportViewer must be
installed on a Windows computer because the CMS uses the AR System BMC Remedy ODBC
Driver to contact the AR System server when retrieving report data.
BMC Remedy Mid Tier scalability

The strategy for processing and serving browser-client requests is based on several components.
These components work together to take input from the client and compute a response that the
user sees in the browser as Dynamic HTML (DHTML). These BMC Remedy Mid Tier components
do not run in a separate proprietary process, but in the JSP engine using standard web protocols.
The use of JSP servlets makes the mid tier scalable in the following ways:
Multiple threads connecting to a servlet can handle many concurrent users.
Page 148 of 4705
Home
Common web-server mechanisms and practices can be used for scaling and load balancing.
See, Parameters to support load balancers between BMC Remedy Mid Tier and server
group without a sticky bit.
BMC Remedy Mid Tier caches BMC Remedy AR System definitions require fewer trips to
the AR System server to retrieve them. In addition, use of browser caching leads to data size
reductions, which in turn reduces bandwidth requirements. See, About Mid Tier caching.
Additionally, the architecture supports server clusters, or web forms that are hardware setups in
which several physical web servers share the load directed to one logical server (one IP address).
In a web form, a load balancer receives requests and sends them to whichever physical server has
the most resources available to handle them.
Multiple browser sessions in a distributed mid tier environment

Administrators can configure a mid tier to launch a browser on another mid tier in a Hub and Spoke
implementation or independently. For information about configuring this feature with BMC Remedy
AR System, see Configuring a mid tier to launch a browser in a different mid tier .
A mid tier allows you to launch a browser on another mid tier so that users can work on records in a
distributed mid tier environment. This feature allows you to link a central mid tier to one or more
remote mid tiers (also known as federated mid tiers) to display forms residing on the remote AR
System server(s).
Note
You configure only the servers that are running the BMC Remedy AR System Server as
the central server.
This feature is used by the Hub and Spoke implementation of BMC Remedy IT Service
Management (BMC Remedy ITSM). It can also be used independently without the Hub and Spoke
implementation. For more information about Hub and Spoke capabilities in BMC Remedy ITSM,
see Hub and Spoke capability overview.
Hub and Spoke overview

The Hub and Spoke implementation displays a consolidated list of tickets from a central console for
a support staffer. This architecture efficiently maintains data integrity and country boundary rules.
When a remote AR System server (the spoke AR System server) is configured to a central AR
System server (the hub AR System server) for this feature, a support staffer can work with records
from any of the remote AR System servers to which his central AR System server is connected.
The central AR System server receives and stores only a subset of the transactional data from the
original record located on the remote AR System server. This feature allows a support staffer to
seamlessly work with remote AR System servers in the Hub and Spoke scenario.
Page 149 of 4705
Home
Without requiring authentication, the central system displays the remote transactional data in a new
mid tier window on a workstation connected to the central AR System server. The support staffer
can open the record from the remote server, view the record's details, and work the record through
its lifecycle.
Notes
If the user name and password for the user on the central AR System server and remote
AR System server do not match, then a browser launches on another mid tier as follows:
If guest users are enabled on the remote AR System server, then the user is
logged in as a guest user and has guest user privileges. The user receives a guest
user warning message.
If guest users are not enabled on the remote AR System server, then the user
receives an authentication failure message from the mid tier. When reloading the
page, the user is directed to the remote mid tier login page.
If the remote mid tier is from a release earlier than 8.1, the user is directed to the remote
mid tier login page for authentication.
Scenario for launching a browser on another mid tier

Francie Stafford is a support staffer of Calbro Services, which supports several customers. Francie
opens her Incident Management console (on the central AR System server) and sees several
newly assigned incident requests, one each from Company A, Company B, and Company C. When
Francie opens the new incident request from Company A, she is automatically connected to the
appropriate remote server. She can then view the incident request details and work the incident
request through its lifecycle.
Note
If a user has multiple records open in multiple remote windows when working with central
and remote (hub and spoke) servers, logging off of one remote window invalidates the
session that is established for all open remote windows. The remaining sessions become
invalid even if they appear active. BMC recommends that work be completed and saved in
all remote windows before logging off from any remote window.
Related topics
For information about configuring this feature with an AR System, see Configuring a mid tier to
launch a browser in a different mid tier .
Page 150 of 4705
Home
For information about configuring this feature within a BMC Remedy IT Service Management Suite
hub and spoke system, see Registering hub and spoke servers.
BMC Remedy Migrator architecture

BMC Remedy Migrator integrates with BMC Remedy AR System through existing application
programming interfaces (APIs) and requires no additional integration work. You can install BMC
Remedy Migrator on a client workstation and run it independently of BMC Remedy AR System. The
APIs handle all communication between BMC Remedy Migrator and AR System servers.
BMC Remedy Migrator and AR System server integration
In addition to server objects, BMC Remedy Migrator can transfer data entries from one or more
BMC Remedy AR System forms. You can select single, multiple, or searched sets of data. You can
migrate data immediately or save your migration in a script to be run later.
Related topics
How BMC Remedy Migrator automates migration of data and objects between AR System servers
Installing BMC Remedy Migrator
BMC Remedy AR System web services architecture

This section describes how information flows between BMC Remedy AR System server and client
applications for web services published in BMC Remedy AR System server, and how information
flows between BMC Remedy AR System server and an external web service consumed by a BMC
Remedy AR System application.
Information flow for web services published in AR System server
Information flow for consuming a web service in AR System server
Information flow for web services published in AR System server

When a client contacts a BMC Remedy AR System web service, the interaction works as follows:
1. The external client sends a Simple Object Access Protocol (SOAP) request to the mid tier.
The URL for the service is either built into the application or is obtained from the web
services registry at run time.
Page 151 of 4705
1.
Home
External web service client calling BMC Remedy AR System (publishing)

2. The mid tier extracts the web service name, the operation name, and the authentication
information from the SOAP request packet. It retrieves the web service object corresponding
to the web service name from the BMC Remedy AR System server and searches the web
service for details about the operation, such as the operation type ( Get, Create, Set, or
Service), the query string, and the input and output mappings. Then it expands the XPATH
expressions in the query string, extracts the XML document from the SOAP request packet,
and sends it to the BMC Remedy AR System server along with the operation type, the input
and output mappings, and the expanded query string.
3. The BMC Remedy AR System server parses the XML document using the mapping
information and converts it into field data. The operation type determines how the data is
treated:
For Get, the BMC Remedy AR System server ignores the input fields.
For Create, the BMC Remedy AR System server creates an entry with the input
fields.
For Set, the BMC Remedy AR System server searches for an entry using the
expanded query string and then modifies the data using the input fields.
For Service, the BMC Remedy AR System server sends the input fields to the
Service Entry call.
For complex documents, the data is pushed into one or more forms. This action might
trigger some filters.
4. The BMC Remedy AR System server also uses the mapping information to get the data from
one or more records and generate an XML document. The operation type determines how
the data is treated:
For Get, the BMC Remedy AR System server performs a query based on the query
string.
For Create, the BMC Remedy AR System server reads the record that was created.
For Set, the BMC Remedy AR System server reads the record that was modified.
For Service, the BMC Remedy AR System server reads the output fields from the
Service Entry call. This action might also trigger some filters.
5. The XML document is returned to the mid tier.
6. The mid tier packages the XML document as a SOAP response and returns it to the external
client.
Page 152 of 4705
Home
Information flow for consuming a web service in AR System server

An external web service can be one created on another BMC Remedy AR System server, or one
based in some other environment, such as one that provides stock quotes, weather information, or
currency exchange rates.
BMC Remedy AR System communicates with the web service through the Web Service plug-in,
using the third-party web service server (Apache AXIS) installed with the Java plug-in server.
The flow for consuming a web service in BMC Remedy AR System is as follows:
1. A filter process triggers a Set Fields filter action that sets fields using data from a web
service.
2. The filter uses the mapping information stored on the server to construct an XML document
with data from the base form and the child form (if any).
3. The BMC Remedy AR System server sends the XML document to the web service plug-in.
4. The web service plug-in receives the XML document, packages it into a SOAP request
packet, and calls the external web service.
5. The external web service replies with the SOAP response packet.
6. The web service filter plug-in extracts an XML document from the SOAP packet and returns
it to the BMC Remedy AR System server.
7. The BMC Remedy AR System server receives the XML document and uses the mapping
information to parse the document and push data into the current record and any child forms
.
8. The Set Fields filter action is finished.
Consuming an external web service with BMC Remedy AR System
BMC Remedy AR System API architecture

Use this section to learn about the BMC Remedy AR System API architecture.
BMC Remedy AR System plug-in API architecture
BMC Remedy AR System C and Java API architecture
Page 153 of 4705
Home
BMC Remedy AR System plug-in API architecture

AR System clients perform external data source operations on external forms through the AR
System server, plug-in service, and plug-in APIs. The plug-in service extends the AR System
server to integrate with external data sources. The AR System server connects to the plug-in
service, which activates the plug-ins.
Plug-in architecture
Note
The arrows in this figure identify the directions in which each program or process can
initiate API function calls. Data can flow in any direction.
BMC Remedy AR System client code links to the provided C API libraries. The C APIs create an
interface layer between the AR System server and C-based AR System clients. The Java API
serves the same function for Java-based clients. AR System clients perform all database
operations through the API interface.
BMC Remedy AR System includes a plug-in server that extends its functionality to external data (
data not contained in the BMC Remedy AR System database). The plug-in service supports three
types of plug-ins with corresponding C and Java APIs:
Page 154 of 4705
Home
AREA plug-in
ARDBC plug-in
BMC Remedy AR System Filter (AR Filter) API plug-in
BMC Remedy AR System offers the following ready-to-use plug-ins that you access through BMC
Remedy Developer Studio:
BMC Remedy AR System External Authentication (AREA) Lightweight Directory Access
Protocol (LDAP) plug-in
BMC Remedy AR System Database Connectivity (ARDBC) LDAP plug-in
Both plug-ins access LDAP services.
For information about the C plug-in APIs, see BMC Remedy AR System plug-in API functions . For
information about the Java Plug-in API, see the online documentation located at
ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
For information about configuring and running all types of plug-ins, see Enabling Plug-ins.
BMC Remedy AR System C and Java API architecture

BMC Remedy AR System client code links to the provided C API libraries. The C APIs create an
interface layer between the AR System server and C-based AR System clients. The Java API
serves the same function for Java-based clients. AR System clients perform all database
operations through the API interface.
C and Java API architecture
Page 155 of 4705
Home
Note
The arrows in the preceding figure identify the directions in which each program or
process can initiate API function calls. Data can flow in all directions.
Important
The Java API also uses a Java Native Interface (JNI) library and the C API library to
connect to a pre-7.0.01 AR System server. You can control when the JNI library is used
by setting the jniLoadMode parameter in the Java API configuration file. See the
comments in the sample file, arsys_sample.xml.
C API
The BMC Remedy AR System clients use the C APIs to manipulate data. For example, the clients
use C APIs to create, retrieve, update, and delete schemas, entries, and menus, and to control
workflow. You can use the C API to extend BMC Remedy AR System functionality.
The BMC Remedy AR System API contains data structures that store both simple and complex
information. Structures that store simple information, such as the type of value or the product of an
arithmetic operation, serve as the building blocks for complex structures.
You can run API programs from a command line or from the BMC Remedy AR System; in the Set
Field $PROCESS$ action from an active link, filter, or escalation; or with the Run Process action in
an active link, filter, or escalation.
C API components
The C APIs consist of a set of functions, most of which cause the server to perform a specific
database or data source operation and return a result. For example, you can create an entry or
retrieve information about a particular BMC Remedy AR System object.
BMC Remedy AR System C API functions describes the purpose and use of each BMC Remedy
AR System C API function. BMC Remedy AR System plug-in API functions describes the purpose
and use of the common BMC Remedy AR System, AREA, ARDBC, and AR filter API plug-in
functions.
In addition, almost all of the BMC Remedy AR System C API functions accept one or more
structure-type parameters. Data structures explains some of the most common structures and the
operations they apply to. These types are defined in the ar.h file. If you understand the functions
and structures that comprise the API, you can interact with the BMC Remedy AR System server to
customize and extend your applications.
Page 156 of 4705
Home
The driver directory contains source code for the driver program. This program provides a
command line interface for calling BMC Remedy AR System C API functions. The driver program
also includes print routines for every data structure in the API, making it a useful debugging tool.
See Using the driver program for additional information about this topic.
Java API
The BMC Remedy AR System Java API is a collection of Java classes that provide the full BMC
Remedy AR System API functionality in a Java development environment.
The Java API:
Provides an object model of BMC Remedy AR System server entities (also called server
objects), definitions, and data.
Includes a single class, ARServerUser, that provides both the context and the methods
required to interact with the BMC Remedy AR System server.
The JavaDriver directory contains source code for a Java program like the C driver program.
For more information about the Java API, see BMC Remedy AR System Java API overview and
the Java API documentation HTML files in the ardocVerNum.jar file in the \Arserver\Api\doc
folder (Windows) or the /ARServer/api/doc folder (UNIX). To access the Java API documentation,
unzip the ardocVerNum.jar file to create a tree of directories, then open the index.html file.
Choosing to use the Java API

Use the BMC Remedy AR System Java API to perform the following tasks:
Write server-side web applications that you access through the Java server page (JSP) or
Java servlets web tier layer.
Implement BMC Remedy AR System clients in Java.
Comparison of the Java and C APIs

The BMC Remedy AR System Java and C APIs have a number of differences, for example:
The Java Virtual Machine (JVM) uses garbage collecting functions to automatically
deallocate objects that are created with the Java API. The C API includes a set of memory
deallocating functions that you can use to deallocate memory.
In the C API, the control parameter provides server access information with every call. In the
Java API, the ARServerUser object encapsulates this information
The C API and Java API have different naming conventions.

BMC Remedy Email Engine consists of multiple modules that run in threads. All the modules are
designed to be thread safe, and to increase speed and scalability.
Page 157 of 4705
Home
BMC Remedy Email Engine modules

Following are the BMC Remedy Email Engine modules:
Module
Description and purpose
Monitor
Monitors the mailbox for statistical information such as when the connection dropped and the length of time the
connection was down.
Receiver
Runs in separate threads to maximize speed and reliability.

Reads incoming mails from the mail server.
Creates entries in BMC Remedy AR System Email Messages form.
Adds messages to message queue.
Execution
Parses and executes messages in the message queue.
Creator
Primarily responsible for creating an email based on a template and the data it retrieves from BMC Remedy AR
System.
Monitors the BMC Remedy AR System Email Messages form for outgoing messages.
Formats messages to be sent.
Sender
Runs as a separate thread, and sends formatted messages to the mail server.
Logging
Logs messages, error messages, and warnings to the BMC Remedy AR System Email Errors form or local file.
Configuration
Maintains configuration information for the system specified in the BMC Remedy AR System Mailbox
Configuration form and EmailDaemon.properties file.
All modules run as separate threads. An incoming mailbox uses two threads to process email in the
message queue--the Receiver and Execution modules. An outgoing mailbox uses separate threads
running for the Creator and Sender modules to format and send outgoing messages.
BMC Remedy Email Engine Architecture
You can specify various troubleshooting parameters, for example, the queue size of email
messages or how finely you want to log information within a module. For more information, see
Debugging options for the BMC Remedy Email Engine and EmailDaemon.properties file.
Page 158 of 4705
Home
Threading model for outgoing mailboxes

The Sender and Creator threads for every outgoing mailbox depend upon the value set for the
NumberOfSenderThreads property and the number of configured outgoing mailboxes
respectively.
Depending upon the NumberOfSenderThreads value and the number of configured outgoing
mailboxes, a connection pool is created. The Sender thread uses the connections from this
connection pool for sending the outgoing messages.
Note
The number of connections for each configured outgoing mailbox depends upon the
number of Sender threads.
The following figure explains this concept in detail.

Threading model for multiple outgoing mailboxes
As per the above figure, there are 3 configured outgoing mailboxes and the value of
NumberOfSenderThreads is assumed to be 2. Due to this, 2 Sender threads and a connection
pool with 6 connections (2 connections for every mailbox) is created. The Sender threads send the
outgoing messages from the common message queue created for the 3 Creator threads by using
the connections from this connection pool.
User goals and features

BMC provides a large set of task-based, conceptual and reference information about BMC Remedy
Action Request System (BMC Remedy AR System) features for new and current users to help you
be successful with your BMC Remedy AR System platform implementation. Each section contains
a home page with goal-based topic summaries and links to instructions.
Page 159 of 4705
Home
User roles
Use this section to learn about the roles and responsibilities of BMC Remedy AR System users
associated with each key section shown in the preceding figure.
Administrator responsibilities
Application programmer responsibilities
Developer responsibilities
End user responsibilities
Page 160 of 4705
Home
Security administrator responsibilities
Administrator responsibilities
Typically, BMC Remedy AR System administrators are responsible for some or all of these tasks:
Installing BMC Remedy AR System software
Defining their organization's work processes and business rules
Determining how to allocate server and database resources
Managing BMC Remedy AR System access control by assigning permissions for BMC
Remedy AR System applications and their components
Maintaining BMC Remedy AR System by adding and deleting users, groups, and roles;
backing up BMC Remedy AR System servers; importing data from other systems.
Application programmer responsibilities

Typically, BMC Remedy AR System programmers are responsible for some or all of these tasks:
Writing plug-ins and custom clients that use the BMC Remedy AR System C API, Java API,
or Java plug-in API
Integrating external applications with BMC Remedy AR System
Developer responsibilities
Typically, BMC Remedy AR System developers are responsible for some or all of these tasks:
Creating an BMC Remedy AR System application that reflects a set of work processes and
business rules, or working with a consultant to create an application
Localizing an BMC Remedy AR System application for use in other languages or countries
Modifying an BMC Remedy AR System application to reflect changes in the organization's
work processes
End user responsibilities

Typically, BMC Remedy AR System end users are responsible for some or all of these tasks:
Using BMC Remedy AR System software
Raising incident and service requests
Analysis or consumption of a customized or prepackaged BMC Remedy AR System-based
application included in an ITSM solution
Security administrator responsibilities

Typically, BMC Remedy AR System security administrators are responsible for some or all of these
tasks:
Securing BMC Remedy AR System software
Managing user accounts
Setting permissions
Page 161 of 4705
Home
Implementing security policy, standards, guidelines and procedures to ensure ongoing

maintenance of security
Page 162 of 4705
Home
Planning
Use the following topics to help you plan for a BMC Remedy Action Request System installation.
Note
Before you begin your planning process, review the Known issues and workarounds to
understand any issues you might encounter.
Goal
Instructions
Plan your BMC Remedy AR System installation. Learn about the available features and
configuration types.
Available BMC Remedy AR

System features and
configurations
Learn the available paths to install or upgrade.
Installation and upgrade paths
Learn about the BSM Reference Stack and BSM Interoperability programs that provide
information about certified environments in which you should install BMC Remedy Action
Request System.
BSM environment
recommendations
Learn about the deployment architecture and performance benchmarks and tuning for BMC
Remedy AR System.
Deployment architecture
Learn the hardware and software requirements for installing and running BMC Remedy AR
System
System requirements
Plan for securing your applications through encryption and other methods.
Security
Learn about what languages are supported and what considerations you should know when
installing languages.
Language information
Learn about the standards followed by AR System server and BMC Remedy Mid Tier.
BMC Remedy AR System

standards
Learn about how IPv6 is supported in BMC Remedy AR System.
Support for IPv6
Page 163 of 4705
Home
Available BMC Remedy AR System features

and configurations
BMC Remedy AR System consists of server and client features that you combine to create the
types of access you want to enable. Certain features are required for all BMC Remedy AR System
installations, while other features are optional. Planning is the key to a successful installation.
BMC Remedy AR System has a flexible and scalable architecture, and can be configured
depending on current and future needs.
BMC Remedy AR System requires several compatible features to function correctly. See
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation to check if your
current features are compatible with the BMC Remedy AR System version you are using.
This topic discusses the available features and configurations for BMC Remedy AR System:
Features you can install
BMC Remedy AR System server
BMC Remedy Mid Tier
Assignment Engine
Flashboards
BMC Atrium Integrator Spoon
Configuration Types
Extending configuration to multiple servers
Extending configuration to the Web
Extending configuration to include email access
Sizing factors and scalability
Features you can install

The following features can be installed with the BMC Remedy AR System installer.

The BMC Remedy AR System server can be installed on UNIX, Linux, or Microsoft Windows
system.
The BMC Remedy AR System server is the primary feature that manages user interaction with the
underlying database. The BMC Remedy AR System server interacts with the database and
provides information to the user independent of the underlying database. For more information, see
Understanding the AR System database.
Page 164 of 4705
Home
See also BMC Remedy AR System functional components .

The BMC Remedy AR System server installation also includes the BMC Atrium Integrator Engine
which provides a single way of doing data movement to or from AR System across the solution
stack. The installation also includes the BMC Atrium Integrator Adapter which supports the ability to
bring in data from multiple types of data sources into BMC Remedy AR System and vice versa.
BMC Remedy AR System can be installed with a variety of underlying databases (Microsoft SQL
Server, Oracle, IBM DB2, and Sybase). The database can be installed on any computer that is
accessible to the BMC Remedy AR System server.
The BMC Remedy AR System installer creates an BMC Remedy AR System database with a
series of tables that make up a data dictionary where form, filter, escalation, and other definitions
are stored. The BMC Remedy AR System installer also creates the user of the BMC Remedy AR
System database. The structure of the BMC Remedy AR System database varies depending on
the underlying database. For more information, see Understanding the AR System database.
BMC Remedy Mid Tier

BMC Remedy Mid Tier can be installed on a UNIX, Linux, or Windows system.
Mid tier is optional middleware that enables BMC Remedy AR System access through a browser. A
web server and the mid tier must be installed on the same computer. This computer can be
networked to the BMC Remedy AR System server computer. One mid tier can permit access to
multiple BMC Remedy AR System servers.
BMC Remedy Mid Tier Configuration Tool is installed with the mid tier. Use this tool to define which
BMC Remedy AR System servers the mid tier can access.
Client computers must have a supported browser installed. Users need BMC Remedy AR System
permissions to submit BMC Remedy AR System requests and search the database through the
web.
For more information, see BMC Remedy Mid Tier functional components .

Access to BMC Remedy AR System servers is available to all supported platforms through the
BMC Remedy Email Engine (Email Engine).
The Email Engine is a process (on UNIX) or a service (on Windows) that transforms email
messages into an interface to the BMC Remedy AR System server. The Email Engine enables
users to instruct the BMC Remedy AR System server to perform queries, submissions, or
modifications to entries, all using email. The Email Engine can also return the results of such
requests in email, formatted as plain text, RTF, HTML, or XML content. In addition, the Email
Engine can process notifications using workflow actions, such as filters and escalations.
Page 165 of 4705
Home
The Email Engine can connect to mail servers by using protocols such as Internet Message Access
Protocol (IMAP4), Post Office Protocol (POP3), Simple Mail Transfer Protocol (SMTP), Messaging
Application Programming Interface (MAPI), and MBOX.
Note
The MAPI protocol for incoming and outgoing mail is disabled for 64-bit Java Virtual
Machine (JVM).
For more information, see Controlling BMC Remedy AR System through email .

The BMC Remedy Approval Server is a self-contained, shared module that can be attached to any
BMC Remedy AR System application. It is a flexible solution for automating any approval or
signature process across any organization. You can have multiple Approval Servers running with
multiple BMC Remedy AR System servers on one computer.
Assignment Engine
The Assignment Engine enables you to use processes instead of workflow to automatically assign
requests to individuals. When you install the Assignment Engine, the installer installs forms to help
you set up the processes. See Assigning requests with the Assignment Engine.
Flashboards
Flashboards enable you to include dynamic, graphical representations of data in the BMC Remedy
AR System forms. You can use flashboards to process, store, and display data in the form of
graphs, charts, text boxes, and meters. You can summarize data for trend or historical analysis.

BMC Remedy Developer Studio is an integrated development environment (IDE) for BMC Remedy
AR System applications. It provides all the application development functions needed to design an
application.
BMC Remedy Developer Studio uses the Java-based Eclipse platform to provide a framework for
its functions. Eclipse includes functions to organize the user interface (UI) and to work with UI
components that the Developer Studio provides.
BMC Remedy Developer Studio can be installed on Microsoft Windows only.

BMC Remedy Data Import allows you to import data from a source file into a BMC Remedy AR
System form.
Page 166 of 4705
Home
BMC Atrium Integrator Spoon

BMC Atrium Integrator Spoon is an optional feature that is used for designing and executing the
BMC Atrium Integrator Adaptor transformations and jobs. This is a stand alone application that can
be installed with or without any other products or components.
Note
BMC Atrium Integrator Spoon can be installed on Microsoft Windows only.
Configuration Types
The following sections show the required and optional features in sample configurations. These
sample configurations do not demonstrate all possibilities. BMC Remedy AR System is flexible,
adaptable, and scalable, so you can mix and match features as needed.
Note
The sample configurations shown in this section do not represent all possible
combinations. Configurations are also flexible; you can change your configuration any
time.
Extending configuration to multiple servers

You can extend your system configuration to include two or more BMC Remedy AR System
servers. For example, you can add another BMC Remedy AR System server exclusively for
development or several BMC Remedy AR System servers for production.
Each BMC Remedy AR System server communicates with one database. Multiple BMC Remedy
AR System servers can communicate with the same database.
You can install the mid tier and the required supporting features on a web server computer to allow
users to access BMC Remedy AR System through a browser. The web server and mid tier must be
installed on the same computer, and this computer can be networked to the BMC Remedy AR
System server computer. All features can be installed on the same computer, but verify that the
computer has adequate resources available (memory, disk space, processor power).
Client computers require a supported browser and Internet or intranet access for the mid tier
computer to access BMC Remedy AR System.
Page 167 of 4705
Home
Extending configuration to the Web

In addition to the required mid tier configuration, web configuration requires BMC Remedy Mid Tier
that resides on a web server computer. This is a supported web server, SDK (which includes the
JRE), a supported JavaServer Pages (JSP) engine, and a supported browser are required. A single
mid tier can access multiple BMC Remedy AR System servers.
For more information about Oracle Java products, go to http://www.oracle.com/us/technologies/java
/oracle-java-products-technologies-111089.html?ssSourceSiteId=ocomnl.
Extending configuration to include email access

To allow users to access BMC Remedy AR System through an email client and to receive email
notifications, you must install and configure the Email Engine on each instance of the BMC Remedy
AR System server.
The Email Engine configuration requires:
A mail server that supports either SMTP (on UNIX or Windows) or MAPI (on Windows only)
for outgoing mail, and POP3, IMAP4, MAPI, or MBOX for incoming mail. The mail server
must be accessible by the Email Engine.
Note
The MAPI protocol for incoming and outgoing mail is disabled for 64-bit Java Virtual
Machine (JVM).
A compatible version of Java for your operating system.

For more information, see Controlling BMC Remedy AR System through email .
Sizing factors and scalability

The information about the sizing factors and scalability for the BMC Remedy AR System
environment is documented in the BMC Remedy IT Service Management documentation at
Deployment architecture.
Installation and upgrade paths

Choose one of the following paths to install or upgrade BMC Remedy AR System:
New installation Run a new installation of BMC Remedy AR System.
Installation of a server group Install two or more servers in a server group.
Upgrade (with overlays) Upgrade with overlays already created. This is a four-stage
upgrade for customers who have previously installed AR System 7.6.04 and have already
implemented overlays.
Page 168 of 4705
Home
Upgrade (without overlays) Upgrade with one-time conversion to overlays. This is an

eight-stage upgrade for customers who do not already have overlays implemented and want
to keep all customizations.
Installation of the BMC Remedy ITSM Suite Preconfigured Stack installer (This takes you to
the BMC Remedy ITSM wiki space.) Run a solution-based installer that installs the BMC
Remedy AR System server and its components and ITSM applications on one server.
Silent installation Run the installer in a headless environment, or run the installer on
multiple systems at the same time.
Planning to upgrade BMC Remedy AR System

This section describes the methods of upgrading to the latest version of AR System and the ITSM
Suite. Choose one of the following upgrade options:
Overlays already present: Upgrade with overlays already created. This is a three-stage
upgrade for customers who have previously installed AR System 7.6.04 or 7.6.04 SP1/SP2
and have already implemented overlays.
Without overlays present: Upgrade with one-time conversion to overlays. This is a
seven-stage upgrade for customers who do not already have overlays implemented and
want to keep all customizations.
Upgrade stages
Overlays already present
Without overlays
Upgrade stage
Stage 1
Stage 1
Set up a staging server
Stage 2
Stage 2
Upgrade AR System server
Stage 3
Create overlays for existing customizations (optional but recommended)
Stage 4
Acquire origin objects (optional)
Stage 5
Restore origin objects on staging server (optional)
Stage 6
Minimize overlays (optional)
Stage 3
Stage 7
Upgrade applications and adjust customizations
Stage 4
Stage 8
Test and promote staging server to production
These stages are based on the assumption that your upgrade environment is already set up, and
that you have created and verified a staging server.
In an upgrade without overlays present, stages 3 through 6 are performed once when upgrading
from a previous release that was customized without overlays.
Page 169 of 4705
Home
Set up a staging server

If you are using the staged upgrade method (whether you already have overlays or not), you need
to set up a staging server.
Upgrading AR System server

In this stage, upgrade the AR System server. This stage must be performed before you can
upgrade to newer versions of any BMC applications or other platform components.
After completing this stage, you can upgrade and run your applications, or install new applications.
If you customized your application without using overlays and you upgrade after this stage, your
customizations will be lost.
Creating overlays for existing customizations (optional but recommended)

In this stage, create overlays to preserve your existing customizations. The application installers for
releases later than 7.6.04 SP2 are designed with the assumption that all customizations are
captured in overlays. The installers for these releases replace origin objects without attempting to
preserve any changes that might have been made to those objects.
If you upgrade to versions of applications without completing this stage, you must reapply all of
your customizations after upgrading, including additional custom fields and their data.
After completing this stage, all customizations are captured in overlays and custom objects. This
includes AR System customizations as well as all other applications and components.
Acquiring origin objects (optional)

In this stage, which is optional, acquire unmodified origin objects onto a reference server. The
origin objects are used to compare with your overlay objects.
After completing this stage, you can compare the overlays on your staging server to unmodified
origin objects on the reference server. This allows you to see exactly what has changed in any
object.
Restoring origin objects on staging server (optional)

In this stage, which is optional, move the new version's origin objects from your reference server to
your staging server.
If you perform the procedures in this stage, when your upgrade is complete, you can run either the
unmodified version of the application using only origin objects, or you can run your customized
version that uses overlays in place of overlaid origin objects.
After completing this stage, you have acquired copies of all of your origin objects in their original
state. This does not affect any overlays that you created.
Page 170 of 4705
Home
Minimizing overlays (optional)

In this stage, which is optional, minimize the number of overlays on your system. This reduces the
analysis required on subsequent application upgrades or patch installations.
When an overlaid object is modified during an upgrade, you should see if new functionality has
been introduced that should be added to the overlay.
After completing this stage, you have removed any unnecessary overlays on your system.
Upgrading applications and adjust customizations

In this stage, upgrade all of your applications and AR System components. Any existing
customizations to those items are preserved by making use of the overlays and custom objects that
were created in previous stages.
After completing this stage, you have upgraded your remaining AR System components and your
applications. Any overlays whose origin objects were modified during the upgrade process have
been identified.
Testing and promoting staging server to production

In this stage, test and promote the staging server to production --- Copy all modified data on your
current production system to the staging server using the Delta Data Migration tool. Promote the
staging server to be the new production server.
Related topics
Upgrading with overlays already present
Upgrading without overlays already present
Planning a server group installation

When using server groups, there are many things to decide, and it is important to map everything
out ahead of time.
How many servers do you plan to use?
Which applications and components will run on which servers?
What database type are you using?
What hardware do you need to support the servers?
What type of network connection and communication is needed?
Will you be using a load balancer?
Are the servers at the same geographic location?
Are you going to use the Distributed Server Option (DSO)?
Do you have a staging and testing environment?
If you will be using FTS, do you have access to a shard file system and the necessary
permissions configured?
Page 171 of 4705
Home
Answer these questions before starting a server group setup. Additionally, create a list of licenses
that will be needed for all products, including the AR System server licenses.
After you have answered these questions and license issues, continue to the following topics for
server group planning:
Server groups overview
Server roles
Example configurations
Understanding server group naming
Planning where software is installed in server groups
Server groups overview

Server groups are designed to work with BMC Remedy AR System in any type of supported
environment that has more than one server. This includes large distributed setups that make use of
hardware load balancers and the Distributed Server Option (DSO). The AR System server groups
feature provides failover management for crucial operations, server scalability, application-level
load balancing, and the sharing of floating licenses among the servers. A server group consists of
two or more AR System servers that are managed as a single unit. The servers share the same AR
System database, but perform workflow and database updates independently from each other.
Note
The servers within a server group need not have the same operating system, but you
should ensure that any workflow that interacts with the operating system will run on all
operating systems within the server group.
AR System servers in a server group
A server group acts as a single AR System server to support applications running on multiple AR
Page 172 of 4705
Home
System servers. The individual servers in the server group are configured to spread the load of
shared services, and to provide backup for each other to ensure that those services are always
available. BMC applications that are based on AR System, such as the BMC Atrium CMDB and its
related applications, as well as the BMC Remedy ITSM suite of applications can be installed and
configured to operate within a server group.
To ensure high availability of AR System operations, a server group can be configured to provide
failover protection by assigning rankings for specific AR System operations to the servers in the
group.
Benefits of using a server group

The following are the benefits of configuring your AR System implementation using a server group:
Heavy user traffic can be distributed across multiple AR System servers using a third-party
load balancer.
Automatic server failover (if a server goes down the system seamlessly keeps running).
Ease of administration; it has only one database to manage and back up.
AR System servers share all BMC software licenses except AR Server licenses.
There is one server designated as an administrative server. (When the workflow and
applications are handled on the administrative server, the changes are automatically
propagated to other servers in the group.)
Specific servers in the group can also be configured to handle reporting, reconciliation, and
other tasks that can impact performance, freeing up the remaining servers in the group to
handle user traffic.
Inexpensive servers can be added to a server group to increase the growth in users and
workload without having to replace or upgrade a single server. The environment is easier
and less expensive to scale.
Server groups also work in conjunction with hardware load balancers that direct user traffic to some
or all servers in the group. For best performance and reliability, BMC recommends that you use a
load balancer when implementing server groups. For specific details on using a load balancer, see
Configuring a hardware load balancer with BMC Remedy AR System and Using a load balancer
with server groups.
Recommendations on when to use a server group

Implement a server group if you require failover protection, or if you have a large environment that
requires multiple servers. AR System can be setup to run on multiple servers without using a server
group, and there may be some cases where that is the best solution, however the recommendation
for running multiple servers is to install them as a server group.
Note
Page 173 of 4705
Home
It is required to always use the exact same version and patch level for all BMC software
applications on each server included within a server group. And, to always upgrade each
application on each server within the server group at the same time.
Server roles
In a server group, each server is typically the primary owner of one or more specific roles. Each
role represents a specific BMC Remedy AR System application or component. In any server group
implementation, no matter how simple, there is one server that is configured the administration role.
This is typically the first server installed and is used to perform all administration operations for the
server group. Because all of the servers share the same database, this allows the group to be
managed as if it were a single server.
Other servers can be assigned specific primary roles. For example, a server might be dedicated to
just one specific primary task, such as Approval Server, while another server might be setup as a
primary server to host a group of roles that might be closely related such Atrium CMDB and Atrium
Integration Engine. The primary roles are configured on the AR System Server Group Operation
Ranking form, and each server should have at least one other server configured for failover.
Following is the complete list of server group roles for BMC software, as supported by the AR
System Server Group Operation Ranking form .
Administration Performs all administration tasks for the entire server group.
Approval Server The approval server provides the approval functionality within BMC
Remedy applications. An approval represents the signature or acknowledgment of an
individual where required in a process. The approval server records all necessary
information to provide an audit trail and proof of authenticity of all approvals.
Archive The archive feature of BMC Remedy AR System provides a convenient way to
periodically store data (not definitions) from a form to an archive form; this reduces the
amount of data accessed during searches on the main form thus improving system
performance. Archiving applies to all types of forms, except display-only forms.
Assignment Engine Using processes instead of workflow, the Assignment Engine
enables you to automatically assign requests to individuals. The assignment method
determines who is assigned to an issue when more than one person matches the
qualification.
Atrium Integration Engine The BMC Atrium Integration Engine (AIE) provides the hooks
to enable data to pass between AR System and other systems, such as an Enterprise
Resource Planning (ERP) system. AIE consists of the Data Exchange application and the
AIE service as well as a configuration tool and an event request interface.
Business Rules Engine The business rules engine is a component of BMC Service
Level Management that is used to interpret stored rules to construct the filters that are
required to implement the rules. The main form that the business rules engine is the SLA:
Business Rules form which contains references to objects required to create a filter.
Page 174 of 4705
Home
CMDB BMC Atrium Configuration Management Database. This is a core component of

any IT Service Management (ITSM) environment and adds substantial value to a simple
Incident Management environment. Specifically, it makes incident management more
efficient by providing support staff and IT management an up-to-date image of their
production IT environment.
DSO The BMC Remedy Distributed Server Option (DSO) is used to build large-scale,
distributed environments that behave like a single virtual system. DSO enables an
organization to share common information among geographically distributed servers and to
keep that information consistent. DSO enables you to transfer requests between servers and
to keep copies of a request synchronized across multiple servers, even if those servers are
geographically dispersed.
E-Mail Engine A server-based module provided with BMC Remedy AR System that
communicates with both the BMC Remedy AR System server and an email server. Email
Engine receives email messages and can parse and interpret the messages to execute
specific instructions on a BMC Remedy AR System form. It also sends email messages to
BMC Remedy AR System and directs notifications as a result of filters and escalations.
Escalation An escalation is an action or group of actions performed on the server at
specified times or time intervals. Basically, an escalation is an automated, time-based
process that searches for requests that match certain criteria at specified times and takes
actions based on the results of the search. For example, an escalation can trigger BMC
Remedy AR System to notify the next level of management if a problem is not assigned to a
technician within one hour of submission.
Flashboards A real-time visual monitoring tool that can show the state of service
operations, warn about potential problems, and collect and display trend data.
Full Text Index Full text index is the indexing feature for the full text search (FTS)
method used in BMC Remedy AR System to search for text in long text fields or attached
documents. It is typically much faster than using the native database searching functionality
Reconciliation Engine The reconciliation engine is a patent-pending component of the
BMC Atrium CMDB. The reconciliation engine is based on business rules, which allow you to
leverage existing data coming from third-party asset or discovery tools. The solution does
not lock you into any one vendor's discovery tools or existing asset repositories.
Example configurations
This section contains examples of a simple configuration and a complex configuration.
Simple example
In the simplest form, a server group can be setup with two AR System servers and a database
server. Each of the AR System servers have all Remedy products installed.
In this example, the first server installed should be configured to be the primary administration
server. Then, using the AR System Server Group Operation Ranking form , the applications should
be distributed evenly across both servers, so that each server handles about half of the load, and
each server has the other server configured for failover on each of its applications.
Page 175 of 4705
Home
The exception to this is the Email Engine and the Flashboards server. In a simple configuration,
those two items are only installed and configured on one server. Configuring failover for those
operations can be complex and may not be necessary in a simple configuration.
The full text search feature should be installed on each server. Each server has the ability to read
from FTS, but only one server can be set to write, which is the server that is set with a higher
priority on the AR System Server Group Operation Ranking form. It is also recommended that the
FTS collection directory (location where the search index files are stored) and FTS configuration
directory (location where the search configuration files are stored) be located on the same
computer.
Simple server group example
Complex example
A more complex server group implementation contains three or more AR System servers. In this
example we are using four AR System servers. It is still recommended to install all Remedy
products on each server, but it is not required. However, each application or component should be
installed on at least two servers so that failover can be provided.
Again, the first server installed should be configured to be the primary administration server. Then,
using the AR System Server Group Operation Ranking form , the applications are distributed evenly
across all four servers, so that each server handles about one quarter of the load, and each server
has at least one other server configured for failover on each of its applications and components.
Page 176 of 4705
Home
In this case, even the Email Engine server and the Flashboards have a failover server assigned.
Configuring failover for those operations is somewhat complex because it means that each server
has to be specifically configured to handle those items, but the secondary server for each is
suspended until the failover is activated.
Complex server group example
Note
The applications and components listed for the servers above are just the primary roles
for each server. It is recommended that all applications and components be installed on
each server. This is important because users could be accessing any components from
any server in the group, and there are dependencies such as plug-ins and other binary
files that could be called when a user opens certain forms, creates a new record, or
modifies a record.
In this example, FTS is setup on all the servers so that failover is possible. The FTS feature should
be installed on each server. It is also recommended that the FTS collection directory (location
where the search index files are stored) and FTS configuration directory (location where the search
configuration files are stored) be located on the same computer.
Related topics
Page 177 of 4705
Home
Understanding server group naming

For each server group, you define a common server name alias and apply it to each server in the
group. This alias identifies the server group in workflow so that the workflow can run correctly on
any server in the group. The alias is also used for items such as notification shortcuts and web
URLs used in notifications.
You must also define a unique name for each server in the group so that the servers in the group
can identify each other and so that you can direct administrative or specialized operations to a
specific server. Both the server alias name and the unique names must be able to resolve by DNS.
This documentation assumes that if there is more than one BMC Remedy AR System server
pointing to the same database, that work is directed to the individual servers via some automated
functionality (such as a hardware or software load balancer), or through manual configuration (such
as directing some users to one server and other users to another server). It is also possible that
one server is used primarily for users while the other server is used for automations and
integrations. In any case, the actual configurations for various settings, such as the server name
alias, need to be considered for the specific environments.
Server name alias

All AR System servers in a group must have the same server name parameter. This is specified in
the Administration Console as the Server Name Alias field. If your server group uses a load
balancer, the common server name parameter must be the same as the short DNS name of the
load balancer.
Note
Make sure that you use a name that will be translated to the IP address of the load
balancer. So, either the DNS should resolve the name or you must map the name in etc/
hosts file.
Clients can, therefore, be directed to the load balancer by using the server name parameter.
Note
If the server name alias setting is not the same as the load balancer short DNS name,
ARTask email attachments generated by the server might not work. When generating an
ARTask attachment, the server generates a reference to itself by using the server name
parameter with the domain name appended. Clients opening the ARTask will then use the
fully qualified domain name to be routed to the server group through the load balancer.
Page 178 of 4705
Home
Unique names for each server

Each server in a server group needs a uniquely defined name to identify itself to other servers in
the group. Usually this is the host name of the computer where the server is installed.
To identify the unique name for each server in the group, the following line is added to each
server's configuration file:
Server-Connect-Name:
<serverName>
DNS must be able to resolve this name, and it is used exactly as specified (that is, no domain name
is appended). Each server uses this name to register as a server group member. Other servers in
the group use the name when communication between servers is required. In addition, various
external server components use the name when connecting to the local server. This name can be
specified as either the short name or the fully qualified name.
Server group name

The server group name was used in some earlier releases in relationship to licensing, but it is no
longer necessary to set this value. In release 7.5.00 and later, this setting is not used. However,
there is still a field for it in the Administration Console. The field can be left blank.
Planning where software is installed in server groups

When installing server groups, make sure you know exactly what products you plan to install, and
determine which servers will be running each product. BMC recommends that you install all
products on all servers, and then to use the AR System Server Group Operation Ranking form to
distribute the load; however, there are may different ways to do this and each decision is based on
the specific implementation.
Create a list in a text file for each server and its IP address, as well as all accepted fully qualified
names. This saves you time when configuring the other servers. Each server must have the same
set of entries containing all resolvable names for each server. Include the IP address, short name,
and fully qualified name for each server in the server group and the load balancer, if one is used. In
the installation instructions, a two-system server group is used and the systems have the following
information. (Ensure to obtain similar information for your implementation before you start the
installation process.)
The following example uses a format that you can easily copy and paste into the ar.cfg files on the
servers in your server group. It includes the entire set of IP-Name entries for this example.
AR System Server 1:
IP-Name: svr_grp_tst0
IP-Name: svr_grp_tst0.svgroup.com
IP-Name: svr_grp_tst0.test.svgroup.com
IP-Name: 92.161.135.31
AR System Server 2:
Page 179 of 4705
Home
IP-Name: svr_grp_tst3
IP-Name: svr_grp_tst3.svgroup.com
IP-Name: svr_grp_tst3.test.svgroup.com
IP-Name: 92.163.169.2
Other Info Needed:
Server-Name (resolves to the load balancer name): RemedyServerGroup
Domain-Name: test.svgroup.com
Planning BMC Remedy AR System installation in an enterprise

environment
The following table helps you plan your BMC Remedy AR System implementation in an enterprise
environment. Each link in the column leads you to key information about the component such as;
knowledge of common issues that you might encounter, actions that you should avoid, security
considerations, and third-party for your enterprise setup.
Topic
AR System
Server
Mid tier
Email
Engine
Installing
Upgrading
tips
Before installing
the Mid Tier
Preparing to
install the
Email Engine
Security
Security
considerations
for BMC
Remedy AR
System
Security
considerations for
BMC Remedy AR
System
Securing
incoming and
outgoing
email
Access control
Access
control
User
authentication
Specifying
internal and
external
authentication
Scalability and
high availability
AR System
server
multithread
architecture
Load Balancing
Using a load
balancer with
server groups
BMC Remedy
Mid Tier
recommendations
Load
balancing
with Email
Engine
Distributed
deployment
Distributed
operations
introduction
Integration
technologies
Integration
capabilities
Assignment
Engine
Approval
Server
BMC Atrium CMDB
Preparing the AR
System server to
install BMC Atrium
Core and other BMC
applications
Configuring
the
Assignment
Engine
Security
considerations
for BMC
Remedy AR
System
Security
considerations for
BMC Remedy AR
System
Integrating with
CMDB
Page 180 of 4705
Home
Topic
AR System
Server
Mid tier
Email
Engine
Where to integrate
BMC Remedy AR
System
Web servers and
Preparing your
JSP/servlet
engines
web server
Proxy servers
Proxy server and

load balancer
settings
Single sign-on (
SSO)
Single sign-on
authentication
Assignment
Engine
Approval
Server
Integrating
the
Assignment
Engine into
an application
Integrating
Approval
Server with an
application
Assignment
engine logs
BMC Remedy
Approval
BMC Atrium CMDB
systems
integration
Log files and
monitoring
Collecting
diagnostics
BMC Remedy
Mid Tier logging
BMC
Remedy AR
System
Email Engine
BMC Atrium CMDB

log files
Server logging
logging levels
Performance
tuning
Performance
Tuning
Performance
tuning
Standards
BMC Remedy
AR System
BMC Remedy AR
System
standards
standards
Language
information
Language
information
Internationalization
and localization
Accessibility (508)
Configuring
Email Engine
for maximum
performance
Tuning
performance
for Approval
Server
Tuning the BMC

Atrium CMDB
performance
Section 508 rules

for application
designers
Common
problems and tips
Licensing
Troubleshooting
issues with BMC
Atrium CMDB
Licensing
Assignment
Engine
Working with
sample users
Import and
reconciliation
Reconciling data
Links to federated
systems
Configuring federated
data in BMC Atrium
CMDB
Page 181 of 4705
Home
Topic
AR System
Server
Mid tier
Email
Engine
Assignment
Engine
Approval
Server
Making changes
to classes or
attributes
BMC Atrium CMDB
Process overview for

creating or modifying
classes
Collecting
Gathering
Collecting BMC
Collecting
Collecting
Collecting
Collecting BMC
information for
support
information for
support
Remedy Mid Tier

information
BMC
Remedy
BMC
Remedy
BMC Remedy
Approval
Atrium CMDB
information
Email Engine
information
Assignment
Engine
Server
information
information
BSM environment recommendations

This topic provides information about the environments in which you should install BMC Remedy
AR System 8.1 as certified by the BSM Reference Stack and BSM Interoperability programs . These
programs provide information about validated use cases involving multiple BMC products and the
third-party products that support them. BMC recommends that you install software versions that
have been validated to work together by these programs, but the stacks validated by the programs
do not represent the only possible combinations of products. For additional information about the
compatible versions of BMC and third-party products for BMC Remedy AR System, see
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation.
BSM Interoperability
The BSM Interoperability program helps you install compatible versions of BMC products together
by testing an application stack of specific releases and verifying that they work together to
demonstrate key use cases. BMC Remedy AR System 8.1 was certified with BSM Interoperability
8.6.1 and some earlier releases of the application stack.
This section lists the products and applications tested in BSM Interoperability 8.6.1. For more
information such as a certified installation order, see the documentation for that release.
Application stack
The BSM Interoperability 8.6.1 release is compatible with BSM Reference Stack 3.0.
This section contains products and applications have been validated in BSM Interoperability 8.6.1:
Infrastructure platform
Atrium products
Cloud Lifecycle Management products
Service Operations - Application Performance Management products
Service Operations - Data Center Automation products
Page 182 of 4705
Home
Service Operations - Proactive Operations products

Service Support products
Mainframe integrations
The patch levels listed were the latest versions available at the time of testing. Patches are
cumulative and compatible except where otherwise noted in product documentation. Required
patches are available on the BMC Customer Support website at http://www.bmc.com/support.
To obtain necessary hotfix files and for more information about hotfixes, contact BMC Customer
Support.
Infrastructure platform
Product name
Version
Service
pack or
Function
patch
BMC Atrium
Core:
8.0
Provides a configuration management database (BMC Atrium CMDB) coupled with

common user, programmatic, and reporting interfaces to accelerate attainment of BSM.
BMC
BMC Atrium CMDB stores information about the configuration items (CIs) in your
Atrium
CMDB
IT environment and the relationships between them. Data consumers such as the
BMC Remedy Asset Management product read data from the production dataset.
BMC
Atrium
The BMC Atrium Integration Engine (AIE) product enables you to transfer data
between an external datastore and BMC Atrium CMDB or the BMC Remedy Action
Integrator
Product
Request System product.

The Product Catalog provides a normalized reference of software, hardware, and
Catalog
Service
other types of products and their characteristics that enhance the accuracy of BMC
Discovery products by uniquely identifying a product regardless of installed name
Catalog
Atrium
or location.
Web
Services
BMC Remedy
Action Request
System
8.0
BMC Atrium
Orchestrator
Platform
7.6.02 1
BMC Atrium
Orchestrator
Content
20.12.03
Enables the building of powerful business workflow applications which can automatically
track anything that is important to the processes in your enterprise. Companies use AR
System to track such diverse items as stock trades, benefits data, inventory assets, spare
parts, and order fulfillment. A common use of AR System is to automate the internal help
desk.
SP 4
Delivers workflow-based process templates, with which customers can rapidly adapt and
deploy functional design to ensure consistent and appropriate, policy-based response
across the enterprise.
Page 183 of 4705
Home
BMC Atrium
Solution or
suite
Product
name
Version
Service
pack or
patch
Function
BMC
Dashboards
and
Analytics
Suite
BMC
Analytics for
Business
Service
Management
7.6.05.002
Hotfix
Provides out-of-the-box interactive reporting and analysis that enables

technical and non-technical users to quickly examine data for trends and
details associated with how IT is supporting business services and goals.
BMC Atrium
Discovery
BMC Atrium
Discovery
8.3.2.2
and
Dependency
and
Dependency
Mapping
Mapping
BMC
BMC
7.7
7.6.03
Provides highly interactive, timely access to key service support metrics to
Dashboards
and
Dashboards
for Business
7.6.03
Hotfix 9
help IT management optimize decisions and accelerate the alignment of IT

with business goals.
Analytics
Suite
Service
Management
BMC
Remedy IT
Service
Management
BMC Service
Level
Management
8.0
Enables a service provider, such as an IT organization, a customer

support group, or an external service provider, to formally document the
needs of its customers or lines of business by using service level
agreements, and to provide the correct level of service to meet those
needs.
BMC
Remedy IT
BMC IT
Business
8.0
Provides IT leaders visibility into costs, activities, assets, resources, and

suppliers to effectively manage the IT business and ensure business
Service
Management
Management
Provides an automated method for discovering, cataloging, and

maintaining a company's configuration data.
alignment.
BMC Cloud Lifecycle Management

Solution or
suite
Product
name
Version
Service
pack or
patch
Function
BMC Cloud
Lifecycle
Management
BMC Cloud
Lifecycle
Management
3.0
SP1 +
hotfix
Provides a complete solution for establishing a cloud environment, including a

Service Catalog that defines service offerings, a self-service console for
procuring resources, and cloud management capabilities.
BMC Cloud
Lifecycle
Management
BMC Atrium
Orchestrator
Content
3.0
patch 2
Content for BMC Cloud Lifecycle Management.
BMC Cloud Lifecycle Management compatibility with BMC Atrium SSO is pending. BMC Cloud Lifecycle Management
is targeting a future release for full compatibility with BMC Atrium SSO. See SW00416103.
Page 184 of 4705
Home
Service Operations - Application Performance Management

Solution or
suite
Product name
Version
BMC
ProactiveNet
Performance
Management
BMC Transaction Management

Application Response Time,
Infrastructure Edition or Service
Level Edition
4.1
Service
pack or
patch
Function
Enables you to manage the performance and reliability

of your worldwide applications to measure site health
based on end-user experience metrics, such as
availability, accuracy, and performance.
Service Operations - Data Center Automation

Solution
or suite
Product
name
Version
Service
pack or
patch
Function
BMC
BladeLogic
BMC
Application
8.2.01
Automates the discrete tasks needed to deploy web applications and

dramatically simplifies the process, making it easier and less expensive for
Automation
Suite
Release
Automation
Add-on:
8.2.01
organizations to leverage web application server technology.
Enterprise
Edition
BMC
Application
Release
Automation
- Standard
Edition
BMC
BladeLogic
Automation
Suite
BMC
BladeLogic
Client
Automation
8.2.01 2
Enables administrators to manage software changes, manage content changes,

configure endpoints, and collect inventory information.
NA
BMC
BladeLogic
8.2.02
Integrates discovered configuration data with the BMC Remedy IT Service

Management suite of products. This integration enables you to use BMC
Client
Automation
Discovery
Integration
for CMDB
Remedy Asset Management, BMC Remedy Change Management, BMC

Remedy Incident Management, and BMC Remedy Problem Management to
access accurate, real-time information about IT infrastructure components across
your enterprise.
BMC
Bladelogic
Automation
Suite
BMC
Database
Automation
8.2.00
SP 1
Provides the essential capabilities for automated database provisioning and

maintenance, thereby removing bottlenecks in the change and release processes
and freeing Database Administrators (DBAs) to make more valuable use of their
time. As part of the BMC BladeLogic Automation Suite, it provides a
cross-operating system, cross-database vendor solution for automating database
changes and maintaining compliance across your enterprise database platforms.
BMC
Bladelogic
Automation
Suite
BMC
Decision
Support -Database
Automation
8.2
SP 1
Used with the BMC Database Automation solution to provide extensive reporting
capabilities based on the database devices that you manage.
8.2
SP 1
Page 185 of 4705
Home
Solution
or suite
Product
name
Version
Service
pack or
patch
Function
BMC
BladeLogic
Automation
Suite
BMC
BladeLogic
Decision
Support for
Network
Automation
BMC
BMC
BladeLogic
Automation
BladeLogic
Decision
related to your data center servers that are managed by BMC BladeLogic. BMC
Service Automation Reporting and Analytics uses rich data warehouse schema
Suite
Support for
Server
and dimensional modeling principles to access and report on historical data

captured by BMC BladeLogic.
A web-based reporting and analytics tool, used together with the BMC
BladeLogic Network Automation solution to provide extensive reporting
capabilities based on the network devices you manage.
8.2
SP 1
A web-based reporting application that provides extensive report capabilities
Automation
BMC
BMC
BladeLogic
Automation
BladeLogic
Integration
8.2
Suite
8.2.01
with Atrium
BMC
BladeLogic
Automation
Suite
8.2.01
BMC
BladeLogic
Network
Automation
8.2.02
BMC
BladeLogic
BMC
BladeLogic
8.2
Automation
Suite
Server
Automation
SP 1
Enables integration between BMC BladeLogic and Atrium components.
Manages change, configuration and compliance of network assets.
SP 1
Acts as a platform for the management, control and enforcement of configuration

changes in the data center.
8.2.01
2 8.2.00.001 is required if using BMC BladeLogic Client Automation for discovery for software license management use
cases.
Service Operations - Proactive Operations

Solution or
suite
Product name
Version
BMC
ProactiveNet
Performance
Management
BMC Capacity
Management Capacity
Optimization
9.0
Automatically analyze, forecast, and optimize performance and

capacity across all resources (IT and business) and environments
physical, virtual, and cloud.
BMC
ProactiveNet
Performance
Management
BMC Portal,
including
BMC Performance
Manager Portal 2.9
2.9.10*
Provides a common web-based interface for managing and monitoring

your IT infrastructure while monitoring business services.
PATROL
Service
Pack
or
Patch
Function
Provides monitoring for the BMC ProactiveNet Performance

Management suite.
Page 186 of 4705
Home
Solution or
suite
BMC
ProactiveNet
Performance
Management
Product name
Version
Service
Pack
or
Patch
Function
Agent, KM:
8.6 (7.5.62)
BMC
PATROL
Consoles
and
Infrastructure
7.8.12
BMC
PATROL for
Servers
9.11.00
BMC
ProactiveNet
Performance
Management
BMC ProactiveNet
Core
BMC ProactiveNet
Performance
Management
Reporting
9.0
A real-time analytics solution that detects performance abnormalities in

the IT environment, delivers early warning of degrading performance,
and reduces time from issue detection to resolution. This early warning
is delivered by Intelligent Events that result from analyzing and
correlating data across the monitored IT infrastructure, speeding the
ability to detect abnormal trends before end users and mission critical
applications are impacted. It also provides the users with views,
detailed graph displays, reports and other tools for diagnosing
performance issues.
BMC
BMC Transaction
4.1
Enables you to manage the performance and reliability of your
ProactiveNet
Performance
Management
Application
Management
Response Time,
either Infrastructure
worldwide applications to measure site health based on end-user

experience metrics, such as availability, accuracy, and performance.
Edition or Service
Level Edition
BMC
ProactiveNet
Performance
Management
Integration for BMC

Remedy Service
Desk
9.0
Patch 1
Provides the integration from certain Service Assurance products to

BMC Remedy IT Service Management.
Service Support
Solution or
suite
Product name
Version
BMC
Remedy IT
Service
Management
Suite
BMC Remedy IT Service

Management:
8.0
BMC Remedy
Asset Management
BMC Remedy
Change
Management
Service
Pack
or
Patch
Function
The BMC Remedy Asset Management application lets IT

professionals track and manage enterprise CIs - and their
changing relationships - throughout the entire CI lifecycle.
BMC Remedy Change Management provides IT organizations
with the ability to manage changes by enabling them to assess
impact, risk, and resource requirements, and then create plans
and automate approval functions for implementing changes.
Page 187 of 4705
Home
Solution or
suite
Product name
Version
Service
Pack
or
Patch
BMC Remedy
Service Desk,
including:
BMC
Remedy
Incident
Management
BMC
Remedy
Problem
Management
BMC
BMC Remedy Knowledge
Remedy IT
Service
Management
Suite
Management
BMC
Remedy IT
BMC Service Level

Management
Function
BMC Remedy Service Desk allows IT professionals to manage

incidents, problem investigations, known errors, and solution
database entries.
8.0
Allows users to author and search for solutions in a knowledge

base. It includes a comprehensive editor with extensive editing
tools and a robust search engine that allows users to search for
solutions using natural language or Boolean searches.
8.0
Service
Management
Provides a way to review, enforce, and report on the level of

service provided to ensure that adequate levels of service are
delivered in alignment with business needs at an acceptable
cost.
Suite
BMC
Remedy IT
Service
Management
Suite
BMC Service Request

Management
8.0
Allows IT to define offered services, publish those services in a

service catalog, and automate the fulfillment of those services
for their users.
Mainframe integrations
See the following documentation for information on mainframe integrations:
BMC Atrium Discovery and Dependency Mapping - Discovering Mainframe Computers
Information about using the z/OS agent and BMC Atrium Discovery and Dependency
Mapping to discover mainframe computers.
BMC Impact Integration for z/OS
Information about integration to the BEM/SIM cell architecture within BMC ProactiveNet
Performance Management.
BMC Middleware Monitoring and BMC Middleware Management Transaction Monitoring
Information about the integration of BMC ProactiveNet Performance Management and
middleware monitoring. Specifically, see the Installation Guides and Event User Guides for
these products.
Page 188 of 4705
Home
BSM Reference Stack

The BSM Reference Stack program helps you install BMC products with compatible versions of
third-party infrastructure products together by testing an infrastructure stack of specific releases and
verifying that they work together to demonstrate key use cases. BMC Remedy AR System 8.1 was
certified with BSM Reference Stack 2.1.00 and some earlier releases of the infrastructure stack.
This section lists the third-party products tested in BSM Reference Stack 2.1.00. For more
information, see the documentation for that release.
Infrastructure stackThe following tables contain information about the components and products in
BSM Reference Stack.
Infrastructure stack
The infrastructure stack represents the foundational components for the BSM Reference Stack
applications. You can choose to standardize on either the Windows or the Linux stack requirements
.
These guidelines do not represent the only possible infrastructure for BSM applications. Specific
infrastructure requirements can be found in product documentation.
Infrastructure Stack components
Component
Windows
Linux
OS
Windows 2008 R2 (64-bit)
Red Hat Enterprise Linux 5.5 (64-bit)
Database
MS-SQL 2008 Enterprise Edition SP 1 (64-bit)
Oracle Enterprise Edition 11g R1 (64-bit)
Application server
Tomcat 6.0.26 (64-bit)
Tomcat 6.0.26 (64-bit)
Web server
Apache 2.2 (32-bit)
Apache 2.2 (64-bit)
Reporting engine
BusinessObjects XI 3.1 SP3 or 4.0
BusinessObjects XI 3.1 SP 3 or 4.0
Java (JDK/JRE)
JDK/JRE 1.6.0_20*
JDK/JRE 1.6.0_20*
*see Oracle critical patch update notice
Oracle critical patch update

Oracle has issued a security advisory and critical patch update for multiple security vulnerabilities.
Details can be found on the Oracle site at this URL: http://www.oracle.com/us/technologies/security
/javacpujune2011-313339.html.
Application stack
BSM Interoperability 8.5.1 contains a detailed listing of the applications verified in this release, with
the exception of the following application, which is not part of the BSM Reference Stack:
BMC BladeLogic Client Automation Discovery Integration for CMDB
Page 189 of 4705
Home
Related topics
System requirements
Deployment architecture
This section contains the following information:
Email deployment use cases
BMC Remedy ITSM Suite 9.0 Solution Performance Benchmarks
For your reference, you can consult the ITSM deployment architecture documentation.
A typical deployment has the BMC Remedy Action Request System server platform with several
BMC applications installed on top of it:
BMC Remedy AR System server version 8.1
BMC Remedy Mid Tier
BMC Atrium Core
BMC Atrium CMDB version 8.1
Atrium Impact Simulator version 8.1
BMC Remedy ITSM Suite
BMC Remedy Asset Management version 8.1
BMC Remedy Change Management version 8.1
BMC Remedy Service Desk version 8.1
BMC Remedy Knowledge Management version 8.1
BMC Service Request Management version 8.1
BMC Service Level Management version 8.1
Email deployment use cases

This section provides use cases for deploying inbound and outbound email in the BMC Remedy
OnDemand 2013.01 environment.
Inbound email deployed in BMC Remedy OnDemand
Outbound email deployed in BMC Remedy OnDemand
Deployment example for inbound and outbound email
Volume testing results
All of these use cases have been tested for low, medium, and high email volume rates. The email
volume rates are defined as follows:
Page 190 of 4705
Home
Rate
Description
Low
10 emails every 5 minutes (peaks up to 30)
Medium
High
Inbound email deployed in BMC Remedy OnDemand

BMC Remedy OnDemand 2013.01 supports the following inbound email use cases where all
inbound email is routed through the BMC Remedy OnDemand mailbox server:
Use the default BMC Remedy OnDemand mailbox
Use the default BMC Remedy OnDemand mailbox and forward from the customer's mailbox
Data flow for inbound email
Note
The information provided in this topic might be helpful when you are considering deploying
applications in an on-premise environment.
All use cases were tested for the following environments and for low, medium, and high volume
rates:
BMC Remedy Email Engine installed in a server group with multiple BMC Remedy AR
System 8.0 servers
BMC Remedy Email Engine installed in a single BMC Remedy AR System 8.0 server
environment
Use the default BMC Remedy OnDemand mailbox

All inbound email is routed through the BMC Remedy OnDemand mailbox server.
For example, Joe Smith at joe.smith@calbro.onbmc.com receives an email notification about a
change that he needs to approve. The notification is sent from calbro@calbro.onbmc.com. Joe
clicks the Approve link in the email, which forms the response email. The response email is sent to
calbro@onbmc.com, and the change record is approved.
Note
In releases earlier than BMC Remedy OnDemand 2012.01, approval via email was not
supported out-of-the-box. However, approval via email can be configured by adding the
provided out-of-the box email template to the SYS:NotificationMessages form for the
Message tag that is used to send email approval notifications.
Page 191 of 4705
Home
Use the default BMC Remedy OnDemand mailbox and forward from the customer's mailbox
A secondary mailbox is set up by the customer, and the reply-to address in BMC Remedy
OnDemand for outbound email is set to the customer's mailbox address. The customer puts a
forward rule in their mailbox server to the onbmc.com email address.
For example, Joe Smith at joe.smith@calbro.onbmc.com receives an email notification about a
change that he needs to approve. The approval notification is sent from the BMC Remedy
OnDemand outgoing mailbox, which forwards it to changeapproval@calbro.onbmc.com (the
customer's reply-to address). Joe clicks the Approve link in the email, which forms the response
email. The email is sent to the customer's email server, which recognizes the email and forwards it
to calbro@onbmc.com. The system accepts the email and approves the change record.
Data flow for inbound email

The following diagram shows the data flow for inbound email.
For more information about this deployment use case, see Deployment example for inbound and
outbound email.
For information about including attachments with inbound email, see Creating an email generated
incident request.
Outbound email deployed in BMC Remedy OnDemand

Remedy OnDemand 2013.01 supports outbound email processing for the following environments
and for low, medium, and high volume rates:
Outbound email processing when the BMC Remedy Email Engine is installed in a server
group with multiple BMC Remedy AR System servers
Page 192 of 4705
Home
Outbound email processing when the BMC Remedy Email Engine is installed in a single
BMC Remedy AR System server environment
Note
The information provided in this topic might be helpful when you are considering deploying
applications in an on-premise environment.
This topic provides the following information:

Protocol used
Data flow for outbound email
Email notification configuration
Following are examples of outbound emails:
An approval notification for a change record sent to a customer
Assignment notification sent to a support group or support person
Notification sent to a customer that an incident has been created
Outbound email addresses are defined within people records, and the email IDs are picked up from
the user records.
Protocol used
Outbound email from the BMC Remedy OnDemand environment is sent using the OnBMC Simple
Mail Transfer Protocol (SMTP) server for delivery. No other protocols (for example, Messaging
Application Program Interface [MAPI] and the mbox email format) are supported. This limitation is
due to implementation complications associated with authentication and the potential
implementation of additional hosted software.
Data flow for outbound email

The following diagram shows the data flow for outbound email.
Page 193 of 4705
Home
Email notification configuration
Note
The BMC Remedy OnDemand Solution QA team performed the following configurations
to support this use case for BMC Remedy OnDemand 2013.01.
One mailbox must be designated as the default notification mailbox. Use the AR System Email
Mailbox Configuration form to configure the email mailbox and supply the following field values:
Field
Value
Mailbox Name
ARSYstemEmail - Outgoing
Mailbox Function
Outgoing
Status
Enabled
The following table indicates the values for the Basic Configuration tab for outbound email
notifications:
Field
Value
Email Server Type
SMTP
Polling interval
60 seconds
Email Server Requires SSL
No
Email Server Name/IP
CORPSMTP
Email Server Port
25
Page 194 of 4705
Home
Field
Value
Email Server User
Not applicable
Email Server Password
Not applicable
For more information about this deployment use case, see Deployment example for inbound and
outbound email.
Deployment example for inbound and outbound email

This deployment example shows how email can be deployed.
Business value
Architecture
Deployment models
Recommended settings for this deployment example
Configuring inbound and outbound emails
Related topics
Business value
This email deployment example provides the following business value:
You can submit incidents and update the affected records (for example, incident, problem,
work order, and task records) using email and can accomplish these tasks from multiple
locations.
Email is a simple and familiar means for accomplishing tasks.
You can provide correspondence that is directly tied to target records so there is no
opportunity for lost correspondence.
Architecture
Note
The icon shown in the following diagrams represents a software component or module:
.
The following diagram shows the components that make up this example deployment.
Components diagram
Page 195 of 4705
Home
For this example, the components include:

BMC Remedy AR System server instance with BMC Remedy Email Engine service
Incoming mail server, which in this example is a Postfix mail server configured to receive
email using Simple Mail Transfer Protocol (SMTP) and communicate with the BMC Remedy
Email Engine using Post Office Protocol version 3 (POP3)
Outgoing mail server, which in this example is a Postfix mail server configured to send email
using SMTP
A browser that is used to access a BMC Remedy application
A mail server (typically Microsoft Exchange) that is used to send and receive email via
SMTP over the internet
Note
You can use mail transfer agents (MTA) like qmail, Exim, and sendmail, or mail servers
like Microsoft Exchange.
After the BMC Remedy Email Engine is installed and started for the first time, it contacts the BMC
Remedy AR System server and reads all the entries in the AR System Email Mailbox Configuration
form and creates Incoming and Outgoing mailboxes based on the information. The BMC Remedy
Page 196 of 4705
Home
Email Engine polls the company mail server for incoming messages from query forms. It interprets
these query instructions and translates them into API calls to the BMC Remedy AR System server.
It also formats outgoing emails and sends them to the company mail server. The BMC Remedy AR
System server responds to BMC Remedy Email Engine API calls and queries the database. It
returns the results to the BMC Remedy Email Engine.
For more information about the BMC Remedy Email Engine architecture, see BMC Remedy Email
Engine architecture
Deployment models
The BMC Remedy Email Engine is deployed on the same VM as BMC Remedy AR System.
Incoming and outgoing mail servers, which are deployed as separate VMs, are considered shared
services.
The following diagram shows a single server deployment.
Single server deployment model
A variation to the preceding deployment model occurs when BMC Remedy AR System is deployed
in a server group. The following diagram shows the deployment of multiple BMC Remedy AR
System servers and one BMC Remedy Email Engine per BMC Remedy AR System server.
Server group architecture
Page 197 of 4705
Home
In the following diagram, BMC Remedy AR System server 1 and BMC Remedy AR System server
2 are in a server group. BMC Remedy AR System server 1 is the primary server, and BMC
Remedy AR System server 2 is the secondary server. If the primary server fails or is shut down,
then the secondary server starts and signals all its peripherals (for example, the Email Engine and
flashboards) to start working. However, if the BMC Remedy Email Engine service on the primary
server fails, then the BMC Remedy Email Engine on the secondary server will not start because
signaling works at the server level and not at the peripheral components' level.
Server group deployment model
Page 198 of 4705
Home
Recommendation
Deploy one BMC Remedy Email Engine per BMC Remedy AR System server to avoid
email disruption if one of the BMC Remedy AR System servers shuts down.
For information about configuring the BMC Remedy Email Engine for a server group, see
Configuring the Email Engine for a server group .
Recommended settings for this deployment example

The following table shows recommended settings.
Recommended settings
Setting
Value
Related information
InComing Email Protocol
POP3
For information about configuring BMC Remedy Email Engine

mailboxes, see Configuring BMC Remedy Email Engine
mailboxes.
InComing Polling Interval

minutes
60 seconds

mailboxes.
InComing Advanced
Email configuration tab
Default configurations
Page 199 of 4705
Home
Setting
Value
Related information
mailboxes.
Outgoing Email Protocol
SMTP

mailboxes.
Outgoing Polling interval

minutes
60 seconds

mailboxes.
Outgoing Advanced
Default configurations
Email configuration tab
Outgoing email daemon

properties

mailboxes.
MailboxPollingUnitslsMinutes =
false
For information about configuring the EmailDaemon.properties

file, see EmailDaemon.properties file.
OutgoingMessagesQueueSize =
400
Incoming email daemon
properties
IncomingConnectionRecycleSize
= 100
IncomingMessagesQueueSize =
100 MailboxPollingUnitlsMinutes =
false

NumberOfSenderThreads

Minimum and maximum

Java heap size
Minimum Java heap size = 256

MB (to be set in registry)
Maximum Java heap size = 1024
MB (to be set in registry)
For more information about configuring heap size, see Defining

a heap size for the BMC Remedy Email Engine .
Configuring inbound and outbound emails

To configure inbound and outbound emails, complete the following steps:
1. Configure your mail server, which includes setting up your mailboxes and the user for BMC
Remedy Email Engine.
2. Configure BMC Remedy Email Engine using the recommended settings listed in the
preceding table.
3. (Optional) You can choose to configure application-specific inbound and outbound email
rules (see Configuring the Email Rule Engine and Notification Engine configurations). If you
do not configure these rules, the rules are set by the default provided out-of-the-box rules.
Related topics
Preparing to install the Email Engine
Tuning the Email Engine performance
Load balancing with Email Engine
Page 200 of 4705
Home
Setting up incoming email

Setting up outgoing email
Volume testing results

BMC obtained the following volume testing results for BMC Remedy OnDemand 2013.01:
Note
A rule-based engine is used to process inbound email and create incidents. Incidents are
processed to create outbound notifications.
Volume testing results for inbound and outbound emails in a single server environment
Total
email
Email
load
Run
duration
Attachment
volume
Total
emails
= 2400
Inbound
emails =
600
10
minutes
No
Outbound
emails =
1800
Total
emails
Inbound
emails =
= 2400
Total
emails
= 2400
Average number
of emails read
Average
number of
Average CPU, BMC

Remedy AR System
emails
from Exchange
server
incidents
created
and email memory

utilized
Based on
incident
creation date =
27 minutes
40
22
N/A
50
23
N/A
40
21
N/A
30
19
Average processor
utilization: 55.190
Based on
incident
reported date =
15 minutes
Yes
Based on
incident
600
Size of one
attachment is
creation date =
26 minutes
Outbound
emails =
26 KB
1800
15.23 MB for
600 inbound
incident
reported date =
emails
12 minutes
Yes
Based on
incident
creation date =
28 minutes
Inbound
emails =
600
10
minutes
Based on
10
minutes
Multiple
attachments (
PDF,TXT and
XML)
Outbound
emails =
1800
15.23 MB for
600 inbound
emails
Total
emails
=
172800
Time taken to
process all
Inbound
emails =
43200
12 hours
Yes
Size of one
attachment is
Based on
incident
reported date =
15 minutes
Based on
incident
creation date =
38 hours
Page 201 of 4705
Home
Total
email
volume
Email
load
Run
duration
Outbound
emails =
129600
Total
emails
Inbound
emails =
=
172800
Attachment
Time taken to
process all
emails
Average number
of emails read
from Exchange
server
Average
number of
incidents
created
Average CPU, BMC

Remedy AR System
and email memory
utilized
48
22
Average processor
utilization: 53.344
26KB
1096 MB for
43200
inbound
emails
12 hours
Based on
incident
reported date =
24 hours
Yes
Based on
incident
43200
Size of one
attachment is
creation date =
33.30 hours
Outbound
emails =
26 KB
129600
1096 MB for
43200
inbound
emails
Based on
incident
reported date =
15 hours
Volume testing results for inbound and outbound emails in a server group environment
Total
email
volume
Email
load
Run
duration
Attachment
Time taken to
process all
emails
Average number
of emails read
from Exchange
server
Average
number of
incidents
created
Average CPU, BMC

Remedy AR System
and email memory
utilized
Total
emails
= 2400
Inbound
emails =
600
10
minutes
No
Based on
incident
creation date =
21 minutes
46
28
N/A
42
27
N/A
42
22
N/A
Outbound
emails =
1800
Total
emails
= 2400
Total
emails
= 2400
Inbound
emails =
600
Based on
incident
reported date
= 13 minutes
10
minutes
Yes
Size of one
Based on
incident
creation date =
Outbound
attachment is
26 KB
emails =
1800
15.23 MB for
Based on
incident
600 inbound
emails
reported date
= 14 minutes
Yes
Based on
incident
creation date =
27 minutes
Inbound
emails =
600
Outbound
emails =
1800
10
minutes
Multiple
attachments (
PDF, TXT and
XML)
22 minutes
Page 202 of 4705
Home
Total
email
volume
Email
load
Run
duration
Attachment
15.23 MB for
600 inbound
emails
Total
emails
Inbound
emails =
=
172800
12 hours
Time taken to
process all
emails
Average number
of emails read
from Exchange
server
Average
number of
incidents
created
Average CPU, BMC

Remedy AR System
and email memory
utilized
30
21
Average processor
utilization: 0.670 (BMC
Based on
incident
reported date
= 14 minutes
Yes
Based on
incident
43200
Size of one
attachment is
creation date =
33 hours
Remedy AR System box

)
Outbound
emails =
26 KB
Based on
Average processor
129600
1096 MB for
43200
incident
reported date
utilization: 34.083 (Email

)
inbound
emails
= 24 hours
Yes
Based on
incident
creation date =
28 hours
Remedy AR System box

)
Total
emails
Inbound
emails =
12 hours
30
26
Average processor
utilization: 1.493 (BMC
=
172800
43200
Size of one
attachment is
Outbound
emails =
26 KB
Based on
Average processor
129600
1096 MB for
43200
incident
reported date
Utilization: 54.211 (
Email)
inbound
emails
= 24 hours

The following topics provide information about how to fine-tune BMC Remedy AR System:
Tuning search performance
Performance benchmarking BMC Remedy applications

This section provides recommendations for benchmarking the performance of single user and
online multi-user loads with BMC Business Service Management products, batch processing of
BMC Atrium CMDB, and a mixed benchmark of online and batch.
This section provides the following topics:
Benchmarking for a single user
Benchmarking for OLTP
Batch benchmarking
Benchmarking for mixed workloads
Scoping project schedules
Checklists for benchmarking
Page 203 of 4705
Home
These topics include recommendations for designing test scenarios, data, and workload in a
manageable test environment, executing performance benchmarking tests, and interpreting test
results
Performance benchmarking overview

Information technology (IT) organizations face the challenge of managing complex environments
while delivering top-notch service. Their environments must function at high performance levels and
handle extreme loads during peak periods. Performance benchmarking helps IT organizations meet
this challenge by providing the following benefits:
Validates customer environments before going live
Reduces risk
Improves efficiency
Improves cost effectiveness
Improves the end-user experience
BMC Software conducts benchmarking for major releases using a standard set of transaction mix
and synthetic data. BMC recommends that customers conduct their own benchmarking. Each
customer environment can vary in terms of hardware, network infrastructure, operating system and
platform versions, customizations, integrations, data volume and distribution, and system usage.
Benchmarking provides the following:
Establishes a performance baseline
Evaluates the capacity of the system for current or future workload
Identifies performance issues and bottlenecks
Recommended tools
BMC recommends and uses the following testing tools:
Microfocus SilkPerformer an online load testing tool
HTTPWatch an online end user response tool
Benchmarking for a single user

A single-user benchmark is the first step in revealing system performance. From a single-user
standpoint, response time is the main factor for determining performance and is the easiest method
of benchmarking. However, use a systematic approach to perform repeatable tests.
Single-user benchmark factors
Measuring response time
Reporting results
Single-user benchmark factors

Consider the factors in this section at the start of every single-user benchmark.
Page 204 of 4705
Home
Environment stability
To ensure that your tests are repeatable, use a test environment that has no other activity running
while you take response times. Perform your tests when the mid tier usage and AR System server
CPU usage are below 10 percent. If the mid tier has just been restarted, ensure that preload
finishes running before you start testing. Verify that no antivirus software is running on the systems.
Time of day
When testing in a production environment, ensuring minimal system activity is difficult. In a
production environment, the time of day is significant, because the server load varies throughout
the workday. Depending on your testing goals, determine the best time of day to conduct your
single-user benchmark test. To ensure repeatability, conduct subsequent tests at the same time of
day.
Network latency
Network latency describes how long a packet of data takes to go from a client to a server. The
farther away a client is from the server, the longer the latency. A common type of network latency is
TCP latency, which is measured by the ping tool. Another type of latency is HTTP latency, which is
measured by the http-ping tool. Use these tools to measure the latency from the test client to the
mid tier. Repeatable tests should have the same latency.
Client environment
Select a test client system that is typical of your company's end-user hardware. If single-user
benchmarks are conducted from different locations, make sure each location's hardware is the
same.
Different browsers, and different browser versions, can give different performance results. Use a
browser and browser version that your company uses and that is compatible with BMC products.
For consistent results, test with the same browser and version.
Ensure the test client system has little to no activity during testing.
Browser caching
If your browser has cached mid-tier resources, performance results can vary. An uncached browser
is the first access to the mid tier. It does not have any images, javascripts, or stylesheets in the
browser's cache. These resources have to be downloaded, which lengthens the response time.
A cached browser already has the mid-tier resources in its cache. These resources have an
expiration date. (For these resources, BMC recommends an expiration date of one day.) After the
expiration date, a request is made to the mid tier for any updated resources. If there are no updates
, the mid tier responds with a 304 Not Modified{ message, which indicates to the browser to
read from the cache. If there are updates, the new resource is downloaded.
Use both cached and uncached methods. To use the uncached method, clean the browser's cache
of all cookies and resources. The uncached method is referred to as a First Session type, and the
cached method can be either a New Session or In Session type.
Session types
Page 205 of 4705
Home
In addition to browser caching, there is the concept of a First Session, a New Session, and an In
Session with respect to the mid-tier logon session. The following table describes session types for
mid-tier logon sessions:
Mid-tier logon session types
Mid-tier
Tasks
logon
session
First
session
Mid tier is cached

Browser is not cached
User logs on and opens console x or form Y. The browser is cached for the first time. Record this time. Log off.
New
session
Mid tier is cached

Browser is cached from the first session access
User logs on and opens console x or form Y for the first time within this session. Record this time.
For example, a support user logs on in the morning.
In
session
Mid tier is cached

Browser is cached from the First Session access
Page 206 of 4705
Home
Mid-tier
logon
session
Tasks
User has already logged on and opened console x and form Y

User reopens console x and form Y from within this session. Record this time.
For example, the remainder of the day after a support user logs on in the morning
Response times vary, depending on which session type is measured. In Session produces the
fastest response time of the session types, while First Session produces the slowest response
times. Record which type of measurements are captured. In Session is the most commonly
measured mid-tier logon session type because it describes the typical work environment.
Measuring response time

Measure client response time with a stopwatch or HTTP monitoring tool. A stopwatch includes all
browser rendering processing time, but it can be inaccurate with different users. HTTP monitoring
tools are more accurate, but they do not account for full resource rendering. The accuracy of HTTP
monitoring tools outweigh the full rendering. In any case, use the same tool for all tests.
Reporting results
Record your results for the tests in a report, such as the following sample spreadsheet:
Page 207 of 4705
Home
Sample spreadsheet for capturing response times
Benchmarking for OLTP

Running an online transaction processing (OLTP) benchmark requires much planning and analysis.
This section describes the procedures for developing a complete OLTP benchmark.
Designing tests
Setting up the test environment
Executing tests
Analyzing test results
Reporting results
Designing tests
Design your performance benchmarking tests to reflect your application's production requirements
and environment. Meaningful tests can take considerable time to design. This section provides
information about the components of good test design and guidelines for designing meaningful
tests:
Setting goals
Developing test scenarios
Evaluating volume with production or synthetic data
Determining workload
Gathering metrics
Integrate your test components to ensure that the tests work well as a whole.
Setting goals
To determine your goals for the benchmarking test, consider the following questions:
Are you developing a capacity plan for your organization's current status?
Are you planning for your organization's future growth?
Are you comparing the efficiency of various integration options?
What goals influence your design and keep your benchmarking project focused?
Business activities that warrant performance benchmark tests include the following activities:
New application implementation
Capacity planning
Application upgrade
Technology stack upgrade
Performance of critical business transactions
Increased user or data workload
Developing test scenarios
Page 208 of 4705
Home
Test scenarios are hypothetical use cases on which scripts for performance benchmarking tests are
based. When developing test scenarios, use the following guidelines:
Start small
Select typical business transactions
Imitate real-life usage
Write a script for each scenario
Prepopulate transaction data
Parameterize user input
Control random user input
Determine transaction contents
Include wait times
Test scripts thoroughly
Start small
Even though your organization might deploy several service support and delivery applications,
focus your first performance benchmarking project on one application. Subsequent benchmarking
projects can focus on application integration.
For example, the applications in the BMC Remedy IT Service Management (ITSM) Suite product
are designed to function together and with other BMC products, such as BMC Atrium CMDB, BMC
Service Level Management, and BMC Service Request Management. Benchmark each application
individually if possible. While designing your tests, remember that eventually all of these
applications are to be integrated into one test. The individual tests should share the same set of
foundation data, such as people, company, locations, regions, and product catalogs.
Most applications perform many actions, and you could write test scripts for each action. Instead,
look at common actions that best simulate how your organization uses an application.
For example, in BMC Service Request Management, users update their application preferences but
not on a daily basis. Instead, users frequently use the Service Request Console as the starting
point for most activities. Scenarios that include Service Request Console interaction have greater
benchmarking value than scenarios that include preference changes. Use the "daily basis" rule to
reduce the number of scenarios that you include in your tests.
Also, consider the type of users involved in each scenario. For example, scenarios can include
administrators or support users. In Incident Management, support users can create tickets on
behalf of end users and search for, modify, and resolve incidents. Support users are more active
than administrators. Scripting support actions instead of administrative actions is a better way to
benchmark typical use for this application.
Imitate real-life usage
Effective test scenarios reflect how users actually use their applications.
Page 209 of 4705
Home
To determine how applications are used in a production environment, look at the web server logs.
For new applications, typical actions include creating, searching for, modifying, and viewing records
.
For example, end users best access the BMC Service Request Management application only
through the Service Request Console. They can then create service requests, view their open
requests, modify their open requests, search for service requests, modify their preferences, and
provide feedback. In your test scenarios, mirror the steps that real-life users perform.
Also, match the application setup data and configuration with your production implementation. For
example, in BMC Service Request Management, configure the catalogs, entitlements, and service
questions.
Ensure that the test environment has production data volume. Test scenarios and environments
that parallel actual implementations yield more accurate results. For more information, see
Evaluating volume with production or synthetic data .
Write a script for each scenario
Ensure that each test scenario has its own script. This gives you better control over how many
virtual users execute each script.
For example, in an ITSM performance benchmarking test, support users can modify an incident to
resolve status, search records via global search, create an incident, create a change, search for a
change, modify a change to closure, update a work order, and search and view Knowledge Base
articles. Each of these actions can have its own script.
Some actions, such as modifying, require preexisting data. For example, in Incident Management,
support users can view and modify their assigned tickets. These scenarios require tickets to
preexist or to be generated dynamically during performance tests. Consider the need for preexisting
tickets when designing the test database. For more information, see Evaluating volume with
production or synthetic data.
Generating tickets during a view or modify scenario requires a create action. In this case,
preexisting data is preferable because it follows the autonomous scenario rule: one main action per
script. For production data, determine the support users with assigned tickets. For more information
, see Evaluating volume with production or synthetic data .
Ensure that test scripts are portable. Portable scripts are not tied to specific users, servers, or input.
Note
Parameterize some of the data that end users supply.
Make the data used to query other information dynamic to ensure that cached data is not
used.
Page 210 of 4705
Home
For example, all ITSM applications require a web server host name and port number, an AR
System server name, and a logon user name and password. Hard-coding these values into test
scripts makes it difficult to change test environments. To make scripts portable so that they can be
easily changed, store these values in program variables. Also, store script input data in text files or
program variables.
Although scripts typically include random input to simulate variability, control randomness to
achieve a known output or a known output range. This control is especially critical for searches. To
ensure that searches do not return unlimited results, design your baseline data appropriately.
Controlled input data also makes script runs repeatable.
For example, when a support user logs in, the overview console lists all tickets assigned to the
logged-on user. In a synthetic data environment, ensure that each of the support users used does
not have thousands of assigned tickets. In a production environment, it is unlikely that a support
user would have thousands of assigned tickets.
A load-generation transaction is a set of actions. When developing test scenarios, determine which
actions belong in each scripted load-generation transaction.
Although a script typically has only one main action, several steps such as logging on are
usually required to get to that action. In cases like this, make the following decisions:
Whether all the steps belong in one transaction
Whether the transaction repeats throughout the performance test
For example, a support user in an Incident Management performance benchmarking test might not
need to log on at the beginning of each iteration. In real life, a support user logs on once and stays
on for the rest of the workday. An end user often logs on, performs a task, and then logs off. For
support users, the repeated transaction consists only of the main task, not one-time actions such as
logging on and off.
Include wait times
Script a scenario exactly as end users manually perform it. Include all the steps leading up to the
main action. Also, insert wait times periods when users are idle while thinking or while waiting for
applications to process their commands throughout the script. Wait times can be a range of
minimum and maximum values and correspond to the throughput rate. For more information, see
Determining workload.
Test all scripts before you use them in performance tests. Scripts typically run for multiple users
and multiple iterations during a performance test. Run the test as follows:
1. Run a single iteration for a single user.
2. Check for errors.
3. Run multiple iterations for a single user.
5.
Page 211 of 4705
Home
5. Run multiple iterations for multiple users.

Evaluating volume with production or synthetic data

Depending on your benchmarking goals, you can use real production data or synthetic data in the
test database.
Using production data in the test database provides the following benefits:
Produces realistic results for benchmarking current production
Shows performance changes from old to new applications
Determines whether an upgrade will work for your organization
Validates synthetic data
However, you can generate synthetic data to demonstrate benchmark scalability. You must use
synthetic data when production data is unavailable.
This topic includes the following information:
Using production data
Determine users with assigned tickets
Determine users with proper permissions
Modify user passwords
Determine search criteria
Back up the test production database
Using synthetic data
Plan data creation to support test scenarios
Determine optimal database size
Determine optimal row entry size
Vary data generation order
Back up the test database
Using production data
Using production data requires knowledge of what is in the production database. To use production
data, take a snapshot of the production database and use the snapshot for all tests.
When using production data, use the following guidelines:
Page 212 of 4705
Home
If Update Incident or Update Change is involved in your transactions, tickets must be updated. Only
users assigned to work on open tickets can perform updates you must know who these users
are.
For example, if you query the HPD:Help Desk form by Assignee and the Assigned, In Progress, or
Pending status and then group the results by Assignee name, you have the names of users who
have open tickets. This query also shows the number of tickets that each user has, which can be
important, depending on your update scenario. If the update is to close the ticket, after the ticket is
closed, it is no longer available. However, if the update is simply to add a work log entry, having
unique entries to update might not be as important.
For change tickets, any user who belongs to the Infrastructure Change User group can modify any
change tickets.
Aside from updates, transactions must have appropriate permissions to run correctly. An AR
System administrator user who is also an application administrator must query the People and
People Permission Group forms.
The following table shows the minimum application permissions required for the most common
actions.
Action
Application permission group
Create Incident
Incident Submitter
Update Incident
Incident User
Search Incident
Incident Viewer
Create Change
Infrastructure Change Submitter
Update Change
Infrastructure Change User
Search Change
Infrastructure Change Viewer
For example, query the CTM:People Permission Groups by the Permission Group field for the
application permission group values in the table.
Application permissions use a superseding model in the following order:
1. Incident Master
2. Incident User
3. Incident Submitter
4. Incident Viewer
Page 213 of 4705
Home
To find users, start with users with the most permissions. Because Incident Master has all incident
permissions, it can perform Search, Create, and Update Incident transactions. So Can Incident
User. Systematic querying from top to bottom yields the proper users that can be divided for each
transaction. Some users can be members of more than one Incident Management permission
group. Also, users can have not only Incident Management permissions but also other application
permissions.
The following example shows a systematic query for a test that consists of only Incident
Management and Infrastructure Change transactions. Excluding Infrastructure Change permission
groups prevents double use of users in Incident and Change transactions. Excluding users that
were found with assigned tickets also eliminates double use.
1. Query for Incident Master permissions, excluding the Infrastructure Change permission
group and users with assigned tickets.
a. Select users for the following transactions in this order: Update Incident, Create
Incident, Search Incident.
b. If the number of users is not enough for all Search, Create, and Update Incident
transactions, go to step 2.
2. Query for Incident User permissions, excluding Incident Master and Infrastructure Change
permission groups and users with assigned tickets.
3. Query for Incident Submitter permissions, excluding Incident Master, Incident User, and
Infrastructure Change permission groups.
4. Query for Incident Viewer permissions, excluding Incident Master, Incident User, Incident
Submitter, and Infrastructure Change permission groups.
b. If the number of users is not enough for your workload, select users for the
combination of Search and Update Incident transactions, adjust the workload, or add
permissions to existing users.
After users have been defined, modifying the user passwords to one common value facilitates
executing load tests.
Modify passwords for a known set of users through a simple program or through SQL by modifying
the Password field of the User form.
Page 214 of 4705
Home
For searches involving incidents and changes, select a search criterion that returns enough results
to be relevant (for example, 300 entries). Use a search criterion that returns a range of results
instead of random results. Searches can return thousands of records if Max Entries Returned By
GetList, an AR System configuration parameter, is unlimited.
Back up the test production database after you finish modifying data. A backup database enables
you to restore your test database to its initial state and to use it on other systems.
Using synthetic data
Synthetic data is built from the ground up, so test designers are familiar with each detail. This
familiarity enables them to better control test scenarios.
When generating synthetic data, use the following guidelines:
While planning test scenarios, determine the data required to perform the actions. For example,
BMC Remedy IT Service Management applications have many types of users, including end users,
support users, managers, and administrators. These users must belong to a company organization
or department and have specific roles. In Incident Management, end users usually select options
from a menu of incident categories for which they can submit tickets. The menu options must be
created. Consider these data requirements during the design process.
BMC recommends using users that have unique logon IDs instead of administrator users. Although
you can reuse the administrator user logon IDs multiple times to simulate work, reusing the same
user does not test the system. Each unique user is allocated its own data structure and has access
checks more often by the AR System server.
Total database size is important. Benchmarking goals define the maturity of the database. If you
are benchmarking for future growth, ensure that the database has a healthy amount of data. Some
database tables might have one million rows. A database with only 5,000 rows might yield different
results. Match the database size to your goals.
Row size affects test results. Row size can affect response times over the network small entries
require fewer bits to be transmitted than large entries. Consider the average row size that supports
your goals. For example, a table that has only three of thirty columns filled is a small entry.
Page 215 of 4705
Home
When generating data, ensure that you vary the generation order. A synthetic test database follows
a pattern because its data is generated in bulk, as opposed to data in a production database.
Creating entries nonsequentially for a particular user is more realistic.
Also, ensure that the data distribution is correct. For example, when incident tickets are generated,
the status of most tickets should be Closed; only a few should be Open.
Back up the test database after you finish generating data. A backup database enables you to
restore your test database to its initial state and to use it on other systems.
Determining workload
In addition to designing the test scenarios and deciding what data to use, you must determine the
number of users for running the scenarios and how fast the scenarios are executed. Service level
agreements help with planning. The workload drives the performance test, and the benchmarking
goals drive the workload setup.
This topic includes the following guidelines for determining the workload:
Set transaction pacing for throughput
Set the user percentage mix
Determine caching requirements
Generate throughput by using wait times
Successively ramp up users
Maintain a steady state
License applications and users
Set transaction pacing for throughput
Transaction pacing is the number of transactions that an end user performs in an hour. This pacing
produces the throughput for the entire performance test.
Throughput is the how fast aspect of the workload the speed at which scenarios are run. To set
the speed for one user performing a scenario, use one script for each scenario. Each scenario can
have a different throughput.
For example, for three scenarios create, search, and view. Creating is the action that is
performed most often. After gathering statistics, you find that approximately 100 entries are created
every hour in your production environment.
Set the user percentage mix
The percentage of users running scenarios is the how many aspect of the workload. To compare
when users are scaled, use a percentage of the total users instead of a fixed number. For example,
if 20 percent of the total users perform the Create action, that is 100 of 500 total users and 200 of
1,000 total users.
Also, ensure that users perform a realistic mix of View and Create transactions, such as 70 percent
View and 30 percent Create.
Page 216 of 4705
Home
Ensure that test users have the same privileges as real-life users. For example, do not give
administrator privileges to end users.
The following table is an example of a summary for planning transaction pacing and user
percentage mix for the Service Request Management and Incident Management applications:
Transaction pacing and user percentage mix table
Transaction name
Percentage of users
Transaction pacing
(transactions/user/hour)
Global search
Update change
Search change
Create change
View service request
10
Update incident
10
Create service request
12
Browse service categories
Create incident
Search for incidents
15
Lookup service context
Update work order
Search service request
15
Knowledge search and view
Determine caching requirements
BMC Remedy AR System uses caching in the mid tier and AR System server. Caching is also done
in the web browser. In a load testing environment, browser caching can be simulated. When a
script repeats during a performance test, consider each end user who logs back on as a return user
. In a real-life company, most employees log on to an application once a day, and do not clear their
browser cache at the end of the day. When browser caching is used, it reduces the number of
HTTP requests and network traffic. Items such as images do not need to be requested each time a
page is displayed.
In the mid tier, caching is done regardless of whether browser caching is enabled. Mid-tier caching
is done by AR System group permission, and the first access always takes the longest time. To fill
the mid tier and AR System server caches, BMC recommends that you run a sanity check before a
performance test and ramp up users.
Generate throughput by using wait times
Workload pacing can also be achieved by using user wait times. User wait times belong in the test
scenarios. Ensure that wait times are designed to produce the assigned throughput.
Page 217 of 4705
Home
Successively ramp up users
Ramping up users one after another, instead of all at once, paces their logons to your application at
the beginning of a performance test. Use successive ramp-ups to prevent overloading your test
environment, build up your cache, and avoid scenario lockstepping.
The following figure shows a 600-user ramp-up at a pace of one user every three seconds. The flat
line is the steady-state period.
Ramping up users to a steady-state period
Maintain a steady state
Ramping up leads to a steady-state period in which every user has a chance to log on once. During
the steady-state period, make your measurements. Depending on your throughput, maintaining at
least a one-hour steady-state period provides a good set of data points. The steady state stops
before users start ramping down to end the test.
License applications and users
All BMC applications require a license, and various users require different types of licenses. Ensure
that sufficient licenses are available for the workload.
The load generation tool also requires licenses and might restrict the number of virtual users. Verify
that the load generation tool does not limit the workload.
Gathering metrics
This topic identifies the information to gather during benchmark performance tests:
Roundtrip response time
Transaction throughput
System, network, and database statistics
Roundtrip response time
Most scenarios contain many steps, but usually just a few steps are worth measuring and reporting.
Roundtrip response time is one metric that affects most users. For example, roundtrip response
time can be the time for a user to respond after clicking a button.
Page 218 of 4705
Home
When writing your test scenarios, determine the actions that the test measures. The following table
shows an example of a set of steps, or actions, in a Create Incident transaction. It also shows
whether the actions are repeated and timed.
Actions in an example Search Change by ID transaction
Transaction
Phase
Transaction steps
Repeat?
Timed?
Search Change By ID
Initialization
Configure load generator settings
No
No
Not applicable
Transaction
As a support change user, log on to the homepage
No
No
Not applicable
Not
applicable
Click Change Management Console link
No, refresh sometimes
Yes
Not applicable
Not
Open the Change form in Search mode
Yes
Randomly enter a Change entry ID and click Search
Yes
Yes
applicable
Not applicable
Not
applicable
Not applicable
Not
applicable
Log out
No
No
Not applicable
End
Close any open files
No
No
Transaction throughput
Transaction throughput is as important as the number of users. For example, compare the following
tests:
1,000 users perform 10 transactions per hour, producing 10,000 transactions per hour
500 users perform 30 transactions per hour, producing 15,000 transactions per hour
The 1,000-user test has more users, but they are not as active as users in the 500-user test. A
system can handle many users concurrently if transaction throughput is minimal. Tracking user
count without transaction throughput is meaningless. To determine the total system throughput,
track both user count and transaction throughput.
System, network, and database statistics
Use system resource metrics and database statistics to ensure that your test runs at the
established throughput.
Metrics for the CPU, memory, network, and disk input/output (I/O) might identify bottlenecks that
impact scalability. To observe system behavior in relation to the workload, take system metrics
during performance tests. Total system resources, per-process resources, and database statistics
gathered during the steady state help identify performance issues. Ensure that gathering this data
does not bottleneck the test.

This topic explains how to set up your test environment:
Run in a controlled environment
Page 219 of 4705
Home
Start with a basic configuration

Use one system per tier
Test in WAN and LAN environments
Run in a controlled environment

The benchmark test environment is crucial to a meaningful test. Ensure that your environment
model supports your test goals. Isolate all test environments from other activities so that the tests
can be run multiple times to demonstrate repeatable results. If you need to create a model for
future use, several environments might be needed.
Select the appropriate network configuration, hardware, and software versions for your test
environment. Use a basic hardware and software configuration as a starting point.
Avoid over-configuring on the first pass of the test. Adjust the configuration only when problems
arise, and make organized adjustments.

At a minimum, BMC conducts performance benchmarking tests by using a single system for each
tier. This keeps system resource monitoring of each tier independent from other tiers, prevents
resource bottlenecks, and provides sizing information for each tier. This is the recommended
architecture for production.
The following figure shows an example of a benchmarking setup for a small environment.
Benchmarking environment setup example
Page 220 of 4705
Home
Test in WAN and LAN environments

Many IT organizations run a global corporation with servers and clients located around the world.
To test high- and low-latency environments, Ensure that the core test servers remain in one area
while the location of the client varies. Select a typical WAN and LAN location in which to run your
load tests. For convenience, use a WAN emulator.
Executing tests
Ensure that your benchmark tests are repeatable. Run the tests systematically. By using a
thorough checklist, others can duplicate your test results.
When creating an OLTP checklist, consider including the following items:
Restore the database to baseline data
Restore all tiers to their initial state, remove old logs, and restart the application
Verify that no other activities are on the system
Set basic system and software configuration
Capture system and software configurations before running the test
Run a sanity check on all scripts
Simultaneously start the performance test and start monitoring system resources on all tiers
Record the start and end times of the steady-state period (monitor system resources only
during steady state)
Page 221 of 4705
Home
Measure single-user timings during the load to get the full end-user experience response
Visually monitor performance tests for problems; if part of a test stops responding, stop the
test and debug the issue
When the performance test ends, stop system resource monitoring
Validate load generator report results with transaction counts from the AR System server (for
example, verify that the reported number of incidents created by the load generator matches
the number actually created)
Save logs and results for each tier and label your test results
Analyzing test results

This topic explains how to analyze test results:
Analyze results after each test run
Check the CPU threshold
Check the memory threshold
Check for input-output bottlenecks
Check the network bandwidth
Check the load-generator environment
Check scenario input
Check steady-state response times
Use graphs
Make one change at a time

Analyze results after each test run. If something goes wrong in a run, do not continue to another
run if scalability is the issue. Check for errors by reviewing the logs of each tier not just by
looking at load generator system reports.
When you run performance benchmark tests, a calibration process usually attempts to validate the
tools. It also involves an iterative process that includes running the test, identifying the bottleneck,
tuning the bottleneck, and then rerunning the test.
Check the CPU threshold

On average, a healthy system uses 75 percent or less of its CPU. The remaining 25 percent of the
CPU is reserved for sudden, unforeseen processing power demands. If CPU use seems low, check
for an I/O bottleneck. If CPU use is unreasonably low but response times are good, the throughput
might be too slow. If throughput is at the desired rate, the results indicate systems are underused,
and you could use a lower-end system instead.
When checking the system on which the AR System server is installed, look at all the processes
associated with AR System, such as BMC Remedy Approval Server, BMC Remedy Assignment
Engine, the AR System plug-in server, AR System Java plug-ins, Email Engine, and BMC Atrium
Configuration Management Database (CMDB). One of these processes might be causing a high
total CPU use instead of the AR System server process itself.
Check the memory threshold
Page 222 of 4705
Home
Memory use can be difficult to analyze. You can observe memory use by using the following
guidelines:
For Java-based applications, a maximum Java virtual machine (JVM) heap size is specified
at startup. The heap size determines the maximum memory that the JVM can reserve. If
given a large amount of memory, the JVM uses it. If memory grows during a steady-state
period, a memory leak does not necessarily exist.
For non-Java-based applications, memory generally remains stable during the steady-state
period. The cache has been filled, and reading from cache usually does not require more
memory.
If resource measurements were taken for each process, you can obtain memory use data
from startup, which helps with memory capacity planning.
Total memory use can be calculated by subtracting the lowest amount of free memory during
the steady state from the amount of memory that is free while the environment is down. The
difference is the maximum memory used during the steady state.
Check for input-output bottlenecks

I/O statistics are most relevant for systems that do substantial reading and writing to disk, such as
databases. Check database statistics for I/O bottlenecks.
Check the network bandwidth
If CPU use, memory use, and I/O seem normal but throughput and response times do not meet
your expectations, network problems might be the issue. Review the web server logs and network
statistics for signs of dropped connections. During tests, ping the systems for roundtrip response
time. An isolated test network prevents outside activities from skewing the test results.
Check the load-generator environment
Bottlenecks might occur in the load-generator environment. Ensure that this environment is healthy.
A load-generator environment typically consists of the following computer systems:
One controller that executes scripts, tracks statistics, and manages agents
Multiple agents that only run scripts
Calibrate to verify that the load-generator environment is not skewing the performance data.
For example, if running 2,000 virtual users on a single controller system does not yield the
same throughput as running 1,000 virtual users on one agent and another 1,000 virtual
users on another agent, the controller system is bottlenecked.
Before beginning actual tests, verify the maximum throughput that a single load-generator controller
system can handle. Checking this by verifying CPU use. If CPU and memory use are at their
threshold (about 75 percent), consider using load-generator agents to farm out the work. Ensure
that the agent systems are in the isolated test network.
Check scenario input

Sometimes, a problem might be in the test scenario's input. Ensure that you thoroughly test the
scenarios before using them in a live performance test. Problems might occur during load testing.
Check steady-state response times
Page 223 of 4705
Home
Record response times from the steady-state period by looking at averages and percentiles. You
can typically obtain these numbers from your load-generator reporting tool.
Percentiles give a better sense of how long most responses take than averages do. A percentile is
a value on a scale of one hundred that indicates the percent of response times that are equal to or
less than the value. For example, if a 2.5-second response time is in the 20th percentile, 20 percent
of the response times are 2.5 seconds or less.
Percentiles help identify outlier values that can occur infrequently. For example, if a big gap exists
between the 85th and 90th percentile, a few outlier values in the 90th percentile are probably
skewing the 90th percentile value. In this case, the outliers can be dismissed as anomalies. Repeat
the test to verify that they are deviations from the norm. A longer steady-state period produces
more data points, which in turn creates more stable percentiles.
Use graphs
During test analysis, chart your results to help with interpretation. To determine whether a
response-time metric has many outliers, use a histogram, which is a bar graph of a frequency
distribution. For example, the histogram in the following figure shows the frequency of a set of
response times for a particular action. Most of the data points fall at 2.66 seconds.
Histogram for one action
Page 224 of 4705
Home
After a problem is diagnosed, resolving it might take several attempts if configuration changes are
required. To help verify whether a change made a difference, make only one configuration change
per rerun.
To save time, decide which configuration change is most advantageous. If several configuration
changes might be needed, combine configuration changes that are related to each other in one
rerun.
Reporting results
This topic explains how to report test results:
Keep it simple
Summarize the workload
Show results based on goals
Summarize throughput results
List the environment, hardware, and software configurations
Keep it simple
When all performance tests are successful, they are ready for presentation to a wider audience.
If the tests have generated considerable data, you do not need to publish all of it. A general
audience can understand response times, average CPU use, and memory use, but not details such
as logs. A high-level summary with charts and graphs is sufficient.
Summarize the workload
Summarize the workload and how the test was run. Include the initial database volume, an
environment topology diagram, product scenario flows and expected throughput, the percentage of
users for each scenario, and user ramp-up time.
Ensure that your report shows results based on your identified goals. If scalability is your goal,
present your findings using graphs showing CPU use, memory use, and response times from one
workload to another. Accompany each graph with a brief analysis.
The following figure shows CPU use on three tiers for three different loads. With each increasing
load, CPU use grew marginally and remained parallel among the tiers.
CPU scalability chart example
Page 225 of 4705
Home
Summarize throughput results

Providing a table of throughput values is informative. For example, in the Service Request
Management application, end users can create services. The application converts these services
into incidents, change requests, or work orders. A table that shows how many tickets of each type
were created during a test run can illustrate the throughput distribution.
The following table shows the number of such tickets created during a steady-state period.
Throughput in steady state (example)
Business metrics
700 users
900 users
1,000 users
Incidents created
2,601
3,314
3,360
Change requests created
1,521
1,992
2,021
Work orders created
566
687
695
List the environment, hardware, and software configurations

To complete the report, add an appendix of the environment specifications and the software and
hardware configurations used during the tests.
Batch benchmarking
Batch benchmarking refers to load testing a series of calls to a server without a graphical user
interface. BMC Atrium CMDB batch processing is an example of batch benchmarking. Batch
benchmarking can reveal the throughput of processing thousands, and even millions, of items
through your servers.
This topic includes the following information:
Batch processing
Page 226 of 4705
Home
Determining the data source and testing volume

Executing the test
Analysis and reporting
Batch processing
CMDB batch processing includes the following steps:
1. Onboarding or updating configuration items (CIs) Onboarding simulates the loading of
new CIs into a source dataset in the CMDB. BMC recommends that you use off-peak hours
for onboarding a large number of CIs. Smaller quantities of CIs (for example, 5,000 CIs and
relationships, or CiRs) can be onboarded with an online transaction processing (OLTP) load.
Updating CIs refers to some CIs being modified in the source dataset.
2. Normalizing CIs The normalization process ensures that product names and
categorization are consistent across different datasets and from different data providers.
3. Reconciling CIs The reconciliation process compares data from different data sources
and creates one complete and correct production dataset. The reconciliation consists of the
identification and merge activities. Identification recognizes class instances that are the
same entity in multiple datasets. Merge consolidates CI attributes from a source dataset to a
production dataset.
In batch processing, you can run normalization and reconciliation jobs in either batch or continuous
mode. Batch jobs process all outstanding CIs at once and stop when those are finished.
Continuous jobs keep running and poll at specific intervals for work to be done. Continuous jobs do
not end until they are manually stopped.
Onboarding is usually done with batch jobs because a large bulk of CIs needs to be processed. In a
production environment, batch or continuous jobs might be run, depending on how many CIs need
processing. If CIs are trickling in, a continuous job might be the better option. If you have a small
set to process (for example, fewer than 10,000 CIs), a batch job is sufficient.
Determining the data source and testing volume

CiRs for onboarding can come from a variety of sources, such as BMC Atrium Discovery and
Dependency Mapping and BMC Atrium Integrator. To ensure that data represents your company,
acquire data from one of these production sources. Make a copy of the data to facilitate retesting.
From these sources, determine the data model and CI attributes used. A typical data model
includes the ComputerSystem CI as the parent. The children are the parts found in a computer
system, such as the software represented by the Product CI.
A destination dataset can be empty or populated with CiRs. First-time onboarding usually means
that the CMDB is nearly empty. Determine what testing volume best describes your situation.
Page 227 of 4705
Home

After obtaining a volume source CMDB, set it up in its own test environment that contains a source
application, an AR System server, and BMC Atrium CMDB. Isolate the test environment from other
traffic to achieve repeatable tests.
Executing the test

To ensure performance can be measured for onboarding, normalization, and reconciliation, perform
each of those steps individually.
When creating a CMDB batch processing checklist, include the following items:
Restore the database to baseline data
Verify that no other activities are on the system
Set basic system and software configuration
Load CiRs into the source dataset
Verify that all CiRs have been loaded
Optional: Back up the database for repeating normalization and reconciliation tests
Start a normalization batch job
Measure normalization throughput
Optional: Back up the database for repeating reconciliation tests only
Start a reconciliation batch job that includes identification and merge
Measure reconciliation throughput
When you onboard CiRs (load new CiRs into a source dataset in the CMDB), the source dataset
should be empty. During onboarding, record the start and end times and number of CIs and
relationships processed.
The BMC.CORE:BMC_BaseElement and BMC.CORE:BMC_BaseRelationship forms can be
queried by the dataset name to determine how many CIs and relationships were loaded.
After a successful CiR load, back up the database. You can then rerun normalization and
reconciliation without having to load CiRs again.
Normalization requires that you create a normalization job that starts and stops normalizing on your
source dataset. In this case, run a batch normalization job so that it processes all un-normalized
CIs and stop the job when those are finished. Record the start and end times and the number of
CIs processed. Obtain this information from the BMC Atrium Console where the normalization job
was started. Roll your mouse over the normalization job to display the information.
After a successful normalization, back up the database again. You can then rerun reconciliation
without having to load CiRs and normalize again.
Reconciliation requires that you create a reconciliation job that identifies and merges all CiRs on
your source dataset to the destination dataset. This reconciliation job is usually BMC.ASSET. You
can either create separate reconciliation jobs to do identification and merge separately, or create
Page 228 of 4705
Home
one reconciliation job to do both. Separating the identification and merge enables you to observe
the behavior of each more thoroughly. Separating or combining reconciliation activities gives you
throughput information on each activity.
A batch reconciliation job starts and stops reconciling when CiRs are processed. Roll your mouse
over the reconciliation job to display the start and end times and the number of CiRs processed.
For each step, measure the system resources used, such as the CPU and memory on the AR
System server and the database. The BMC Atrium Console shows the normalization and
reconciliation job progress, information about start and end times, and the number of CiRs
processed.
Analysis and reporting

In CMDB batch processing, throughput can be calculated by CiRs per second (CiR/s). The
throughput formula is as follows:
Total number of CiRs/Total time to process (seconds) = Throughput
Calculate throughput for onboarding, normalizing, reconciliation identification, and reconciliation
merge.
Use the steps for online benchmarking reporting to present batch benchmarking results.
Benchmarking for mixed workloads

In a production environment, a combination of online and batch workloads occurs throughout the
workday. A benchmark that combines both helps determine the necessary server resources to
handle such a load. This is day-in-the-life benchmarking.
BMC recommends that you process large CMDB during off peak hours. However, some CMDB
processing can still occur during peak hours. To determine how much CMDB processing your
servers can handle without impairing performance, conduct a combination of online and batch
benchmarking.
In this combination of online and batch testing, use your usual online benchmark workload. Run
your batch testing as you would normally run a production batch workload, even if it during peak
hours. Start with a minimal number of CMDB batch processing, then increase it by as much as your
environment can handle without impairing performance. Ensure that you configure for normalization
and reconciliation private queues to handle the CMDB load separately from the online threads.
Using private queues and limiting the number of threads for each queue restricts how much CPU
each job uses and prevents the CMDB from consuming too much CPU and adversely impacting
end-user online transaction response times. When combined with an online load, a CMDB load
consists of updating CIs and loading new ones, which are generally run as continuous
normalization and reconciliation jobs.
When you have reached a peak, anything more requires a separate server to handle a strictly
CMDB load.
Page 229 of 4705
Home

The time required for performance benchmarking projects is often underestimated. If you plan to
benchmark before production rollout, allow generous time and leeway for this project. The following
table provides estimates for each general task.
Project schedule estimates
Task
Time required
Designing a meaning test
3 to 7 weeks
Executing the test and analyzing the results
2 to 4 weeks
Creating a final report
1 week
Checklists for benchmarking

This topic provides the following checklists for your benchmarking tests:
Designing tests
Setting up environments
Executing OLTP with batch tests
Executing CMDB batch processing tests
Analyzing results
Reporting results
Designing tests
Goal
Tasks
Getting started
Set goals
Test scenarios
Use one application per scenario
Script actual use cases exactly as executed by users
Write autonomous scripts for each scenario
Include wait times
Volume data
For production data:
Determine users who have assigned tickets
Back up the database
For synthetic data:
Page 230 of 4705
Home
Goal
Tasks
Verify that data is realistically distributed
Determine data model and proper attributes for CIs
Back up the database
Workload
Set the throughput for each scenario
Set a percentage of users per scenario
Determine caching needs
Use wait times to generate throughput
Successively ramp up your users
Run at least one hour of steady state
License your applications and users
Metrics
Measure roundtrip response times for critical actions
Measure throughput
Gather system resource statistics
Gather database statistics
Setting up environments
Support your benchmark test goals
Isolate the test environment from other activities
Select the appropriate software, hardware, and network
Executing OLTP with batch tests

Write a checklist to ensure that your test can be repeated
Restore the database to its baseline data
Restore all tiers to their initial state, remove old logs, and then restart the application
Ensure that no other activities are on the system
Set basic system and software configurations, and capture system and software
configurations before you run a test
Run a sanity check on all scripts
Start normalization and reconciliation continuous jobs for processing incoming CIs
Simultaneously start performance testing and monitoring system resources on all tiers
Start onboarding or updating of CIs, or both
Measure single-user timings with back-end load
Record the start and end times of steady-state period
Visually monitor the performance test for issues
When the test ends, stop system resource monitoring
Page 231 of 4705
Home
Validate load generator report results with transaction counts from the AR System server
Save each tier's logs and results
Executing CMDB batch processing tests

Load configuration items and relationships (CiRs) into source dataset
Verify that all CiRs have been loaded
Optional: Back up the database

Start normalization batch job
Measure normalization throughput
Optional: Back up the database
Start reconciliation batch job that includes identification and merge
Measure reconciliation throughput
Analyzing results
Check for errors in each tier's logs
Verify that CPU use for any system is less than or equal to 75%
Verify that Java memory use does not exceed allocation
Verify that other memory use is stable during steady-state period
Use database and system I/O statistics to identify I/O bottlenecks
Check for network bottlenecks
Check load generator system
Check test scenario input
Use percentiles to determine steady-state response times
Use histograms to determine response times
Reporting results
Keep it simple
Summarize initial database volume
Include environment setup diagram
Summarize product scenario flows and expected throughput
Summarize percentage of users per scenario
Summarize user ramp-up
Use graphs and charts to clarify results
Summarize actual throughput
Add appendix of environment specifications and software and hardware configurations

Estimate generous time for your benchmarking project
Page 232 of 4705
Home
Performance tuning for BSM

The Business Service Management (BSM) product suite can dramatically simplify an organizations
IT environment by providing process automation and service management solutions. Though BMC
benchmarking greatly improves the performance of BSM products before they are released,
understanding how best to tune your environment is critical.
The following topics contain information on performance tuning for BSM:
Overall system tuning
Developing a problem statement
System performance and capacity
Tuning the mid tier
Tuning the AR System server
Tuning a database server
Performance tuning checklists
BSM case study
This section addresses environments and configurations for typical BMC enterprise customers, with
emphasis on the following tasks:
Evaluating the performance of a configuration running BSM applications
Identifying potential bottlenecks that might cause performance issues
Collecting and interpreting diagnostic data to identify the root cause of a performance issue
Product and configuration focus

Any BSM environment should contain the following for an ITIL-compliant product set:
Configuration Management Database (CMDB)
Automated discovery sources
Service Impact Management and Service Level Management tools
Incident, Problem, and Change Management
The recommendations in this section are based on tests conducted with products running on the
BMC Remedy Action Request System server (such as BMC Atrium CMDB, BMC Remedy IT
Service Management Suite) and products such as BMC Service Impact Manager and BMC
Configuration Discovery. However, the majority of the techniques discussed are generic
recommendations that can be applied to any product set.
To reduce the scope of BSM performance tuning, these topics focus primarily on the Oracle and
Microsoft SQL Server databases and the Tomcat servlet engine.
Performance considerations
Sizing a database server for capacity is important because it might not be possible to scale
the database tier horizontally unless you are using Oracle RAC.
Page 233 of 4705
Home
Database performance is highly dependent on a fast I/O subsystem.

Since the AR System server only caches metadata, it is highly dependent on the fast,
reliable, low-latency connection to the database.
BMC recommends a gigabit connection with close to zero latency between the AR System
server and the database. Any additional hop, packet screener, or firewall has a negative
impact on performance.
For the AR System server tier, you can scale horizontally by configuring multiple AR System
servers configured as a server group.
For the web tier, you can scale horizontally by configuring multiple mid tiers connecting to
the same AR System server or server group, and by configuring a load balancer (or a
reverse proxy) in front of the mid tiers to do the routing.
BMC recommends having a dedicated environment for the BSM application. Performance is
difficult to manage when multiple applications are running in the same environment.
If there is a load balancer or firewall between the mid tier and the AR System server,
configure so that idle connections from the mid tier are not severed. Reestablishing severed
connections takes additional time.
Overall system tuning

This topic discusses the following overall tuning strategy:
Optimizing the network
Optimum client configuration
Overall tuning approach
Optimizing the network

Use a gigabit network with minimal latency between the AR System server and the database
server.
Do not to install a firewall between the AR System server and the database server. A firewall
has significant negative impact on performance.
If there is a load balancer or firewall between the mid tier and the AR System server,
configure it so that idle connections from the mid tier are not severed. Reestablishing
severed connections takes additional time.
Optimum client configuration

Dual Core 2+ GHz CPU with 2 MB L2 cache or single core 3+ GHz CPU with 2 MB L2 cache
2-4 GB RAM
Mozilla Firefox 3.6 or later, or Microsoft Internet Explorer 8 or later
Disable all browser add-on toolbars and plug-ins except Adobe Flash
Configure the browser to open pop-ups in a new tab
Configure the browser cache setting to Automatic
Page 234 of 4705
Home
Note
All applications, especially the browser, run slower while virus scan is running.
For additional information, see Browser hardware requirements and settings.
Overall tuning approach

1. Create a precise statement of your performance problem. See Developing a problem
statement.
2. Review overall system performance and capacity of the following components:
CPU and memory resources
Memory consumption
See System performance and capacity.
3. Review the following individual components:
Mid tier
AR System server
Database server
Note
Evaluate all components before making any changes.
4. Evaluate and resolve performance issues by doing the following steps:

a. Identify configuration discrepancies and performance bottlenecks.
b. Prioritize any proposed changes based on the problem statement.
c. Perform and evaluate the impact of the highest priority change.
Note
Resolving performance issues is an iterative process. Evaluate one change
at a time. Each time a substantial change is made, quantitatively evaluate
the effect of that change before making another change.
5. Repeat step 4 for each change in order of priority.
Developing a problem statement

Performance tuning initially requires a clear problem statement, including the following common
metrics:
Page 235 of 4705
Home
Throughput Frequency of an operation over time, such as the number of tickets created in
an hour, or the number of configuration items (CIs) processed in an hour.
Response time Seconds between a significant operation (for example, clicking Save to
create an incident ticket) and the time that the operation is completed and system control is
returned to the user. See Collecting response time data.
A problem statement should also include a list of recent changes that might have led to the current
state. In production-related issues, change control or other sources can often provide a log of
system changes that took place before a problem began. Such a change history might not point to
the root cause of a problem, but provides valuable background data.
Collecting response time data

Response time might be described subjectively with a statement, such as the system seems slow.
However, to effectively identify a problem, multiple users with different client configurations should
manually time the operations.
To measure response time, collect event times from multiple users who are experiencing the
problem. To form a complete picture, capture various data points that impact performance. Record
the following data:
Client configuration and browser information for each user Record the browser type and
version. For more information, see Optimum client configuration.
Client location Record the latency the user is experiencing at the application layer by
using http-ping and tcp ping latency.
Timestamp for each timing test Because caching might cause the first timing test to take
longer than subsequent tests, make a separate note of these times for each user.
The following example shows a spreadsheet for capturing response time data. To instruct the
testers exactly what to do and what to time, describe each test in detail. All testers should use a
equivalent timing device, such as a stopwatch or similar tool.
Example spreadsheet for capturing response time data
Page 236 of 4705
Home
For more information about collecting response time data, see Benchmarking for a single user.
System performance and capacity

This topic contains the following information:
Monitoring CPU consumption
Monitoring memory consumption
Initial triage of performance problems involves observing resource consumption across the
configurations. Resource profiles can point to the root cause of a problem, or they can help focus
the search for a cause.
For each tier of your system, analyze the consumption of the following resources:
Central processing units (CPUs) Include system time, user time, and I/O wait time. For
benchmarks simulating online users, get CPU usage data for the computers driving the load.
Memory

CPU usage substantially affects system response time, usually in a nonlinear way. The following
figure shows a typical response-time curve. Response time starts at a baseline and grows slowly
while CPU usage is low. As CPU usage increases, the response-time slope becomes steeper until
it is almost vertical.
Page 237 of 4705
Home
Response-time curve
Response time growth is incremental until a significant increase is reached. The point at which the
response time increase occurs is variable, but it typically occurs when CPU usage for at least one
computer in the system is at least 60%, and sometimes as high as 90%.
Running only one server at high load in a multi-server configuration can substantially affect
response time. Favorable response time does not always occur when some servers in the
configuration are largely idle.
If the sharp increase in response time in the configuration's response-time curve is similar to the
bottleneck in the figure but occurs while CPU usage on all systems is low, the consumption of a
non-CPU resource is creating the system bottleneck.
CPU usage has several components:
User time Time consumed by applications that are performing useful activity on the
system. Generally, user time should constitute the majority of CPU usage.
System time Time consumed by the OS kernel for core processing. If system time is
higher than 5%, an OS-level resource or locking problem exists, which is a typical memory
management issue.
I/O wait time Time consumed waiting for a request to the I/O subsystem to return. If I/O
wait time is substantial, the I/O subsystem cannot keep up with the CPU application
processing. In this case, the system is likely to have poor response time unless the I/O
subsystem bandwidth is improved or the applications data requirements are tuned.
Generally, I/O concerns are relevant only on the database system of a multi-tiered
configuration.
Typical tools used to track CPU usage are the perfmon command for Microsoft Windows and the
sar command for UNIX and Linux. In both cases, you should store the collected data for later
review.
Page 238 of 4705
Home
For UNIX systems, the top command can identify high-load processes, but its data is harder to
store for review. Using the ps command might be a useful alternative. The top command is also
helpful for monitoring relative CPU usage among running processes.

Tracking memory consumption can be challenging because of the following situations:
Some systems assign unused memory to swap space or to other system resources.
Memory allocation algorithms vary depending on OS.
Understanding approximately how much of a configurations physical memory is in use
during application execution is important.
A modern OS always provides a virtual memory space that far exceeds the systems physical
memory. If an application consumes nearly all the systems physical memory, processes in shared
memory are written to disk to free up space for new memory requirements. This practice is
informally called swapping. Although swapping can be useful, it degrades both CPU usage and
response time.
Note
Do not confuse process swapping with simple memory paging, which can be normal
behavior and does not necessarily consume extra resources.
The primary goal of evaluating memory consumption is to ensure that:

The OS is not swapping
A running application can still allocate memory when needed
Because swapping increases CPU usage, the first symptom of running out of memory might be that
CPU resources are fully used. Noticing how memory consumption grows over time is often useful.
A process that continues to consume memory quickly might have a memory leak, which is likely to
lead to swapping or failure.
When evaluating the performance impact of memory consumption with 32-bit BMC applications,
consider whether the OS is 32-bit or 64-bit. For example:
On 32-bit editions of Windows, applications have 4 GB of virtual address space available.
This space is divided into 2 GB for the application and 2 GB for the kernel. However, you
can use tuning features such as 4 GB tuning (4GT) and the
IMAGE_FILE_LARGE_ADDRESS_AWARE value of the LOADED_IMAGE structure to reallocate
3 GB for the application and 1 GB for the kernel.
Page 239 of 4705
Home
On 64-bit editions of Windows, you can use the IMAGE_FILE_LARGE_ADDRESS_AWARE

parameter to increase the 2 GB limit up to 4 GB for a 32-bit application. In addition,
technology such as Physical Address Extension (PAE) can enable 32-bit Windows systems
to use more than 4 GB of physical memory.
On UNIX and Linux systems, application memory management (including how shared memory is
configured) differs from vendor to vendor. To learn how to use your systems virtual memory and
shared memory management features to achieve the best performance for BMC applications, see
your product documentation or consult your system administrator.
Tuning the mid tier

This section provides instructions for optimizing the performance of the mid tier as a web
application from the server, browser, and network perspectives in the following sections:
Fine tuning the web infrastructure for the mid tier
Fine tuning the mid tier web application
Browser hardware requirements and settings
Mid tier case studies
The web component for the BMC Remedy AR System platform is the BMC Remedy Mid Tier (the
mid tier). The mid tiers main function is to transform any BMC Remedy AR System application into
a web application that is accessible to users through a web browser. Therefore, you can categorize
the mid tier as a web application because it delivers web contents to browser requests and is
deployable on any J2EE-compliant servlet engine. However, the mid tier is not a web application in
the strict sense because it does not contain resources to fulfill any browser use cases. All contents
delivered by the mid tier to fulfill web use cases (with the exception of platform level resources) are
dynamically derived from the BMC Remedy AR System applications that are deployed on the AR
System server to which the mid tier is configured.
The mid tier is a web application that conforms to the J2EE Servlet 2.3 specification. It can be
deployed on a wide range of web application servers or servlet engines as specified in the AR
System server compatibility matrix (http://www.bmc.com/support_home).
Note
The term web server is used inter-changeably for the application server or servlet engine
that is hosting the mid tier or any generic web application.
Apache Tomcat is the default servlet engine included with the BMC Remedy AR System installer.
One advantage of this is that a licensed third-party product such as ServletExec is not required in a
production environment, which keeps deployment costs to a minimum. Tomcat performs as well as
other application servers or servlet engines under most conditions. It also has a much smaller
memory footprint because it is not a full J2EE application server.
Page 240 of 4705
Home
You need to fine tune the web infrastructure separately because the Java Virtual Machine (JVM)
parameters, servlet engine thread configurations, network optimizations, and some HTTP protocol
parameters are not controlled at the web application level. These parameters are set at the web
infrastructure level. Moreover, this fine-tuning process is generic and re-usable for any general web
application deployment unless otherwise explicitly stated.
Additionally, this section discusses the client hardware that hosts the browser. The hardware must
meet certain requirements so that the UI rendering and JavaScript executions are timely since the
mid tier web application relies heavily on dynamic UI layout and JavaScript execution on the
browser side.
As with most web applications, most of the web contents delivered by the mid tier are serviced with
browser cache directives that are issued for faster use case execution time. If the security settings
in the browser are incorrectly set resulting in the disabling of the browsers caching mechanism, the
use case times as executed by the given browser are adversely affected.
Fine tuning the web infrastructure for the mid tier

This section provides the following information about optimizing the web infrastructure:
Fine tuning the network for HTTP protocol
Fine tuning the web stack
When a company purchases a web application, the application is generally delivered as a WAR file
or a self-contained expanded directory. The web administrator then deploys this application in a
web container. By using some guidelines from the selling company, the web administrator must
also configure the web container appropriately for the correct web-user load and performance.
Because user load varies, the provided guidelines are generic and are suitable for most
deployments. This is also true in the case with the mid-tier installer.
For the BMC Remedy AR System platform, the mid-tier installer is packaged with the open source
Apache Tomcat, so the topics focus on this servlet container. For other choices, apply the
recommendations accordingly.
The out-of-the-box installation of the mid tier and Tomcat with the default configurations works well
for most deployment cases. However, because each deployment has a different network
environment, hardware, and user load, you can optimize the out-of-the-box configurations for better
performance that is more appropriate to your situation.
The metrics of optimization are the use case times as observed by your browser users. These
guidelines are generic to the deployment of any AJAX-type web application and are not specific to
the BMC Remedy AR System platform, which means that you can apply the guidelines in the
deployment of other dynamic (AJAX-type) web applications.
Page 241 of 4705
Home
This topic explains how to optimize the network for HTTP protocol and transport, as well as how to
optimize the load balancing scheme for a balanced HTTP load distribution (for network
infrastructures with load balancers).
Optimizing the network for HTTP by setting the HTTP keep-alive option
Optimizing the load balancing scheme for the web tier
Off-loading SSL when using HTTPS (HTTP over SSL)
Optimizing the network for HTTP by setting the HTTP keep-alive option
HTTP keep-alive is officially supported in HTTP 1.1 and by all current browsers, such as Mozilla
Firefox and Microsoft Internet Explorer versions 6 or later. HTTP keep-alive is necessary because
the original HTTP 1.0 protocol requires only the browser to open a TCP socket, send the HTTP
request, receive the response, and then close the socket. The HTTP 1.0 protocol works well but
can tax the browsers performance when accessing a dynamic web application, especially an
Asynchronous Java-XML (AJAX) web application such as the mid tier.
An AJAX web application relies on many smaller HTTP requests to fulfill a use case. When so
many HTTP requests occur, browser performance is impaired without HTTP keep-alive because
the browser is constantly opening and closing sockets. This occurs especially when SSL (HTTPS
protocol) is used for transport security, or when a single URL has links and references to many
other resources (such as images, CSS, and JavaScript) embedded in the HTML content of the
target URL.
By using HTTP keep-alive, the browser maintains the opened TCP sockets, keeping them alive (
active) and re-using them for subsequent browser requests. This greatly enhances the browsers
performance because the constant opening and closing of sockets is no longer needed.
For web applications that use pipelining, you must activate HTTP keep-alive for pipelining to work.
However, the mid tier web application does not use pipelining, so enabling HTTP keep-alive is
optional, but will improve the browser performance when accessing the mid tier.
Note
HTTP keep-alive is distinct from TCP keep-alive. HTTP keep-alive is at a higher network
layer than the TCP layer.
For the purpose of this HTTP keep-alive configuration example, a simple network configuration with
one network segment is used (that is, the browser is connecting directly to the web or application
server with the browser acting as a client and the web server acting as the server or service
provider). In the case of a more complex network with multiple network segments, HTTP keep-alive
must be enabled on every network segment for optimal web performance.
For the example, the mid tier installer installs the Tomcat web server.
Page 242 of 4705
Home
Specific to Tomcat, the following parameters control the HTTP keep-alive:

connectionTimeout Specifies how long the web server will keep the TCP socket alive
when it is idle. (In terms of real world usage, the interval is targeted approximately to the
browser-user think time.)
maxKeepAliveRequests Specifies how many HTTP requests the browser can submit
through one opened socket before the web server closes the socket. (This relates to a
security precaution because limiting the number of HTTP requests on an opened TCP
socket can help with denial of service attacks by capping the number of HTTP requests per
socket.)
A third Tomcat parameter called keepAliveTimeout is specifically used to manage HTTP
keep-alive. However, by default, Tomcat sets the value for this parameter to the value of
connectionTimeout if keepAliveTimeout is not set. Since the HTTP keep-alive time needs to
be identical to the TCP idle time as given by the connectionTimeout parameter, managing both
by using a single parameter is less error prone. For simplicity, use only the connectionTimeout
parameter.
For more information, see http://tomcat.apache.org/tomcat-7.0-doc/config/http.html .
When the two parameters are set, keep-alive is turned on in Tomcat. These two parameters might
be optional for other web servers or load balancers and might have different labels. The parameters
are transmitted to the browser through the HTTP response headers. If necessary, the browser
knows whether to establish a new TCP socket connection when it sends out the next HTTP request
.
The following figure shows the HTTP response header for a browser connecting to Tomcat with the
connectionTimeout set at 120 seconds and maxKeepAliveRequests set at 5000. (This
response header was captured using Fiddler, a free tool from Microsoft and available at http://
www.fiddler2.com.) For subsequent requests over the same TCP socket, the HTTP response
header shows a decreasing value for the maxKeepAliveRequests count.
HTTP response header
Page 243 of 4705
Home
The following table lists the recommended HTTP keep-alive values of the Tomcat web server that
hosts the mid tier. It also shows the minimum recommendation if the hardware hosting the Tomcat
has resource constraints.
Tomcat web server HTTP keep-alive recommendations
Tomcat HTTP keep-alive parameter
Recommended value
connectionTimeout
90000 ms (minimum 60000 ms)
maxKeepAliveRequests
infinite (minimum 5000)
To set these parameters, locate the Connector entry in the <tomcat dir>/conf/server.xml file.
The following example shows the configuration with the connection timeout at 90 seconds and the
keep-alive count at infinite:
<Connector URIEncoding="UTF-8" acceptCount="100"
blank connectionTimeout="90000"
blank maxHttpHeaderSize="8192" maxKeepAliveRequests="-1"
blank maxThreads="500" port="80" protocol="HTTP/1.1"
blank redirectPort="8443"/>
The following example shows the configuration with the connection timeout at 60 seconds and the
keep-alive count at 5000:
<Connector URIEncoding="UTF-8" acceptCount="100"
blank connectionTimeout="60000"
blank maxHttpHeaderSize="8192" maxKeepAliveRequests="5000"
blank maxThreads="500" port="80" protocol="HTTP/1.1"
blank redirectPort="8443"/>
Page 244 of 4705
Home
By turning on HTTP keep-alive, you can expect a transport time gain of approximately 10-30%
depending on network latency the larger the latency, the larger the gain. For SSL deployment,
the gain is more dramatic typically over 30%.
Note
The Tomcat HTTP keep-alive configuration as explained here is for the simplest case
where the browser is connected directly to Tomcat. For this case, there is one network
segment with the browser being the client and the Tomcat being the server. In a complex
network infrastructure with multiple network segments, the recommendation is to
configure every network segment for HTTP keep-alive.
To verify that the keep-alive setting is working in the browser, use a web debugging proxy, such as
Fiddler, to capture the exchanges between the browser and the server.
The following figures compare the exchanges when keep-alive is off and when it is on for HTTPS.
Observe the frequency of SSL socket establishment when keep-alive is off.
HTTP keep-alive set to off
HTTP keep-alive set to on
Page 245 of 4705
Home
Another method to verify that the HTTP keep-alive is on is to examine the HTTP response headers.
In the following figure, the Transport header of the response is tagged with Connection:
Keep-Alive. In this example, a BigIP load balancer was used, and it does not support the two
optional keep-alive parameters as Tomcat.
HTTP keep-alive is set in the response header
Page 246 of 4705
Home
Note
For HTTP 1.1 browser clients, the Transport header of the HTTP request is always
tagged with Connection: Keep-Alive to indicate to the server that it supports HTTP
keep-alive. To complete the protocol exchange process, the server must do the following:
Keep the TCP socket established by the browser alive and active for the browser to
reuse
Set the Transport header of the response to Connection: Keep-Alive to indicate to
the browser that the socket is being kept alive so that the browser can reuse the
socket. However, though many products set this response header, it is optional as
specified by the W3C organization. As long as the HTTP response header does not
explicitly specify Connection: Close, all HTTP1.1 browsers will re-use the TCP
socket.
For more information, see http://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html and http://

www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.10 .
Optimizing the load balancing scheme for the web tier
If you have multiple mid tier instances deployed in your environment (each is supported by a single
instance of Tomcat), a load balancer is necessary to load balance the browser load across the mid
tier instances. Unless you have set up your mid tier instances as a web cluster (with a mechanism
for sharing HTTP sessions across every web application instance of your cluster), HTTP session
affinity is required of the load balancing scheme.
Two common methods to ensure HTTP session affinity load balancing are source IP binding and
cookie insert. BMC recommends the cookie-insert method for the following reasons:
The browsers use HTTP protocol, so using cookies for load balancing is most appropriate for
the HTTP layer.
If the browser clients are Network Address Translated (NAT) or are behind an outbound web
proxy, the cookie-insert method still ensures a balanced load distribution. In contrast, in this
case, source IP binding does not provide an even load distribution in the NAT because there
is only the single IP address of the proxy.
Off-loading SSL when using HTTPS (HTTP over SSL)
Most web deployments are done through HTTPS (HTTP over SSL) for security reasons.
Tomcat is not as efficient at handling SSL as a hardware load balancer or the Apache Web Server.
If you require SSL in your deployment, offload the SSL handling to the load balancer. If you do not
have a hardware load balancer, configure the Tomcat instance with the Apache Web Server to
handle SSL. Offloading the SSL handling to a single entity also centralizes certificate management
to this single entity, making certificate installation and management much easier.
Page 247 of 4705
Home
If you have Tomcat handle the SSL layer, adjust the JVM heap allocation accordingly because the
SSL handling will increase JVM CPU and JVM heap usage of the JVM hosting the Tomcat instance
. See JVM runtime analysis.
When deploying a web application over SSL:
Secure only the necessary network segments because encryption and decryption is
resource intensive.
Activate HTTP keep-alive because SSL sockets are expensive for a browser to establish, so
reuse them when possible.

This topic discusses how to fine tune the web stack to optimize the handling of HTTP requests in
terms of the rate of service and throughput. The task is to configure the web stack to behave
predictably under load and to leverage the available hardware resources to service HTTP requests
as quickly as possible.
This section includes the following information:
JVM monitoring and analysis
Tomcat container workload configuration
For this discussion, when deploying a web application, consider the following abstraction of the web
stack:
Web Application
Servlet Engine/Container
JVM
Operating System
Hardware/VM
With these layers in mind, the goals are to do the following:

Configure stack behavior so that it is predictable (in terms of JVM CPU and heap resource
usage) under load.
Predictable behavior implies that you can adjust the stack for the expected user load so that
you can introduce vertical/horizontal scaling as necessary. Then, you can then leverage the
available system resource allocations to maximize hardware usage for servicing HTTP
requests.
Page 248 of 4705
Home
Leverage available hardware resources to maximize the performance of the dedicated web
stack.
To minimize the number of configurable parameters and for simplicity, the example here
uses a single dedicated web stack. The hardware or virtual machine (VM) is assumed to
host only the single instance of the web application with no other service or web application
running on the same computer.
Note
Even in a real deployment environment, having another service increases
unpredictability and obscures the root cause of failure. Having another web
application running in the same servlet engine also affects the behavior of the JVM
hosting the servlet engine.
When allocating memory to a process on any hardware or VM hosting a web application,

allocate so that the OS layer will not swap. Swapping introduces unpredictable service
behavior in terms of time required for servicing an HTTP request. Your OS platform has tools
, such as perfmon and sar, to monitor the swap behavior.
JVM monitoring and analysis
This section includes the following information:

JVM monitoring
JVM runtime analysis
The fine tuning of JVM runtime behavior includes: PermSize allocation, garbage collector selection,
heap size allocation, and miscellaneous load planning. This fine tuning is necessary in any web
application deployment because non-optimal JVM configurations may result in the following:
The Garbage Collection (GC) cycle occurring frequently, thus consuming CPU cycles that
would otherwise be available to service application users
Memory allocation not being used completely, thus depriving other processes on the same
computer of available memory
Memory being over allocated, thus causing the OS to swap which adds delays to service
time of HTTP requests
Memory being insufficiently allocated, thus causing excessive GC and JVM instability
This fine-tuning process is necessarily iterative: monitor, adjust, re-monitor, compare, and validate
improvements. This is a standard process for runtime behavior adjustment. There is no shortcut to
this iterative process, and no fixed recommendation can achieve a similar optimal result given the
various hardware and changing nature of user load.
JVM monitoring
Page 249 of 4705
Home
To enable JVM monitoring, start the JVM with the JMX protocol enabled. Then, from a local or
remote computer, you can launch <jdk>/bin/jvisualvm.exe and attach to the target JVM
process to start the monitoring. (A remote computer is preferable so that monitoring does not affect
the monitored target JVM.)
Note
When collecting JVM monitoring data for analysis, collect at least 24 hours of usage data.
This captures peak and off-peak data for a more accurate picture of the JVM behavior.
The following procedure explains how to remotely monitor the JVM process on the computer
twiddler through port 8088 with no authentication, which is the easiest setup. You can add the
authentication later when you have the monitoring process mastered. In the case of remote
monitoring, be sure your port is free and accessible from the remote computer. You can also use a
single instance of jvisualvm to monitor multiple target JVMs. Additionally, you can monitor a
single JVM process from multiple remote locations by using multiple jvisualvm instances.
To remotely monitor the JVM process
1. Start the JVM with the following additional arguments:
-Dcom.sun.management.jmxremote
-Dcom.sun.management.jmxremote.port=8088
-Dcom.sun.management.jmxremote.ssl=false
-Dcom.sun.management.jmxremote.authenticate=false
2. Launch <jdk>/bin/jvisualvm.exe.
3. Select File > Add Remote Host. (Skip this step and the next step if jvisualvm was launched
on the same computer as the JVM.)
4. In the Host Name field, enter the host name or the IP address.
5. For remote monitoring, right-click the host name in the navigation tree, and select Add JMX
Connection.
6. For local monitoring, select File > Add JMX Connection.

7. In the Connection field, enter the host name and port number.
Page 250 of 4705
Home
7.
For remote monitoring, enter your JMX port number (8088).
For local monitoring, enter localhost:8088.
The JMX connection appears in the navigation tree.

8. Double-click the connection to start monitoring.
9. To change the interval from the default to 24 hours, select Tools > Options, and enter *
1,440 in the two Charts Cache fields.
10. After sufficient data is collected, right-click the host name in the navigation tree, and select
Application Snapshot.
Page 251 of 4705
Home
The snapshot appears with timestamp in the navigation tree under Snapshots.
11. Right-click the snapshot, and select Save As to save the JVM monitoring data.
Warning
Do not use the Microsoft Remote Desktop Protocol (RDP) desktop to copy and
paste the snapshots to another computer. Use FTP or the network file system (NFS
). RDP copy and paste causes file corruption so that jvisualvm can no longer
read the file for analysis.
JVM runtime analysis
At the Java Virtual Machine (JVM) layer, the following parameters and JVM utilization factors can
drastically affect the performance of a web application:
JVM PermSize setting
JVM Garbage Collector selections
JVM heap size setting
JVM CPU utilization
Page 252 of 4705
Home
JVM heap utilization

JVM PermSize setting
The PermSize section of the JVM heap is reserved for the permanent generations and holds all of
the reflective data for the JVM (such as class, methods definitions, and associated data) and
constants (such as intern strings). This allocation is completely separate and independent from the
JVM heap size setting.
To optimize the performance of applications that dynamically load and unload many classes such
as the mid tier, increase the size from the default maximum allocation of 83MB. (This default
applies to Suns JVM 64-bit running on Windows in server mode and is 30% larger than the default
of 64MB of the 32-bit JVM. Other modes, operating system, and some JVM vendors might default
to a different value.)
For more information, see http://www.oracle.com/technetwork/java/javase/tech/vmoptions-jsp140102.html.
The following JVM arguments are related to the PermSize setting:
-XX:PermSize The initial PermSize. If this value is less than the maximum default value,
then the JVM allocation starts with this size and grows to the maximum default size as
needed. If this value is larger than the maximum default size and no -XX:MaxPermSize is
set, then both are set to the same given value.
-XX:MaxPermSize The maximum PermSize.
BMC recommends setting the PermSize for a 64-bit JVM hosting the Tomcat hosting the mid tier at
256MB, which is the default value that the mid-tier installer sets. This size is sufficiently large for a
mid tier connecting to an AR System server with the complete BMC Remedy ITSM Suite deployed
plus additional custom Data Visualization Modules, if any. However, if you have many custom Data
Visualization Modules deployed or if your mid tier is connected to multiple AR System servers, you
might need to adjust your PermSize value based on your JVM monitored data.
The following graph shows the JVM PermSize usage of a production mid tier connecting to an AR
System server with the full BMC Remedy ITSM 7.6.04 suite deployed while under a user load of
300 concurrent users over 24 hours. At the default 256 MB for the PermSize, there is sufficient
space to accommodate additional custom Data Visualization Modules and additional BMC Remedy
AR System application deployment. Also, though the graph shows an increasing usage pattern for
the permanent generations, garbage collection (GC) is on by default. If loaded class definitions with
no associated objects are on the JVM heap, those definitions will be collected and the PermSize
usage will drop as shown in parts of the graph.
PermSize Usage under full 300 user load
Page 253 of 4705
Home
The following example sets the PermSize to the recommended 256MB.

-XX:PermSize=256m
This allocates the PermSize to a fixed 256MB at JVM startup because 256MB is larger than the
default maximum.
JVM Garbage Collector selections
This section provides a brief overview of JVM Garbage Collector (GC). For a primer on how Java
GC works, see http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523.html . For a
summary of all the aspects of java GC, see http://www.petefreitag.com/articles/gctuning/ .
The JVM heap, not including the permanent generations, is partitioned into the following regions:
Young generations, which contain short-lived objects
Old generations, which contain long-lived objects each with its own independent GC.
Garbage collection of young generations occurs frequently whenever the eden space is full and is
called a minor GC cycle. When a minor GC cycle cannot reclaim sufficient heap space as
configured by various GC parameters, a major GC cycle starts. This involves the GC of the old
generations (as well as moving objects from the young generations into the old generations).
Whenever a major GC cycle occurs, application threads stop during that interval. This reduces the
applications performance and throughput, and it introduces additional delay to the web application
s service time.
Aim to configure the JVM with GCs that are most suitable to the hardware and web application
usage to minimize the delay of servicing HTTP requests.
With exception of the incremental GC (-Xincgc) and older GC not suitable for web applications, the
following table summarizes the different GCs for the old, young, and permanent generations in
terms of low-pause, throughput, and number of CPUs.
Garbage collection summary for various generations
Page 254 of 4705
Home
For permanent generations, the GC is on by default and is not configurable, but you can disable it
through -Xnoclassgc. The advantage of disabling the permanent generations GC is that the GC
will not unload and garbage collect class definitions in the permanent generations space that have
no associated live objects. This implies that a future object instantiation of one of those classes is
much faster since its class definition is already in memory. However, if you disable this permanent
generation GC, monitor the PermSize because the PermSize grows faster than with the GC on.
The most generic recommendations regarding GC choice are to use:
Default GC for a single CPU.
Low-pause GC for multiple CPUs if the focus in on HTTP service time.
Throughput GC for multiple CPUs if the web application creates many objects such as a mid
tier set up for reporting.
This might not be the most optimal recommendation for your hardware and user load. GC tuning is
a highly specialized topic. Monitor and collect JVM data to analyze and see what works best for
your hardware and load.
In the BMC testing environment, when the CPU clock speed is over 2.5GHz, the throughput GCs
worked better than the low-pause GCs.
If you mix different GCs, not all versions of the JVM will take all combinations of old and young
generations GC collectors. See http://www.oracle.com/technetwork/java/javase/gc-tuning-6-140523
.html. If you have a different JVM vendor, refer to the vendors documentation.
If you selected an invalid combination, the JVM will not start, or it will start but will ignore the GC
selection that does not make sense.
The following example sets both young and old generation collectors to the low-pause GC. Add the
following arguments to your JVM arguments:
-XX:+UseParNewGC -XX:+UseConcMarkSweepGC
Page 255 of 4705
Home
This changes the young and the old generation collectors from the default to the low-pause GC. If
you have other GCs already set, remove those arguments.
The following figures show a low-pause GC versus a throughput GC for the same 2 CPUs
hardware with 4 GB RAM running Windows 2008. For a one-hour load test, the throughput GC had
one major GC cycle versus the three major GC cycles with the low-pause GC. The reason is that
for the throughput GC, the minor GC cycles reclaimed significantly more heap space than with the
low-pause GC, thus fewer major GC cycles are required. However, for these different GC choices,
the average response time over the entire load test was similar.
GC behavior for throughput GC
GC behavior for low-pause GC
For most cases, these generic recommendations are sufficient. However, if your web stack still
experiences pauses and you suspect that it is the GC, use the following article as a starting point:
http://java.sun.com/docs/hotspot/gc1.4.2/example.html .
JVM heap size setting
Note
Page 256 of 4705
Home
A key item in making the transition from 32-bit JVM to 64-bit JVM is understanding that
the 64-bit platform has associated performance overhead due to the addressing. For more
information, see http://www.oracle.com/technetwork/java/hotspotfaq-138619.html
#64bit_performance.
BMC internal performance stress tests recorded that the 32-bit JVM outperforms the 64-bit JVM by
approximately 45% in CPU utilization on the same box with the two JVM versions installed and with
the identical load that drives each box to at least 50% CPU utilization at the OS-level aggregated
metric monitoring. Also, using jvisualvm to monitor the JVM process, the 64-bit JVM heap usage
was about 25% higher than the 32-bit JVM.
Oracle provides a hybrid mode for the 64-bit JVM to reclaim some of the performance overhead
both in CPU and heap usage. This is known as the 64-bit JVM hybrid mode. This mode reclaims
roughly 50% of the performance loss as recorded by BMC lab tests. Use this mode if your memory
requirement is less than 32 GB because this is the maximum heap size possible in the hybrid mode
. To activate this hybrid mode, add the following argument to your JVM startup arguments:
-XX:+UseCompressedOops
For information about the hybrid mode, see https://wikis.oracle.com/display/HotSpotInternals/
CompressedOops.
Note
On AMD-based hardware in conjunction with some JVM versions combination, the hybrid
mode can occasionally cause a JVM crash. Oracle might have fixed this defect for your
JVM version. However, if you experience some instability with your version of the JVM
running in hybrid mode, see if disabling the hybrid mode eliminates the instability.
To confirm the same instability as observed in our lab, if your JVM crashed, locate and
open the hs_err_pid.log* file, verify that the JVM is running in hybrid mode
windows-amd64 compressed oops and that the GC thread is pointing to an invalid stack
GCTaskThread [stack: 0x0000000000000000,0x0000000000000000]. This is based on
BMC observation and experience with the JVM instability in the BMC lab. To explicitly
disable the hybrid mode, add the following JVM argument:
-XX:-UseCompressedOops
Regarding the heap size allocation for the JVM (hosting the Tomcat running the mid tier), there is
no one-size-fits-all setting. The size of the JVM heap depends on the following:
The mid-tier version Later versions use more memory to support additional features.
The web user load The rate of the HTTP requests that users generate.
Page 257 of 4705
Home
The number of concurrent users logged on to the mid tier The number of HTTP session
objects alive in the mid tier.
The use cases supported A use case that retrieves more data from the AR System server
(such as reporting) creates more heap usage on the mid tier.
Another key item in JVM heap allocation is to always allocate the JVM heap up front (deterministic
JVM heap allocation) so that none of the allocated memory is virtual (range JVM heap allocation).
This helps the system behavior to be predictable as virtual allocation may cause the OS to swap.
Though a range allocation for the JVM heap is more flexible, when a range is allocated (by having
the start value less than the maximum value), the JVM adheres to the following process:
1. Allocates the start value at startup time
2. Allocates the delta as virtual
3. Requests system allocation when necessary as the heap usage grows
This works reasonably well if the OS has sufficient resources. In practice, however, when the
systems resource is constrained, a call from the JVM to acquire more heap space may send the
system into swap, which is not recommended. For more information, see http://www.oracle.com/
technetwork/java/javase/gc-tuning-6-140523.html .
To allocate the entire JVM heap up front as recommended, set the start and maximum value to the
same number. The following example allocates 2GB to the JVM heap. Add the following arguments
to your JVM arguments:
-Xms -Xmx
Use the following rules when allocating JVM heap size. (With the exception of SSL, the rest of the
rules are specific to the mid-tier web application and are not usable for other web application
deployment.)
BMC Remedy Mid Tier 7.6.04SP2 requires a minimum of 1.5GB to support a workload of
300 concurrent web users in typical ITSM use cases. A minimum of 2 GB for a workload of
300 500 concurrent users for typical ITSM use cases with the following AR System server
property limit:
Max-Entries-Per-Query: 2000
Different use-case execution has different JVM heap usage. Typically, the more data a BMC
Remedy AR System API call returns, the more JVM heap the mid tier needs to handle the
data. For details on the workload, see the BSM case study.
If Tomcat is handling SSL, allocate more memory than without SSL because SSL handling
requires extra JVM heap allocation. The rule of thumb is 20% extra. (This depends on the
number of concurrent users and the rate of simultaneous HTTP requests generated.)
In general, to support more concurrent users per mid-tier instance, add 1 MB per user. This
is based on empirical approximation; the exact value depends on which use case is being
executed. See JVM CPU utilization and JVM heap utilization below.
Page 258 of 4705
Home
To allocate more memory to the ehcache in the mid tier, for each additional 500MB, increase
the value of arsystem.ehcache.referenceMaxElementsInMemory in <
midTierInstallationFolder>/WEB-INF/classes/config.properties by 1250. For example,

consider that the default maximum heap size is 1024 MB and the
arsystem.ehcache.referenceMaxElementsInMemory is set to a value of 1250. If you have
additional memory available and you can allocate additional 500 MB heap size (total 1524
MB), you can change the value of referenceMaxElementsInMemory to 2500 (1250+1250)
to get the benefit of the mid tier cache.
ehcache is the mid-tier caching mechanism when converting BMC Remedy AR System
forms into HTML/JavaScript. The more memory allocated, the more HTML/JavaScript and
associated objects can reside in memory for faster service of HTTP requests for UI and
client-side workflow contents.
Do not modify other ehcache properties unless you have the expertise to do so.
The larger the JVM heap, the more important the GC tuning is. (BMC recommends
fine-grained GC tuning for 4 GB heap or larger. A good starting point is http://java.sun.com/
docs/hotspot/gc1.4.2/example.html.)
Note
When allocating and accounting for system memory usage, add the PermSize to the JVM
heap size to get the total heap allocation to the JVM.
The following figure shows the heap usage during a 1-hour, 300-user load test executing typical
ITSM 7.6 use cases. The JVM was allocated 2GB for heap, 256 MB for PermSize, with the
low-pause GC. Two CPUs with 8 GB RAM were used. The graph shows that the JVM CPU is
underutilized and can handle a higher HTTP request rate while the heap usage pattern is typical.
Look for the following key points:
A low percentage of CPU is spent on GC (blue graph of the first chart).
The heap is fully utilized.
Full GC cycles (there are two) did not use excessive CPU. (There was no jump in the blue
graph of the first chart during major GC cycles.)
Heap usage during load testing
Page 259 of 4705
Home
Note
To install the Visual GC plug-in for jvisualvm to observe finer-grained details of heap
space usage, select Tools > Plugins, select Visual GC under the Available Plugins tab,
and then let the plug-in self-install.
The interpretation of the Visual GC graphs is beyond the scope of this topic.
JVM CPU utilization
For JVM CPU utilization (based on your JVM monitored data for the interval of interest), CPU
usage should not be above the 95% utilization for extended periods. In real deployment and under
normal load, the JVM CPU should be underutilized so that it has sufficient space for surges such as
users logging in at the start of a workday.
You can determine the maximum number of simultaneous HTTP requests during your monitored
interval to see if this matches your load planning. If this exceeds your anticipated load, adjust the
hardware scaling appropriately for your load. If your typical load has wide fluctuations, and you
have a more lenient service time model, adjust your HTTP request buffer queue larger. (See
Page 260 of 4705
Home
Tomcat container workload configuration to learn how to determine the maximum number of
simultaneous HTTP requests during the JVM monitored interval and how to adjust the HTTP
request buffer queue.
The following shows various graphs of JVM CPU utilization, including categorization of behavior.
Ideal nominal load: Light usage with headroom for load surges
Ideal normal load: Some usage with headroom for load surges
Normal load with heavy constant usage: Can handle some load surges
Page 261 of 4705
Home
Heavy load with heavy constant usage: Cannot handle load surges
Typically, your system should behave within the two extremes: Ideal Normal Load and Normal Load
with Constant Usage.
The last graph of Heavy Load with Heavy Constant Usage indicates that the system is at its
maximum handling capacity and will need vertical or horizontal scaling.
JVM heap utilization
Page 262 of 4705
Home
For JVM heap utilization (based on your JVM monitored data for the interval of interest) at nominal
load, your heap usage should be at about 25% of total allocated heap or less. During service, your
heap usage will increase. (This is normal because Java has garbage collection instead of
programmer-controlled memory allocation.) The normal pattern of increase is until about 90% of
heap size. Then, a major GC cycle starts, provided that you did not adjust the default GC heap
ratios. If you need the major GC to start before 90% is reached (to have more space for use cases
such as running very large reports), resize the heap ratios. For more information, see http://
java.sun.com/docs/hotspot/gc1.4.2/example.html.
Note
For the heap percentage at nominal load, first invoke GC explicitly from the jvisualvm
console. Otherwise, the graph would show heap usage ratio with objects that GC still
needs to collect.
The following table shows the graph of JVM heap usage under load with different GC over a 20minute monitoring interval.
Normal heap usage under load with low-pause GC
Normal heap usage under load with throughput GC
Page 263 of 4705
Home
Tomcat container workload configuration
The default installation of Tomcat sets the number of HTTP request processing threads at 200.
Effectively, this means that the system can handle a maximum of 200 simultaneous HTTP requests
. When the number of simultaneous HTTP requests exceeds this count, the unhandled requests
are placed in a queue, and the requests in this queue are serviced as processing threads become
available. This default queue length is 100. At these default settings, a large web load that can
generate over 300 simultaneous requests will surpass the thread availability, resulting in service
unavailable (HTTP 503).
You should configure Tomcat to handle your planned workload. The maximum number of
processing threads depends on your hardware capability. One method to determine when you have
reached the maximum capacity of the hardware is to monitor the JVM runtime behavior to see the
JVM CPU utilization.
With the 64-bit JVM, the JVM memory allocation is no longer limited to a small value (1470MB on
Windows platform), so the potential for vertical scaling is vast.
The following configuration values are used for request processing threads in Tomcat for a given
connector:
maxThreads The maximum number of request processing threads that a given
connector creates.
acceptCount The maximum queue length for incoming connection requests to the given
connector when all possible request processing threads are in use.
You can configure multiple connectors per Tomcat instance, each running a different protocol such
as AJP, HTTP, or HTTPS.
Page 264 of 4705
Home
Under ideal conditions, these configuration values should not need user configuration. The ideal
software should service as many simultaneous incoming requests as possible and queue up as
many requests as necessary until the limit of service is reached. This is simple to state yet
impossible to implement because a systems runtime behavior depends on many external variables
.
maxThreads
acceptCount
Other connector properties
Tomcat thread configuration example
maxThreads
View the maxThreads value as a cap on runaway conditions. For example, if the AR System
server is unresponsive, and as requests arrive, each processing thread is in use and is in an
unavailable state until eventually all allocated threads are in use and are unavailable. If no cap is in
place, eventually the Tomcat process (or the JVM process hosting the Tomcat) would crash from
creating too many processing threads.
Based on BMC load tests, a balanced value for the maxThreads parameter is twice the number of
maximum concurrent users for your planned workload. Current browsers allow multiple TCP socket
connections to a given domain server name. If the user interactions with the mid tier are fairly
consistent, at twice the maximum concurrent users, this value provides enough spare threads to
reasonably handle unexpected surges. However, you can increase this value if your use cases
require long-running BMC Remedy AR System API calls (which ties up the service threads for
longer) or if you have heads-down type users such as at a call center (which generates a higher
number of simultaneous HTTP requests).
In practice, for BMC Remedy AR System platform deployment, the number of actual processing
threads rarely reaches the maxThreads value. When it does, it is because of other issues (such as
an unresponsive AR Server or poor load planning). To view the maximum number of service
threads created over a monitored interval using the JVM monitor data. In jvisualvm, click the
Threads tab and the Table tab, then sort by Thread.
Note
For a deployment with a larger number of concurrent users, the guideline of setting to
maxThreads twice as many users might be too much; this rule is non-linear. For example
, if you planned for 30 concurrent users, the probability that all 30 users are accessing the
mid tier simultaneously is high. However, if you planned for 3,000 concurrent users, the
probability of all 3,000 users accessing the mid tier simultaneously is almost zero. For
higher concurrent users load, you may taper off your allocation of HTTP service threads.
Page 265 of 4705
Home
The following figure shows that over the monitored interval, for the running load, the JVM created
213 HTTP service threads for the SSL (or HTTPS) connector on port 443. If the maximum number
of service threads was reached and users experienced no error conditions, revisit your load
planning because this is a symptom of a web instance reaching its maximum service capacity. If
the users experienced errors during the monitored interval, look in the Tomcat logs for the
conditions that caused the processing threads creation to reach its maximum limit.
Number of processing threads created
acceptCount
View the acceptCount value as the buffer size for smoothing out surges in incoming HTTP
requests. Any spillover requests (ones without available service threads) from the maximum
simultaneously serviceable requests are placed in this queue. Any request in this queue requires
longer service time because the user-experience service time for the request is the sum of the
actual service time spent by the processing thread plus the time the request spent in the queue.
For service-time critical deployments, set this queue to a smaller value (such as 100). For a highly
fluctuating web load, set this queue to a higher value (such as 250).
Other connector properties
Other Tomcat connector thread properties affect the performance of the web application to a lesser
degree. These properties include acceptorThreadCount and acceptorThreadPriority. For
more information, see http://tomcat.apache.org/tomcat-7.0-doc/config/http.html .
The mid tier uses UTF-8 encoding for requests and responses, so include this encoding in the
connector property. If you have multiple languages deployment, include UTF-8 encoding.
Tomcat thread configuration example
In the following example, the web stack instance is designed to support a maximum of 300
concurrent with the HTTP request buffer queue set at 100 and the UTF-8 encoding set. The
maxThreads parameter is set twice the number of maximum concurrent users.
Page 266 of 4705
Home
<Connector URIEncoding="UTF-8" acceptCount="100" connectionTimeout="60000

"
blankmaxHttpHeaderSize="8192" maxKeepAliveRequests="5000" maxThreads="600
"
blankport="80" protocol="HTTP/1.1" redirectPort="8443"/>

This section discusses fine tuning the mid tier web application, including adjusting the properties
that are controllable at the mid tier web application layer to achieve a performance optimization that
is specific to your deployment environment. The following scenarios are discussed:
Configure the mid tier so that the resources necessary to service any request are already in
memory
Configure the mid tier so that if a resource is not in memory, it can be located and loaded
quickly
Configure the mid tier to issue longer cache directives to the browser to cache and re-use
resources that are changed infrequently
Configure the mid tier to load-balance effectively across an AR System server group (if you
have a server group environment)
The mid tier transforms BMC Remedy AR System applications into web applications by compiling
each AR Form definition into an HTML/JavaScript pair. This compiling process is analogous to a
servlet engine compiling a Java Server Page (JSP). The process is more CPU-intensive for the
Java Virtual Machine (JVM) that is hosting the mid-tier web application stack than compiling a JSP
because the BMC Remedy AR System development paradigm is quite different from the web
development paradigm.
This compiling process of BMC Remedy AR System definitions into DHTML (HTML/JavaScript) in
the mid tier is referred to as prebuilding, precaching, or preloading of AR System forms. After a
form is built, it is also loaded and cached in memory inside the mid-tier web application unless a
resource limitation is preventing this from happening.
Note
The prebuilding of a form requires the prebuilding of all its subparts, such as active links
and fields. This process is distinct from browser caching.
Compiling of form definitions into DHTML is CPU intensive. So, when a browser user accesses a
BMC Remedy AR System form that the mid tier has not yet prebuilt into DHTML, it takes longer to
open the form because the mid tier must compile the definition before it can service the browser
request. This service time can be as long as 1 minute, depending on the complexity of the form
definition. However, if the form is already prebuilt and cached in memory, the response time is
generally less than 10 milliseconds.
Page 267 of 4705
Home
To achieve optimal browser time, the mid tier relies heavily on prebuilding forms and caching the
resulting transformations in memory. Because memory availability is finite, the mid tier also has a
serialization process for writing the objects that are not currently needed to disk. This frees up
memory. See JVM heap size setting to learn about leveraging more memory for the mid-tier cache.
With BMC Remedy Mid Tier 7.6.04.02 and later versions, the connection pooling no longer requires
TCP binding (TCP stickiness) when connecting the mid tier to an AR System server group. You can
set properties to control the life and redistribution of the connections in the connection pool (to
members of the AR Server group). See Configuring the mid tier connection pool .
Every browser has a caching mechanism to cache or write URL resources. Changes to the caching
mechanism are kept to a minimum so that subsequent requests for the same URL resources can
be loaded from disk rather than from HTTP requests. This mechanism caches resources as
dictated by the browser cache directives issued by the web application which provided the URL
content.
Configuring the mid tier preload and prefetch

The following performance related services in the mid tier assist in the prebuilding process:
Using the preload service
Using the prefetch service
About the statistics service
Using the miscellaneous service
You can manually configure the first two services. The statistics service runs automatically and
requires no administration.
The following sections about these services assume that the Enable Cache Persistence option is
set to on. For more information about cache persistence, see Configuring mid tier cache
serialization.
When the mid tier loads a necessary object into memory with Enable Cache Persistence set to on
, the mid tier tries to load the object from disk first. If the object is not available from disk, the mid
tier loads the object from the AR System server and constructs the object in memory. The object is
then serialized to disk. On subsequent usage of the same object, if it is not already in memory, the
object is retrieved from disk unless the objects definition has changed according to the Definition
Change Check Interval parameter. For more information, see Using the miscellaneous service.
Using the preload service
If the preload service is turned on for an AR System server as configured in the mid tier, the
preload service preloads all of the active links and menus when the mid tier starts. It then preloads
all of the AR System forms that contain active links up to the limit as defined by the ehcache. The
forms with active links are preloaded because any form with active links must be a user-facing form
for some use case. The users access these links at some point, so they should be preloaded.
Page 268 of 4705
Home
When a browser user requests a form from the mid tier, the mid tier performs the final process of
compiling the form into DHTML because this is when the mid tier can determine a view, locale, and
permission group. This final process happens quickly because all related form objects exist in
memory.
The following figure shows Preload activated on the Edit AR Server page of the Mid Tier
Configuration Tool. For more information, see BMC Remedy Mid Tier recommendations.
AR Server Settings page of the Mid Tier Configuration Tool
Using the prefetch service
The prefetch service has been available since BMC Remedy Action Request System 7.0 and is
kept for backward compatibility. The preload service replaces prefetch. You can use prefetch
instead of the preload service, but do not use both because preload already loads a superset of the
data as specified in the prefetch file.
If the midTierInstallationDirectory/WEB-INF/classes/prefetchConfig.xml file is not empty, all of the
user-facing forms as specified in the prefetchConfig.xml file are preloaded into memory. (The
prefetch service uses the same code module as the preload service for the loading of BMC
Remedy AR System definitions.) All of these forms are serialized to disk when the Enabled Cache
Persistence option is On. The forms listed in the prefetchConfig.xml file are a subset of the forms
that the preload service preloads up to the limit as defined by the ehcache property.
Note
Use prefetch only when you know the specific set of user-facing forms for your use cases.
Otherwise, use the preload service because it is easier to use.
Page 269 of 4705
Home
Optionally, you can access the prefetchConfig.xml file through the Cache Settings page of the
Mid Tier Configuration Tool.
Cache Settings page of the Mid Tier Configuration Tool
About the statistics service
When a browser user accesses a form, the statistics service collects the information necessary to
build a view for the target form. The statistics service builds a quintuple list (AR System server
name, form name, view name, locale, user group combination), sorted by the frequency of access,
with the most frequently accessed form listed first.
When the mid tier is restarted (a Tomcat restart) and after the preload or prefetch service has
finished, the statistics service loads this list and the corresponding DHTML into memory. They are
loaded in the order given by the list using a thread with a lower-than-normal priority, allowing the
mid tier to service browser users in parallel.
After the statistics service finishes loading, the forms and corresponding DHTML are loaded into
memory. This allows the mid tier to respond quickly to browser requests as dictated by the statistics
of actual usage.
The collected statistics are serialized to the
midTierInstallationDirectory/WEB-INF/classes/viewStat.dat file. This data is continually validated

as the statistics are collected. Data that is no longer applicable is removed (such as data for an AR
System server that was removed from the mid-tier configuration). You can also view the collected
data through the hidden JSP config_cache_adv.jsp file by using the Mid Tier Configuration Tool. (
After you have logged into the Configuration Tool, you need to enter the JSP name into the URL
bar of your browser because this JSP is hidden.)
Using the miscellaneous service
Page 270 of 4705
Home
The mid tier also provides a cache synchronization service to synchronize the memory and disk
cache with the definitions stored in the AR System server. The frequency of synchronization is
configurable through the Cache Settings page of the Mid Tier Configuration Tool.
For a production system where the definitions are unchanged or if there is a specific period for
rolling out changes, turn off the cache synchronization service. (Deselect the Perform check check
box on the Cache Settings page of the Mid Tier Configuration Tool as shown in the following figure.
) Instead, use Sync Cache after the changes are in place.
To run preload on a production system
1. In the Mid Tier Configuration Tool, click Cache Settings.

2. Select the Perform check check box to turn off the Sync Cache service.
3. Select the Enable Cache Persistence check box.
4. Turn on preload as follows:
a. Click AR Server Settings.
b. Select the server to edit, and click Edit.
c. Select the Pre-Load check box next to the server name.
d. Click Save AR Server.
5. Allow preload to finish preloading all the user-facing AR System forms.
6. Turn off preload.
Using this procedure allows the statistics service to load only the objects that correspond to the
actual usage of the system into the mid-tier memory. After the preload service has run once, all of
the relevant objects are written to disk (because Cache Persistence is enabled). By turning off the
preload service, the statistics service has full memory access to load only those objects that are
collected in actual usage. You can repeat this procedure if the applications on the AR System
server have changed, or if you have flushed the mid tier cache.
Configuring mid tier cache serialization

Additionally, you can select the Enable Cache Persistence option in the Mid Tier Configuration
Tool to serialize all objects that are prebuilt in mid tiers memory to disk. When this option is on, any
BMC Remedy AR System object that the mid tier builds is also serialized to disk. When the mid tier
Page 271 of 4705
Home
is restarted (by restarting Tomcat or the application server that hosts the mid-tier web application),
any object that the mid tier needs (such as forms, active links, fields, or groups) is loaded from the
disk first, if available. When this option is on, any object not available in memory is located and
loaded from the disk first, if available.
Note
Turn on cache persistence for a production environment. Turn it off in development
environments so that newer definitions are retrieved from the AR System server.
The following figure shows Enable Cache Persistence activated on the Cache Settings page of
the Mid Tier Configuration Tool.
Configuring mid tier issued browser cache directives

A standard web technique to improve the performance of a browser is to tell the browser to cache
contents that are infrequently changed so that the browser uses the cached contents on
subsequent requests instead of requesting the contents from the web application. This is called
browser cache directives, and it is optionally issued by a web application with each response. To
configure the browser to observe the cache directives, see Browser hardware requirements and
settings.
The mid-tier web application issues cache directives for all of the BMC Remedy AR System web
platform resources and almost all of the UI components. (For security reasons, the data portion
coming from the mid tier is explicitly directed to never be cached by the browser). The duration of
the cache directives is controlled by the following properties located in midTierInstallationDirectory/
WEB-INF/classes/config.properties:
Page 272 of 4705
Home
arsystem.resource_expiry_interval The duration (in seconds) the browser must

cache mid-tier platform resources, such as images, icons, CSS, ClientCore.js, and other
platform resource
arsystem.formhtmljs_expiry_interval The duration (in seconds) the browser
must cache the UI and active links (transformed into JS) associated to forms
Regarding the arsystem.formhtmljs_expiry_interval properties, the mid tier generates a
unique URL pattern (per user group) for access. This ensures that there is no security violation with
the cached UI and active links even if there are two users with different group access privileges
using the same browser on the same computer.
Note
Any changes to these properties require a restart of Tomcat or the web server hosting the
mid tier for the new values to take effect.
In a production environment where the BMC Remedy AR System definitions are not changed, set
the properties to at least 1 day (86400 seconds). Though you can manage each separately, setting
them to the same value eases management when altering BMC Remedy AR System web platform
resources or definitions.
These properties define how often the browser should check with the mid tier for updates. So, in a
typical deployment environment where the BMC Remedy AR System applications and platform are
no longer being modified, you might set the parameters to a week or longer.
The browsers behavior in relation to the mid tier-issued cache directive is as follows:
1. The browser requests for a resource from the mid tier.
2. The mid tier delivers the resource with the browser cache directive (for the duration as
configured).
3. After the cache directive has expired for the resource, on a subsequent browser request (or
a browser refresh) for the same resource, the browser sends a request to the mid tier with
the original cache directive.
4. On receipt of the request, the mid tier checks to see if the resource has changed since the
cache directive was issued.
a. If the resource has not changed, the mid tier returns an HTTP 304 response header (
with no data payload) instructing the browser to reuse and update the cache directive
of the resource.
b. If the resource has changed, the mid tier returns the new content with a new cache
directive.
Page 273 of 4705
Home
When content is unchanged, the response has zero data payload. However, on networks with
bandwidth saturation or long latency, many such requests can result in poor browser performance
because the request/response cycle takes time. Setting the browser cache directives to a longer
value means fewer browser checks with the mid tier for changed content, which results in faster
use case times. Set the cache directive interval correctly so that the browser does not have stale
contents.
Note
In production, suppose these properties are set to 1 week, and a change in a definition
occurs. If the change is for a non-user-facing form, then the change takes effect as soon
as the form definition is saved to the AR System server. If the change is for a user-facing
form, after the mid tier has synchronized with the AR System server, the users who have
accessed the changed form within the last week (less than 7 days) must refresh their
browsers or clean out the browser cache to see the change.
Most companies roll out the changes over a weekend. If both properties are set at 1 day, then on a
Monday when users access the mid tier, they will receive the new changes. However, deployments
that are 24 hours a day, 7 days a week must adopt a different strategy of browser caching.
Configuring the mid tier connection pool

Connection pool settings
Enable Lifespan parameter
Mid tier logging
Connecting the mid tier to a load-balanced AR System server group does not require the
TCP-binding setting on the load balancer. (For versions prior to version 7.6.04.02, TCP-binding or
TCP-sticky is required of the load-balanced configuration so that each client mid tier invokes
subsequent API calls to the same AR System server.)
The following independent configurations improve the performance when connecting to a
load-balanced AR System server group:
Connection Pool Settings Affects the connection pool manager
Enable Lifespan Affects the individual connection
Connection Settings page in the Mid Tier Configuration Tool
Page 274 of 4705
Home
Modify these settings by using the Mid Tier Configuration Tool instead of directly accessing the
config.properties file. Changes made in the UI take effect as soon as you click Save Changes.
The connection pool manager manages the creation and destruction of BMC Remedy AR System
API connections in its pool. If the mid tier connects to multiple AR System servers or server groups,
a pool is created per AR System server or server group, and this setting is a global setting that
affects all pools. (From the mid tiers perspective, a load-balanced server group is logically a single
AR System server.) To simplify the pool management process, there is no individual pool
configuration.
The pool properties are the following:
Maximum Connections per Server The maximum number of BMC Remedy AR
System API connections in the pool. This number prevents a runaway condition that an
unresponsive AR System server might cause, for example.
Idle Connections per Server The minimum number of BMC Remedy AR System
API connections available in the pool. When you start the mid tier, until there are enough API
calls to reach this number, the pool might not reach this number. In other words, the mid tier
does not create this number of connections on startup but only when needed. This is the
minimum number of connections in the pool during a low-service period.
Connection Timeout The maximum number of minutes a BMC Remedy AR System
API connection can stay idle before the manager cleans out the connection. By definition,
the manager cannot clean out a connection in the middle of a transaction because the idle
time of that connection would be zero.
The following rules worked favorably in BMC load and endurance tests:
Set Maximum Connections per Server to one-third of the anticipated number of
maximum concurrent users. This is the maximum number of simultaneous API calls the mid
tier can make to the AR System server or server group. If your user base is a heads-down
Page 275 of 4705
Home
type (such as in a call center), you might adjust it slightly higher. If your user base is the
casual type, you might adjust it slightly lower, but no lower than one-quarter of the
anticipated maximum number of concurrent users.
Leave Idle Connections per Server at the default (5) unless your need is different,
such as if you expect to have more than 15 users during a slow period. If your load-balanced
configuration does not match the TCP keep-alive setting of the OS that is hosting the AR
System server, you might experience stale connections. In this situation, set the OS TCP
keep-alive interval to match the load-balanced setting.
Set Connection Timeout to the TCP idle time setting for your load balancer. The
manager then cleans out stale or invalid connections. The default value is 0, which means
that each connection in the pool lives forever and is cleaned out only when it becomes
invalid. Setting this to a low value affects the JVM heap usage and Garbage Collection (GC)
because the JVM needs to create and destroy more connection objects.
Enable Lifespan parameter
The Enable Lifespan parameter is paired with the Connection Lifespan parameter. When
you select Enable Lifespan, each AR System connection is created with the expiration
indicated by the Connection Lifespan value. On expiration, the connection makes itself
available for GC. A connection will not put itself to GC while in the middle of a transaction.
When the numbers of connections in the pool drops, new connections are created as needed in a
load-balanced server group environment. A newly created connection is load-balanced possibly to
a different AR System server member. Therefore, on the average, the time interval of the
Connection Lifespan parameter indicates how often the connections in the pool are
re-balanced to all the members in the server group.
Note
You can also select Balance Now to re-distribute the connections on demand whenever
bringing up or taking down a new server group member.
Set Connection Lifespan to the lesser of 15 minutes or the server group load-balanced TCP
idle time. A smaller value creates additional work for the JVM GC because connection objects are
created and destroyed at a faster rate.
In a non-server group environment, the Enable Lifespan parameter is less useful because the
connection manager already has the Connection Timeout setting (see Connection pool settings
).
Mid tier logging
Logging provides runtime information and assists you when there is a problem to resolve. Too
much logging can affect the performance of the system.
The mid tier has the following logging categories:
Page 276 of 4705
Home
REPORTING
CACHE
SESSION
CONFIG
FLASHBOARD
WEBSERVICES
FIELD
WORKFLOW
PERFORMANCE
EXPRESSION
SERVLET
INTERNAL
ARSERVER
DVMODULE
In a production environment, unless you have a specific issue you want to track down, turn on only
the minimal logging:
arsystem.log_category=INTERNAL
arsystem.log_level=Severe

Client-side hardware
Browser configurations
Client-side hardware
Even though its web infrastructure and the web application might be optimally configured, if the
client-side computer is inadequate, then the users of the client-side computer do not experience the
superior performance expected of the server side. Your browser, computer hardware, and browser
configurations choices affect the following:
Workflow execution and user interaction The mid tier web application relies heavily on
JavaScript to execute all client-side workflow (active links, dynamic menus, auto-completion,
and so on). In general, the browser with the fastest JavaScript engine provides the most
responsive workflow execution and user interaction. For more information, see Reviewing
the compatibility matrix.
Overall performance Faster hardware (such as duo core CPU) executes faster JavaScript
, so the client-side hardware plays a central role in the overall optimal performance beyond
the specific browser choice.
Page 277 of 4705
Home
Browser performance Other hardware-dependent factors affecting browser performance

include TCP socket connection and SSL negotiation. SSL negotiation is most apparent on
slower hardware. When a web application is deployed on SSL, the difference in SSL
negotiation can exceed 3 seconds on a single CPU versus a duo core CPU.
Memory consumption From BMC Remedy Mid Tier 7.6.04 and later, the mid tier can
leverage in-memory caching by the browser. This is in addition to the standard browser
caching mechanism that stores the most frequently accessed URL resources on the hard
drive for faster subsequent requests for the same URL resources. Because of in-memory
caching, the browser consumes more memory while accessing the mid tier than with a
standard web application.
Security setting Adding the deployed server to the browser's list of trusted sites,
especially when deployed as HTTPS, improves browser performance by removing security
checking overhead.
For the client-side computer, BMC recommends a duo core CPU with 4 GB RAM.
Browser configurations
Depending on its settings, a browser can ignore browser cache directives issues by the mid tier,
resulting in poor performance.
To ensure that a browser observes the cache directives
Note
The following procedure in its entirety is only for Internet Explorer 6 or later. For other
browsers, only the disk space is configurable through the UI.
1. In the browser, select Tools > Internet Options.

2. Click Settings in the Browser history section.
3. Select Automatically.
4. Ensure that Disk space to use is set to at least 250 MB. This is the total disk space to use
for all websites.
Page 278 of 4705
Home
5. Click OK.
6. Click OK again to close the initial dialog box.
7. In the browser, select Tools > Internet Options.
8. Click the Advancedtab, and make sure that the following items are not selected:
Do not save encrypted pages to disk
Empty Temporary Internet Files folder when browser is closed
Page 279 of 4705
Home
Mid tier case studies

The following case studies illustrate performance improvements achieved by fine tuning the mid tier
:
Sluggish mid tier server behavior
Poor web application performance under SSL
Poor web application performance on long latency network
Sluggish mid tier server behavior

Scenario
When the mid tier was under normal usage load, an AR System form took several minutes to load
in the browser for some users. Some users received an HTTP 500 error.
Analysis
An HTTP 500 error is a generic web server error. Unless more specifics can be found, this error is
difficult to resolve. Start investigating this in the web server logs, not in the web application logs.
Look for any error at or near the time when the problems occur. For this case study, the factor of
slow loading of forms plays a large role.
When the service is poor, there is usually a CPU or resource contention. The natural course of
action is to monitor the Java Virtual Machine (JVM).
Root cause
Page 280 of 4705
Home
While monitoring the JVM that hosted the Tomcat running the mid tier, it was observed that the
JVM heap was over 90% used, so the Garbage Collectors (GC was) often running to reclaim
memory. In the Tomcat log, out-of-memory exceptions generated by the JVM were found. These
memory exceptions resulted in HTTP 500 errors, a generic web error that obscured details from
potential hackers. Tomcat was found to be hosting an additional web application BMC Remedy
Knowledge Management (RKM).
Resolution
Memory usage of the RKM application was profiled and found to require approximately 200 MB.
The JVM heap allocation was then increased to 1700 MB. The observed response time for loading
an AR System form then returned to an acceptable level, after restarting the JVM with the new
heap allocation. Note that, as of the 7.6.04 release, the RKM application is no longer a standalone
web application, but has been changed to a BMC Remedy AR System application. This case study
is still useful when another web application is required to be in the same web container as the mid
tier.
Poor web application performance under SSL

Scenario
When a deployment of a mid tier was put under HTTPS, the average response time for browser
loading of the same BMC Remedy AR System form increased by over 35%.
Analysis
The only factor is the HTTPS protocol. When a problem concerns browser loading time, use a web
debugging proxy (such as Fiddler), which provides the details of each request and response (
including timing) for an entire use case. Such a tool also captures the same use case under plain
HTTP. You can compare the capture of HTTP and HTTPS results to find where the additional time
is spent.
Root cause
Using a web debugging proxy to capture the browser requests and responses, it was observed that
an SSL socket was negotiated for every request that the browser sent.
Resolution
HTTP keep-alive was turned on, with the keep-alive count set at infinite and the maximum
connection timeout set at 60 seconds. After restarting the web server, the form loaded 10-15%
faster than with plain HTTP. This gain can be expected with keep-alive on (with maximum
connection timeout at 60 seconds or greater) than with keep-alive off.
Poor web application performance on long latency network

Scenario
When the mid tier was deployed as an internet application (not over VPN) in the United States (U.S
.), users in India experienced delays greater than 2 minutes to load an AR System form.
Analysis
Based on general networking knowledge, this is probably a latency problem. The latency at the
TCP layer did not provide accurate information in terms of browser performance because the
browser application works at the HTTP layer. Therefore, the latency must be determined at the
HTTP layer. To analyze browser performance relating to latency, use an http-ping tool, such as the
one from Core Technologies (for Microsoft Windows). Fiddler can also provide HTTP latency, but
only when actual requests are made. In contrast, the http-ping tool is more like the ping tool.
Page 281 of 4705
Home
For this case study, Fiddler was used to capture the same use case run from the U.S. and from
India. Then, a request comparison was made to see the accumulated effect of the HTTP latency.
Root cause
Using http-ping, the HTTP latency from India was measured. Then, using Fiddler, the HTTP
requests and responses from the U.S. and from India were captured. After comparing the
cumulative effect of the HTTP latency, the browser cache directive was increased.
Resolution
The values of arsystem.formhtmljs_expiry_interval and

arsystem.resource_expiry_interval were changed to 86400 (1 day). After restarting the
mid tier, loading forms took 5-7 seconds. With expiry for HTML/JavaScript and resources set to 1
day, the browser loaded from cache without sending requests to the mid tier for the duration of 1
day. After 1 day, requests for the same resources were sent to the mid tier with an
If-Modified-Since header, allowing the mid tier to reply with an HTTP 304 error (use browser cache
and update expiry as resources had not changed) with a 0-byte payload. This low payload allowed
for faster browser loading of forms.
Though the resolution could fix the latency issue, when a user loaded a form, the UI appeared
quickly while the data appeared more slowly. This was because the HTML/JS were already cached
in the browser. The overall user experience improved because the browser was more responsive
and less data was transmitted.

This section contains the following information:
Allocating AR System server resources
Setting the Max-Entries-Per-Query option
Designing efficient queries
Tuning the OS
Configuring AR System server queue threads for scheduler jobs
Configuring private queue threads
Configuring limits and timeouts
Because most of the business logic resides in the server tier, it is imperative to size and configure
the BMC Remedy AR System server correctly. Based on field experience, the following factors
might result in sub-optimal performance:
Insufficient hardware resources (CPU and memory) for any component in this tier
Poorly configured multi-threading and multi-process settings
Poorly configured limit and timeout settings
Poorly filtered user requests
Design deficiencies in the AR System workflow that lead to inefficient SQL
When tuning the AR System server, consider the performance of all of the components that it
interacts with and that draw on AR System server resources.
Page 282 of 4705
Home
Following are some of the components that affect AR System server performance:
BMC Atrium CMDB
Normalization Engine
Reconciliation Engine
Business Rules Engine
BMC Remedy Full Text Search Engine
BMC Remedy Flashboards
Application-specific plug-ins such as Overview Console and Command Application Interface
(CAI)
RKM plug-ins
BMC Remedy Assignment Engine
Allocating AR System server resources

CPU
Memory
To optimize performance of online transactions, create a dedicated integration server and move
resource-intensive batch or background processes to this server. Response times for online user
transactions should always be the priority. By moving all other components to an integration server,
online transactions do not have to contend for CPU and memory resources with other components.
If CPU on the BMC Remedy AR System server becomes a limiting factor, consider adding an
additional AR System server. An AR System server can scale easily with a server group. After you
have created a server group, you will have to balance the load from the mid tier to each AR System
server in the server group.
CPU
When tuning the AR System server, consider these facts:
It is a multithreaded application
Its default thread count settings are low to accommodate the lowest common denominator
for hardware
If the thread count is set too low, the AR System server will have low CPU use, poor throughput,
and potentially poor response time under high loads. If the thread count is set too high,
unnecessary thread administration can result. Instead, start with fast threads set to 3 times the
number of CPU cores and list threads set to 5 times the number of CPU cores. Then, fine tune
further by conducting tests using the specific infrastructure. For example, a two-CPU box might
have 6 threads for fast and 10 threads for list.
Page 283 of 4705
Home
Note
BMC recommends using the same value for the minimum and maximum settings.
AR System server applications work well on a variety of hardware platforms, including symmetric
multiprocessor (SMP) systems that have many CPUs. The OS for SMP systems might develop
thread contention with high thread counts for fast and list threads. Therefore, SMP systems with
more than 8 CPUs might perform better with smaller thread counts, where the maximum for any
thread pool is 30 or less.
Consider these suggestions as a starting point. Since there are several variable factors (including
different hardware, CPU architecture, and CPU speed), benchmark your environment to determine
its optimum settings for fast and list threads.
Memory
As mentioned in System performance and capacity, make sure that the system has enough
physical memory to avoid swapping. Use OS tools such as Performance Monitor (Microsoft
Windows) to monitor the server. When the OS runs low on memory, it starts paging, which severely
impacts performance. By monitoring process memory usage and the amount of paging, you can
identify problems.
A common cause of memory depletion is the CopyCache operation. The AR System server
performs this operation when an administrative change is made to object or group definitions. To
improve performance, the AR System server caches all forms and their related objects as well as
group information into memory at startup. This caching enables users to access objects more
quickly than they could if the AR System server had to retrieve their definitions from the database
each time the objects were needed.
When an administrative change occurs, the AR System server creates a copy of its cache. The
amount of additional memory used during a CopyCache operation is roughly the size of the initial
memory footprint of the AR System server. If adequate memory is not available, then the OS might
start paging and cause severe performance degradation.
When a CopyCache operation creates a new copy of the cache, the original cache is still intact and
available for all active operations to complete their tasks. After each running operation completes, it
is directed to the new cache. Becaue the last operation is done with the original cache, that cache
is removed and its memory is freed. Long-running operations could cause multiple cache copies to
be in use for a significant amount of time. Examples of long-running operations are escalations,
large queries, and long Atrium Integration Engine jobs. In some cases, four or more copies of the
cache could be present in memory, each consuming about the size of the initial AR System server
memory footprint.
Because of the heavy memory usage of a CopyCache operation, it is important to manage
administrative changes through user behavior and correct configuration:
Page 284 of 4705
Home
Perform administrative changes during non-peak hours.

Do not make administrative changes during periods of peak usage. This ban includes
actions in ITSM applications that can cause CopyCache operations, such as creating or
deleting a service target; adding or removing attributes in the CMDB; and creating, modifying
, or deleting a company.
Set the Max-Num-Caches parameter in the ar.cfg (ar.conf) file to manually set a limit to the
number of cache copies that can exist at one time.
If the maximum number of cache copies is already present, then a subsequent
administrative change cannot be made, and the following error is displayed:
ARERR 9911
Admin operations are suspended because the number of open caches is at the
configured limit.
Set the Delay-Recache-Time parameter in the ar.cfg (ar.conf) file to the number of
seconds to wait before the server makes the latest cache available to all threads.
Valid values are 0-3600 seconds. The default value is 5 seconds. Since the new cache is not
made available to other threads until the timeout is reached, subsequent administrative
changes can update that copy of the cache rather than creating additional cache copies. By
setting this value to a higher number, a cache copy is built fewer times, so fewer multiple
cache copies should exist.
The recommended value is 300 (5 minutes) but can be set as high as 3600 (60 minutes) if
there are going to be many Admin changes over a period of time and delaying their
availability to end users is acceptable.
Set the Cache-Mode parameter to a value of 0 (Production Cache mode, the default) or 1 (
Development Cache mode).
If doubling of memory is time-consuming (possibly due to paging), or there simply is not
enough memory to double the AR System server memory, Development Cache Mode
provides a way to make an administrative change without performing the Copy Cache. This
option locks the Server Cache, performs its change, and then releases it. The downside is
that all other AR System server work is blocked while the cache is being updated (though
this is typically a quick operation). Of greater concern is that to get the exclusive lock
required to modify the cache, the administrative operation must wait for all other work to
complete. In the meantime, all other activity must queue up behind the administrative
operation, so a blocking condition might occur. Consequently, when the initial operation
takes a long time (such as a long-running escalation), the server acts as if it is in a hang
condition until the administrative operation has completed.
Adding memory to a system might also resolve the problem.
You might also configure or limit the amount of memory a component can use. For example, you
might set the MaxHeap for Java applications (or configure it to not use as much memory by using
fewer threads), perform smaller queries, or chunk data.
Page 285 of 4705
Home
The following configuration parameters log cache operations and large memory allocations:
Set the Copy-Cache-Logging parameter to T.
Add this parameter directly to the ar.cfg (ar.conf) file and then enable thread logging. This
parameter writes to the arthread log file details about each cache operation, including the
time it was requested, the time it occurred, when the memory was freed, and how many
copies of the cache exist.
Set the Large-Result-Logging-Threshold <bytes> parameter
Add this parameter directly to the ar.cfg (ar.conf) file and then enable thread logging. This
parameter writes to the arthread log file each time an API call requests memory larger than
the threashhold. This is useful for monitoring users that are performing large queries that
cause AR System server memory growth.
Setting the Max-Entries-Per-Query option

The Max-Entries-Per-Query parameter sets the maximum number of requests that a search
can return. BMC recommends always setting the Max-Entries-Per-Query parameter because
unqualified searches can yield enormous result sets. This leads to a large amount of memory
allocated to each BMC Remedy AR System server thread that processes this type of search. In
addition, queries will take longer to execute and use more database resources.
Limit the entries to be displayed to no more than 2000 entries. Depending on the functional
requirements of your business, it might be optimal to set this parameter as low as 300.
Users can specify the maximum number of requests returned through Search Preferences in the
AR System User Preference form, but the actual maximum is the lower of these values.
Similarly, you can adjust how much data is returned by setting the chunk size for table field or form
results lists. The default table-field chunk size is 1000. Table field chunk size can be set at a field
property level if a size other than the default is needed. Form- level results list chunking can be set
as a view property.
Note
For a table field, the value of the Max-Entries-Per-Query parameter supersedes the
value of chunk size.
Designing efficient queries

It is important to design efficient queries. Although the AR System server generates most SQL
statements, you can influence the structure of SQL statements by the design of the workflow (
escalations and active links that they create on forms).
Consider the example in which a user searches for customers by name. Workflow creates the
following complex SQL statement:
Page 286 of 4705
Home
SELECT
T313.C1,C750010114,C750010112,C750010109,C750010103,C750010113,C750010118,C750010101,
C750010102,C750010108,C750010106,C750010107,C750010110,C750010111, C750010115,C750010119
,
C750010120 FROM aradmin.T313
WHERE (
((T313.C750010114 = ' ') OR (' ' = ' ')) AND
((T313.C750010109 = ' ') OR (' ' = ' ')) AND
((T313.C750010112 LIKE ((('DOE' || '%') || 'JANE') || '%')) OR
('DOE' = ' ') OR ('JANE' = ' ')) AND
((T313.C750010101 LIKE (' ' || '%')) OR (' ' = ' ')) AND
((T313.C750010118 = ' ') OR (' ' = ' '))
)
ORDER BY 1 ASC
This online query takes over 2 seconds. The SQL is overly complex as it has unnecessary WHERE
conditions.
A properly designed workflow creates a SQL statement with WHERE conditions for which the user
enters a value.
The following SQL statement has the same functionality as the previous example, but is less
complex for the Oracle optimizer to interpret.
SELECT
T313.C1,C750010114,C750010112,C750010109,C750010103,C750010113,C750010118,C750010101,
C750010102,C750010108,C750010106,C750010107,C750010110,C750010111, C750010115,
C750010119,C750010120 FROM aradmin.T313
WHERE (
((T313.C750010112 LIKE ((('DOE' || '%') || 'JANE') || '%')) OR
('DOE' = ' ') OR ('JANE' = ' '))
ORDER BY 1 ASC
In turn, Oracle correctly determines the proper index to use and the SQL statement executes in
less than 10 milliseconds.
Tuning the OS
Tune the OS to respond quickly to BMC Remedy AR System server requests.
For Oracle Solaris, use libumem for memory management instead of the standard Solaris memory
management library. The libumem tool provides the following:
Better performance when used on multi-CPU servers
Better conservation of memory usage after recaches
Built-in diagnostics and statistics (such as mdb, umastat)
Page 287 of 4705
Home
Using libumem requires setting the LD_PRELOAD environment variable to libumem.so before
starting the AR System server.
For Linux, BMC recommends using TCMalloc (libtcmalloc) rather than the default memory
manager (libc). Both internal and external tests show that TCMalloc drastically improves
memory conservation after recaches and other heap-intensive operations (such as EXPQRY).
Refer to the following Knowledge Article for detailed steps on implanting to TCMalloc for memory
management: https://kb.bmc.com/infocenter/index?page=content&id=KA347994&actp=search&
viewlocale=en_US&searchid=1347565791299
Configuring AR System server queue threads for scheduler jobs

A thread pool is a collection of worker threads that the AR System server uses to process
concurrent client requests. The threads are allocated to queues from the thread pool on the
per-need basis. A single thread from the pool can handle requests, such as archiving, escalation,
server statistics, and application statistics.
Note
The Fast, List, and Private queues do not use threads from the thread pool. Only
scheduler jobs use the threads from the thread pool.
A thread is allocated to a request from the list of available threads in the thread pool. When a
thread completes its processing, it is returned to the pool. For example, if a server statistics request
comes up and a thread that just finished an archiving request is available, the same thread can be
allocated to the server statistics request.
When all the existing threads are in use, the Java server starts additional threads as needed until
the maximum queue size is reached. (See Defining queues and configuring threads.)
Similar operations run sequentially. For example, two forms are not archived at the same time or
two escalations marked for the same escalation pool will not run at the same time.
Note
You cannot reserve threads in the thread pool for specific operations.
BMC Remedy AR System API logging reports how long each API call waits before a thread starts
to process the request.
The thread wait time is displayed after each call as follows:
Page 288 of 4705
Home
// :q : < wait time in seconds>
Following is an example log:
<API > <TID: 0000006384> <RPC ID: 0000002985> <Queue: Fast> <Client-RPC: 390620 > <USER
: Demo
> <Overlay-Group: 1 > /* Sat Aug 11 2012 16:53:12.6950 */+CE ARCreateEntry -- schema
DSS:NearEarthOrbitRecalc_InFlt from Remedy User (protocol 14) at IP address 172.28.32.58
// :q:0.7s
000000000000203
Use BMC Remedy AR System API logging for the following situations:
Users who are reporting slow response time for online transactions
New implementations or upgrades during the performance benchmarking phase prior to
placing the system in production
Periodically check of the general health of the system
If the log shows sustained wait times of more than 0, increase the number of threads for the queue.
Increase the number of threads in the queue until your API log consistently shows thread wait times
of 0. However, after CPU consumption on the AR System server reaches an average of
approximately 70%, do not add more threads to the queue.
For list or private queues, a large result set from a query set might occur for every thread in the
queue. For example, operations that consume a lot of memory (such as nested filters with push
fields operations that update a large number of records) could occur on every thread in the queue.
For this reason, memory is a consideration when increasing the thread count. Adding too many
threads could cause memory paging to occur, which would severely impact system performance.
High queue thread wait times might not necessarily mean that not enough threads are set in the
system. Instead, the wait times could be result of an application performance problem. For example
, a transaction that users frequently run could have a poorly performing SQL. Every user executing
the transaction ties up a thread while waiting for the database to execute the long-running SQL. If
enough users are executing the transaction (and, in turn, the problem SQL), all of the threads could
quickly become used. In this case, tune the SQL instead of adding more threads.
Configuring private queue threads

C plug-ins
Java plug-ins
BMC Atrium CMDB thread sizing
FTS thread sizing
Page 289 of 4705
Home
Related Topics
In case of heavy workload, create Private Queues with specified threads counts to allocate
resources to different workload components. This provides the following advantages:
Limits the number of threads for a particular component
Makes sure that the components workload does not directly interfere with the regular
workload (running on fast and list threads) by executing the work in separate pools (Private
Queues)
Restricts the amount of CPU that individual components use
You can tune most components to limit the number of BMC Remedy AR System server threads
and configure the number of threads used internally by that component. To limit the number of AR
System server threads, assign a Private-RPC-Socket (private queue) and set the appropriate
minimum and maximum threads.
The following table lists tuning methods for several workload components.
Tip
Press f to open the page in full screen mode. Press Esc to exit the full screen mode.
Thread tuning for workload components

Component
Suggested
Private-RPC-Socket
Where to configure the Private

Queue to use
How to configure the internal thread count
In the ar.cfg (ar.conf) file,

comment out the parameter for
In the ARSystemInstallDirectory/pluginsvr/fts/
setting
Full-Text
Search
390602
Engine
Private-RPC-Socket: 390602, if it
exists. Because of this, the
Full-Text Search Engine uses a
pluginsvr_config.xml file,
enter the following setting:
<numCoreThreads>10
</numCoreThreads>
single thread, which is

recommended in most cases.
Email Engine
390681 2 2
<serverName>.RPC=390681
The number of threads connecting to the AR

System server is equal to the number of enabled
mailboxes.
Set the ARServerRpcNumber
Flashboards is single-threaded.
Emaildaemon.properties
com.bmc.arsys.emaildaemon.
Flashboards
390619 1 2
parameter in the
ARSystemInstallDirectory/
flashboards/server.conf file.
CAI
390693 2 6
of queue threads to be a maximum of 2. This

makes sure that if one thread takes too long and
times out, the plugin can connect back in on the
second available thread.
Open the CAI Plug-in Registry
In the CAI Pool Configuration section, for pool 0,
through Application Console >
make sure the number of the threads is 6. The CAI

plug-in for BMC Remedy IT Service Management
Customer Configuration >
Note: For single threaded plug-ins, set the number
Page 290 of 4705
Home
Component
Suggested
Private-RPC-Socket
setting

Queue to use
Foundation > Advanced Options
uses pool 0. Another application uses pool 1000.
>
The total of all pool threads is listed in the Total
PlugIn Registry.
Threads field. For more information, see

Configuring BMC Remedy AR System server for
private server queue.
In the CAI Plug-in Registry dialog

box, either create a new entry
(if one does not exist for Private
Queue 390693) or modify the
existing entry.
Overview
Console
390685 4 6
Configure the APPQUERY plug-in

with the
Plugin-Loopback-RPC-Socket
user-defined property in the
ARSystemInstallDirectory/
ARSystem/pluginsvr/
pluginsvr_config.xml file.
For more information about configuring CAI, see the

article
The Pulse: Queues & Threads Utilizing Private
Queues on BMC Communities.
In the ARSystemInstallDirectory/pluginsvr/
pluginsvr_config.xml file,
enter the following setting:
<numCoreThreads>30
</numCoreThreads>
The core threads running in this plugin server are
shared with all other plug-ins.
Set the value to the Private Socket

number. For example, 390685.
Atrium
Integration
Use any available

private socket from
To set an Atrium Integration

Engine default RPC-socket, edit
In the Advanced tab of the Data Exchange page
Engine
the range:
the
of Threads.
for each Exchange, provide a value for the Number
aie.cfg file in the

390621-390634
390636-390669
AtriumInstallDirectory/aie/
service64/conf/ directory, and set
the PrivateRPCPort parameter.
The default value is 3. The maximum value is 49.
390680-390694
To specify a private socket for
each Exchange, go to the
Connection Settings tab of the
Data Exchange page for that
Exchange; then clear Use default
destination AR server, and
specify the RPC Program
Number.
Normalization
Engine
390699 <1 x #CPUs

> <1 x #CPUs>
BMC Atrium Core Console >

Normalization > Configuration
Editor > System Configuration >
CMDB RPC Queue
BMC Atrium Core Console > Normalization >

Configuration Editor > System Configuration >
Threads and Connections
Normalization
Engine AR
RPC Queue
390621 <1 x #CPUs

> <1 x #CPUs>
BMC Atrium Core Console >

Normalization > Configuration
Editor > System Configuration >
RPC Queue
This plugin automatically sizes itself based on the

number of available threads in the defined RPC
Queue.
Business Rule
Engine
390625 1 2
BR-RPC-Socket: 390625
Single threaded.
Page 291 of 4705
Home
Component
Suggested
Private-RPC-Socket
setting

Queue to use

Approval
Server
390680 3 10
Approval-RPC-Socket: 390680
For versions prior to 8.0, Approval server is

single-threaded. Set 390680 1 2.
For version 8.0 and later, Approval Server is
multi-threaded and runs as a Java plug-in.
Go to Approval Administration Console > Server
Settings > Basic > Thread Count to set the
number of threads that the Approval Server uses.
This is the ASJ-Thread-Count option in the ar.cfg (
ar.conf) file. Set Private-RPC-Socket: 390680 to
match this number.
For example, set the Thread Count to 5, and set
Private-RPC-Socket: 390680 5 5. If you have other
highly intensive clients using the same private
socket, set Private-RPC-Socket to a higher
number.
Reconciliation
Engine
390698 <1 x #CPUs

> <1 x #CPUs>
Set the RE-RPC-Socket, either

through BMC Atrium Core
Reconciliation Engine automatically detects and

uses the number of threads available in this queue.
Console > Applications >

Reconciliation > Server
Configuration Editor > RPC
Socket or manually using the
Note: BMC recommends that you use 390698 as

the queue number since this queue is used
out-of-the-box.
ar.cfg (ar.conf) file.

AREA-LDAP
Plugin-AREA-Threads (C-Plugin only)
ARDBC-LDAP
Plugin-ARDBC-Threads (C-Plugin only)
DSO
Use any available

private socket from
the range:
For a local server, go to AR
Developer Studio > Distributed Pools > Create
System Administration Console
new pool.
Each pool is a single thread.
> General > Server Information >

Connection Settings > DSO
390621-390634
390636-390669
390680-390694
Local RPC Program Number.

For a remote server, go to AR
Note: Define the DSO Mappings to use a specific

pool number otherwise the first pool number is used
.
System Administration Console

> General > Server Information >
Connection Settings > DSO
Server Setting Table.
390626 5 5
Page 292 of 4705
Home
Component
Suggested
Private-RPC-Socket
setting
Plugin
Loopback
Socket

Queue to use
Set Plugin-Loopback-Socket:
This is the default socket that many plug-ins use, if

they are not configured for a specific RPC socket.
390626 in the ar.cfg (ar.conf) file.

Some plug-ins automatically use
the Plugin-Loopback-Socket, if
they are not defined for a specific
RPC queue.
Assignment
390630 2 3
Engine
In the ar.cfg (ar.conf) file, set
Go to Assignment Engine Administration
AE-RPC-Socket: 390630.
Console > Server Settings > Number of threads.

The default value is 3.
C plug-ins
For any component that runs as a C plug-in, consider the number of fast, list, escalation, private
threads that are likely to communicate simultaneously with the particular type of plug-in (AREA,
ARDBC, Filter API) and set the appropriate option in the ar.cfg (ar.conf) file (
Plugin-AREA-Threads, Plugin-ARDBC-Threads, and Plugin-Filter-API-Threads).
For example, suppose 4 escalations run on 4 separate escalation pools run nightly, and 10 list
threads might access the ARDBC LDAP plug-in. In this case, you might need as many as 14
Plugin-ARDBC-Threads. If most users are not accessing the LDAP data during the time that the
escalations run and only 20% of the user activity is likely to access the ARBDC-LDAP vendor form,
then you might choose to set Plugin-ARDBC-Threads to 2 6.
You can set different minimums and maximums at first, and then monitor the plug-in log to see if
more than the minimum threads are being used. Then you can target a value to use for both the
minimum and maximum.
Java plug-ins
For any component that runs as a Java plug-in, you can configure the Java plug-in server to use a
specific number of threads by adding the following parameter to the pluginsvr_config.xml file:
<numCoreThreads>12</numCoreThreads>
Since there is not a minimum and maximum, set this value to the value that would provide
maximum performance without consuming too many resources. For example, the Full Text Search (
FTS) engine runs in a Java plug-in server that does not service any other plug-ins. So, if 12 list
threads are likely to access the FTS engine simultaneously, set this value to 12.
The Java Heap size can be manually set for each Java plug-in server. From the armonitor
configuration file, locate the line that calls the specific Java instance that you want to configure. By
looking at the --classpath parameter, you can identify the purpose for each Java instance. The
Xmx parameter can be set to indicate the maximum size for the Java Heap. For example, "C:\
Program Files\Java\jre6\bin\java" -Xmx512m --classpath sets the limit to 512 MB.
BMC Atrium CMDB thread sizing
Page 293 of 4705
Home
BMC Atrium CMDB normalization and reconciliation processing are CPU intensive. By default,
CMDB processes are executed using fast and list threads. Private queues allow you to restrict how
much CPU is used by CMDB processes.
Normal day-to-day CMDB processing should not consume more than 20% of AR System server
CPU capacity. The goal is to obtain optimal throughput for CMDB processing while not sacrificing
response time for the users who are doing online transactions.
Configure a private queue with minimum and maximum thread settings of one times the number of
CPU cores as the starting values. Adjust the thread settings based on the BMC Atrium CMDB
workload, online workload, and thorough performance testing.
FTS thread sizing

The standard AR System server installation establishes a private queue for the FTS component.
The default thread setting is 1 for minimum and maximum. Consider adjusting this setting upward if
there is a backlog of entries to be indexed. This is most likely to happen during an initial index build
or an index rebuild.
You can configure and tune BMC Remedy Email Engine parameters to optimize outgoing email
performance.
By default, outgoing email is set to use 4 threads by all outgoing mailboxes. This is sufficient if the
outgoing email load is not heavy and you do not need emails sent quickly. However, if your Email
Engine is installed on a system that is separate from the AR System server, you should configure
for more outgoing email threads to allow for faster performance.
The number of sender threads can have a maximum value of 20. You can lower this setting if the
Email Engine consumes more CPU cycles than you want. For example, if the email server is
located with the AR System Integration Server, then allow some room for the AR System
Integration Server to process other workloads during production hours. To change the number of
sender threads, edit the following options in the EmailDaemon.properties file:
com.bmc.arsys.emaildaemon.NumberOfSenderThreads=20
com.bmc.arsys.emaildaemon.MailboxPollingUnitIsMinutes=false
In the AR System Email Mailbox Configuration form for outgoing mailbox configuration, you can
also set the polling interval to be in seconds and indicate the number of seconds. This value
indicates how often the Email Engine looks for AR Email Messages to process.
Incoming email uses one thread per incoming mailbox and cannot be changed. If you have
changed the mailbox polling units to seconds, then you must also indicate the polling value for
incoming mailbox. This value indicates how often the Email Engine looks for entries in your email
server.
390621 - 390634
Page 294 of 4705
Home
390636 - 390669
390680 - 390694
Related Topics
Private queues for loopback calls
Configuring limits and timeouts

The following table provides performance optimization recommendations for BMC System Action
Request System configuration parameters. These recommendations are for BMC Remedy Action
Request System 7.5 or later.
Limit and timeout setting recommendations
AR System server configuration
Description
parameter
Private-RPC-Socket (Fast:
Recommended
value
Set this parameter for fast and list threads values only.
390620)
Private-RPC-Socket (List:390635
)
Fast thread
values equal 3
times the
number of
CPUs.
List thread
values equal 5
times the
number of
CPUs.
Next-ID-Block-Size
Allocates next IDs in blocks instead of one at a time. Allocating in
100
blocks increases performance during create operations. Values are any

positive number up to 1000. The default value is 100. (A value of 1
disables the feature.) You can also disable it by removing it from the
configuration file. You do not need to restart the server for the change
to take effect.
This setting is always disabled on the Distributed Pending form so that
DSO can operate correctly.
Next-ID-Block-Size can also be set as a form property on an individual
form basis. That value takes precedence over the server setting.
Warning : Using this option might result in unpredictably large Next-ID
sequence gaps. The likelihood of this occurring increases with the use
of multiple servers that share a database. The BMC Remedy AR
System server will not malfunction because of this gap, and it should
not be considered a defect.
Server-Side-Table-Chunk-Size
For server-side table fields, specifies the number of requests (or size of
the chunk) that the server retrieves at one time from the database and
stores in memory to process during filter or filter guide actions. The
server then retrieves, stores, and processes the next chunk until all
requests are processed.
1000 (this is the

default)
Page 295 of 4705
Home
AR System server configuration

parameter
Description
Recommended
value
A value of 0 causes the server to retrieve an unlimited number of

requests. Specifying a value lower than 1000 causes the server to
process smaller chunks, which reduces server memory use but results
in slower processing because the server must access the database
many times, especially for large tables. Specifying a value higher than
1000 causes the server to retrieve and process large chunks of data
and access the database fewer times, resulting in improved
performance at the cost of increased memory use.
Allow-Unqual-Queries
Specifies whether unqualified searches can be performed on the AR

System server. Valid values are T (allows unqualified searches) or F (
F (disallow)
disallows unqualified searches). The default value is T.

Unqualified searches are ARGetListEntry or
ARGetListEntryWithFields calls in which the qualifier parameter
is NULL or has an operation value of 0 (AR_COND_OP_NONE). Such
searches might cause performance problems because they return all
requests for a form. This is especially problematic for large forms.
Cache-Mode
Specifies whether a cache mode optimized for application development

is on. In development mode, user operations might be delayed when
changes are made to forms and workflow. Valid values are 1 (
development cache mode is on) or 0 (development cache mode is off
and the server is in production cache mode). The default value is 0.
0 (development
mode off; this is
the default)
For more information about Cache-Mode, see Allocating AR System

server resources.
Debug-mode
Specifies the server logging modes. See ar.cfg or ar.conf options C-D
for all possible values.
0 (all logging off

for a production
environment)
Minimum-API-Version
The oldest API version with which the server communicates. The
Set to a value
default value is 0 (the server communicates with all API versions).
appropriate for
your production
Generally, your system should support two earlier versions. If the client
s API version is less than the specified value, the server refuses to talk
environment.
with the client, and the client receives a decode error. Supporting too
many versions means there are excessive amounts of RPC parameter
conversions that will degrade performance. For values corresponding
to BMC Remedy AR System release versions, see Setting
administrative options.
CMDB-Cache-Refresh-Interval
The interval of time (in seconds) when CMDB calls the AR System
server to update cache-related data. The default is 300 (5 minutes) if
the entry does not exist in the AR System server configuration file.
600 (10
minutes)
Tuning a database server

The BMC Remedy AR System database server is the server in your BMC Service Management (
BSM) configuration that requires the largest amount of I/O bandwidth. Use external storage for this
system because local disks might fail to keep up with the demands of a substantial implementation.
Any I/O bottleneck will limit overall throughput and increase system response time.
Page 296 of 4705
Home
This section provides the following information for tuning database servers:
Tuning an Oracle server
Tuning an SQL Server database
Tuning an Oracle server

This section provides the following information for the Oracle database:
Initial database configuration
Cursor sharing
Cost-Based Optimizer
Oracle CLOB storage
Oracle case-insensitivity
Oracle database diagnostics
Oracle case study
Although the commands and syntax differ, similar methodologies can also be effective for other
databases.
Initial database configuration

The basic memory structures associated with Oracle include SGA and PGA.
System Global Area (SGA) Shared by all server and background processes. The SGA
holds the following:
Database buffer cache
Redo log buffer
Shared pool
Large pool (if configured)
Program Global Areas (PGA) Private to each server and background process. Each
process has one PGA. The PGA holds the follwoing:
Stack areas
Data areas
In Oracle 11g, the following parameters enable automatic memory management to control both the
SGA and the PGA:
memory_max_target Governs total maximum memory for the SGA and the PGA.
memory_target Governs existing sizes for the SGA and the PGA.
Oracle 10g includes the following parameters for automatic memory management for the SGA and
a separate parameter for the PGA:
sga_max_target Governs total maximum memory for the SGA
sga_target Governs existing memory for the SGA
Page 297 of 4705
Home
pga_aggregate_target Defines the memory size for the PGA

For Oracle 10g and 11g, the regular memory parameters, such as db_cache_size and
shared_pool_size, define the minimum size Oracle will maintain for each subarea in SGA.
The following table lists the capacity recommendations for small, medium, and large Oracle
databases.
Oracle database recommendations
Cursor sharing
The most important parameter setting in Oracle for BMC Remedy applications is
cursor_sharing, which determines what kind of SQL statements can share the same cursor. Its
default value is EXACT, which means that Oracle allows statements with identical text to share the
same cursor.
Because BMC Remedy AR System issues SQL statements with literals, the application could issue
thousands of SQL statements. Each statement is treated as a different statement and is parsed.
This frequent parsing of the SQL statement uses significant resources such as shared pool and
library cache latch, which severely limit performance and scalability. Setting cursor_sharing to
Page 298 of 4705
Home
FORCE or SIMILAR is a way to mitigate this issue. With cursor_sharing set to FORCE or
SIMILAR, Oracle replaces literal values with system-generated bind variables in the SQL statement
. This increases soft parsing but significantly reduces hard parsing.
BMC recommends setting cursor_sharing to FORCE. An excessive number of child cursors is
an issue with SIMILAR.
BMC Remedy applications do not provide any bitmap indexes out of the box. However, the
optimizer can choose a bitmap access path without the presence of bitmap indexes in the database
by using the CPU-intensive BITMAP CONVERSION FROM/TO ROWID operation. Set _
b_tree_bitmap_plans to False to avoid this issue.
Cost-Based Optimizer
When used with Oracle 10g or later, BMC Remedy AR System applications depend on Oracles
Cost-Based Optimizer (CBO) for performance. When the AR System server issues an SQL
statement, the CBO uses database statistics to determine an optimal execution plan to fetch the
required data. By default, Oracle automatically gathers statistics using a scheduled job (
GATHER_STATS_JOB), which runs locally within a maintenance window between 10:00 P.M. and
6:00 A.M. weeknights and all day on weekends.
Query the database to determine when statistics were last gathered. If statistics were not gathered
recently, make sure that automatic statistics gathering is enabled. Lack of statistics can lead to poor
SQL execution plans and inefficient database processing.
The only time you might need to gather statistics manually in an Oracle database is during batch
jobs that begin with an empty destination table. Statistics on such a table reflect that it is empty. If
the table subsequently becomes very large, operations against the table might begin to perform
poorly because the statistics no longer reflect its true size. If this occurs, you can gather statistics
during the execution of the batch job. Consider this only for batch operations that take hours rather
than minutes.
Oracle CLOB storage

The default for character large object (CLOB) column storage during an AR System server
installation is Out Row. For example, the actual data is stored outside the actual row that contains
the CLOB column.
If high database space growth is a concern, convert CLOB storage to In Row. For more information
, see Using Oracle CLOBs with BMC Remedy AR System .
Oracle case-insensitivity
If you need to make the Oracle database case-insensitive, set the following parameters in Oracle
10g and Oracle 11g:
Parameter
Description
NLS_COMP
Specifies how the predicates in an SQL statement will be compared. Valid values are:
BINARY Compares according to the binary value of the characters.
ANSI Still available (from Oracle 9i) but only for backward compatibility.
Page 299 of 4705
Home
Parameter
Description
LINGUISTIC Honors the setting of NLS_SORT.
NLS_SORT
Specifies the collating sequence for ORDER_BY queries. Valid values are:
BINARY The collating sequence is based on the numeric value of the characters.
Named Linguistic Sort Sorting is based on the order of the defined linguistic sort.
To make Oracle use an existing index on a column that is present in one or more queries
1. Set NLS_COMP and NLS_SORT at the session level or the database level.
2. Drop and recreate all ARADMIN indexes as function-based indexes.
Setting NLS_SORT in a session

SQL> alter session set NLS_SORT=BINARY_ CI;
Drop and recreate an index as a function-based index
SQL> drop index <index name>:
SQL> create index <index name> on
<table_name>(NLSSORT(<column_name>, NLS_SORT=BINARY CI)):
If you still have a Full Table Scan against the table after following this procedure, then force the
Oracle CBO to pick up the index by completing the following step:
Set the Oracle parameter optimizer_index_cost_adjustto 1 at the session level.
SQL> alter session set

optimizer_index_cost_adjust=1:
The default value for optimizer_index_cost_adjustis 100.
Note
This setting forces the Oracle CBO to choose index lookups over Full Table Scans.
BMC recommends thoroughly assessing the impact of these settings in your
development and quality assurance environments before implementing this setting
in production.
Oracle database diagnostics

Typically, Oracle 10g/11g diagnostics come in the form of a report called Automatic Workload
Repository (AWR). To create an AWR report, a snapshot is taken before and after the period of
interest. The report is then generated to show how the system counters (V$ views) changed
between the two snapshots. Oracle AWR snapshots are automatically taken every hour unless
changed by the DBA. Reports are most valuable when they focus on a period of high activity.
Page 300 of 4705
Home
The AWR reports include a high-level summary of system usage, specific observed wait events,
and a list of high-load SQL statements. Oracle documentation explains how to interpret the reports.
The following points provide additional guidelines.
Make sure the Buffer Cache and Shared Pool are well used.
Instance efficiency percentages (target 100%)
Buffer NoWait %:
100.00
Redo NoWait %:
100.00
Buffer Hit %:
99.99
In-memory Sort %:
100.00
Library Hit %:
98.99
Soft Parse %:
99.51
Execute to Parse %:
3.51
Latch Hit %:
100.00
Parse CPU to Parse Elapsed %:
86.68
% Non-Parse CPU:
93.57
A section near the top of the AWR report addresses Shared Pool usage. If the amount of
consumed Shared Pool memory is above 80% and the use of statements is low (for example
, less than 40% of memory is used by statements executed more than once), your system is
not reusing SQL statements efficiently. This could happen if cursor_sharingis set to
EXACT.
Shared pool statistics
Begin
End
Memory Usage %:
86.17
86.27
% SQL with executions>1:
93.33
94.74
% Memory for SQL w/exec>1:
97.83
98.25
The best practice is to set cursor_sharing to FORCE for Oracle 10gor later.
Note
For AR System server settings, the cursor_sharing setting in the ar.cfg file
must match the setting in the init.ora file.
The overall sizing for the Buffer Cache and the Shared Pool in Oracle depends on whether
the OS is 32-bit or 64-bit. If you encounter a problem, add memory to the cache or the pool,
but do not make them larger than the size shown in the table in Initial database configuration
.
If the Buffer Cache and Shared Pool are well used, check for blocking wait events.
In the wait event summary at the top of the AWR report, the CPU time event should be near
or at the top of the list (ideally 70% or more). Typically, CPU time might be low if you are I/O
bound. If the top wait events are relate to I/O, you might be getting poor SQL execution
plans.
Page 301 of 4705
Home
The high-load SQL statements that Buffer Gets order are listed further down the report. If
you see statements with very high Buffer Gets per Execute, an index might be missing on a
table that the statement accesses. db_file_scattered_read wait events are associated with
Full Table Scans or Index Fast Full Scans and can indicate a need for additional indexes (or
up-to-date statistics for Oracle).
The following table lists the top timed events:
Event
Waits
Time (sec)
Average wait (msec)
% total call time
Wait class
CPU time
n/a
94
n/a
95.7
n/a
LNS wait on SENDREQ
713
51
71
51.8
Network
Log file parallel write
15,869
10
10.6
System I/O
Log file sync
14,965
10
10.4
Commit
Control file sequential read
21,781
10
10.0
System I/O
Use the Oracle SQL tkprof trace utility.

To learn about executed SQL statements and their execution plans, use the Oracle SQL
tkprof trace utility.
When SQL tracing is on, raw trace files are generated in an Oracle dump directory. The tkprof
utility can use these trace files to create reports on executed SQL statements. Multi-threaded
applications might produce multiple trace files at the same time, and the trace files might get large
quickly, so managing the generated trace files can be challenging.
Other ways to evaluate SQL execution plans include directly using the SQL plan tables, such as V$
SQLAREA, V$SQL_TEXT, and V$SQL_PLAN. If the EXECUTION PLAN has been aged out of V$
SQL_PLAN, use the EXPLAIN PLAN and AUTOTRACE commands.
When tuning SQL statements, getting the runtime execution plan for the SQL statements in
question is important. Oracle supplies a awrsqrpt.sql script, (available in $ORACLE_HOME/
rdbms/admin). This script takes the Start and End AWR Snapshot IDs and the SQL ID of the
statement to be examined as arguments. If a runtime plan is not available, then use the EXPLAIN
PLAN command to get an execution plan for the statement.
When two plans differ in the Cost column, the plan with the lower cost values may not necessarily
be better. The execution for the SQL with the higher cost might be better. To verify this, run the
SQL in a tool, such as SQL*Plus, with timing turned on.
Oracle case study

Issue
A single user submitted a BMC Remedy Incident Management ticket, and it took 18 seconds to
process.
Symptoms
Page 302 of 4705
Home
The database trace accounted for less than 2 seconds of time.

The arserverd process accounted for 2 to 3 seconds of CPU time.
The SQL log from AR System shows SQL time at approximately 1 second.
Diagnostic steps
1. Reduce the number of connections to the database.

2. Measure the CPU time of all the relevant processes on the AR System server and Oracle
database as follows:
a. Bring up the environment (with limited connections from the AR System server to
Oracle).
b. Execute the transaction once to warm up the environment.
c. Start the transaction again up to the point before submission.
d. Record the process status (ps) time for arserverd and Oracle processes.
e. Click SUBMIT.
f. Run the top command and verify which Oracle process is consuming time.
g. Record the process status time for arserverd and Oracle processes.
Observations and analysis
The arserverd took little time. The Oracle process consumed most of the CPU time (close
to 18 seconds).
A combined log for API callsand SQL and filter processing was informative. There was a gap
of 0.8 seconds on every LOB write. If all LOB writes at different places in the log file were
added, the total time accounted for was over 15 seconds.
* Thu Dec 07 2010 08:13:54.2535

* Tue Dec 07 2010 08:13:54.2535
000000000004902' FOR UPDATE
* Tue Dec 07 2010 08:13:54.2536
* Tue Dec 07 2010 08:13:54.2550
* Tue Dec 07 2010 08:13:55.0727
'000000000004902'
* Tue Dec 07 2010 08:13:55.0759
*/OK
*/SELECT C456 FROM T1253 WHERE C1 = '
*/Set LOB into the above row...
*/OK
*/UPDATE T1253 SET C459 = EMPTY_CLOB() WHERE C1 =
*/OK
The Oracle raw trace file showed a similar pattern during the direct write operation.
WAIT #4: nam='SQL*Net message from client' ela= 155 driver id=1650815232 #bytes=1
p3=0 obj#=-1
tim=295710595994
WAIT #9: nam='direct path write' ela= 0 file number=7 first dba=396004 block cnt=
1 obj#=-1
tim=295710596586
WAIT #9: nam='direct path write' ela= 1 file number=7 first dba=396004 block cnt=
1 obj#=-1
tim=295710596738
Page 303 of 4705
Home
WAIT #9: nam='direct path write' ela= 52 file number=7 first dba=396004 block cnt
=1 obj#=-1
tim=295710596787WAIT #0: nam='SQL*Net message to client' ela= 5 driver id=1650815
232 #bytes=1
p3=0 obj#=-1 tim=295711477135
WAIT #0: nam='SQL*Net message from client' ela= 146 driver id=1650815232 #bytes=1
p3=0 obj#=-1
tim=295711477427
STAT #4 id=1 cnt=1 pid=0 pos=1 obj=0 op='FOR UPDATE (cr=6 pr=0 pw=0 time=85 us)'
Oracle Support had a note with a similar issue:

Note 393780.1 Poor Performance Writing Blobs SymptomsA job that is writing BLOBs are
taking long time and consumes a lot of CPUs.
The 'pstack' output of the spinning process shows:
__fdsync ksfdsyncdata kcflsync kcblsy kcblcn kcblrr kcbldrcls kdlpdba ktsplbfmb ktsplbrecl
ktspgsp_cbk1 kdlgsp kdlsfb kdl_write1 kokliccb koklcre kokleva evaopn2 insolev insbrp
insrow insdrv inscovexe insExecStmtExecIniEngine insexe opiexe kpoal8 opiodr ttcpip opitsk
opiino opiodr opidrv sou2o opimai_real main _start
CauseEspecially the __fdsync() system calls indicate that the problem is related to OS.
Technical note from Veritas:
Oracle Import takes longer when using buffered VxFS than using unbuffered VxFS.
Loading data into database using the "import" utility may be slower with buffered VxFS.
Double buffering could be easily avoided by enabling Quick I/O for VERITAS File System (
VxFS).
Quick I/O allows regular files built on VxFS to be accessed as a raw device, bypassing
normal file system buffering and allowing direct I/O. There is no question of double-buffering
when Quick I/O is used.
Recommendation
Use Quick I/O or raw devices.
Tuning an SQL Server database

This topic provides instructions for performing the following Microsoft SQL Server tuning:
Setting the PARAMETERIZATION database option to FORCED
Setting the READ_COMMITTED_SNAPSHOT database option to ON
Setting the SQL Server max degree of parallelism option
Page 304 of 4705
Home
Troubleshooting SQL Server performance
Setting the PARAMETERIZATION database option to FORCED

In SQL Server 2005/2008, forced parameterization promotes the reuse of SQL execution plans,
thereby reducing the time spent parsing SQL queries. The effect is similar to that achieved by
Oracle cursor sharing.
To enable forced parameterization
1. Connect to the SQL server instance as a user with ALTER permission on the database.
2. Assuming that the database name is arsystem, run the following SQL commands:
Alter database arsystem set PARAMETERIZATION FORCED

go
3. To verify the parameterization setting of the database, run the following SQL commands:
select name, is_parameterization_forced

from sys.databases
where name='arsystem'
For more information, see SQL Server 2005 Books Online at http://technet.microsoft.com/
en-us/library/ms175037.aspx.
Setting the READ_COMMITTED_SNAPSHOT database option to ON

Turn on the READ_COMMITTED_SNAPSHOT options for the BMC Remedy AR System database.
Turning on these options enables the row versioning-based isolation level, which provides the
following benefits:
Read operations retrieve a consistent snapshot of the database.
SELECT statements do not lock data during a read operation (readers do not block writers,
and vice versa).
SELECT statements can access the last committed value of the row, while other
transactions update the row without being blocked.
Fewer deadlocks and lock escalations occur.
Fewer locks required by a transaction occur, which reduces the system overhead required to
manage locks.
To turn on the READ_COMMITTED_SNAPSHOT option
1. Connect to the SQL server instance as a user with ALTER permission on the database.
2. Make sure there are no active connections to the database except for the connection
executing the ALTER DATABASE command.
3. Assuming that the database name is arsystem, run the following SQL commands:
Page 305 of 4705
3.
Home
ALTER DATABASE arsystem SET READ_COMMITTED_SNAPSHOT ON

go
4. To get the isolation level of the target database to verify, run the following SQL commands:
select name, is_read_committed_snapshot_on

from sys.databases
where name='arsystem'
go
Note
The database administrator must make sure that tempdb has ample space to
support the version store after enabling row versioning-based isolation levels.
Setting the SQL Server max degree of parallelism option
Note
This section applies only to transaction-oriented systems. Skip this section if your system
is for reporting or is a Decision Support System.
When configuring your SQL Server database server, use the maximum degree of parallelism (
MAXDOP) option to limit the number of processors used in parallel plan execution.
By default, this option is set to 0, which uses all available processors. A single long-running,
CPU-intensive SQL statement could monopolize all processors and create long wait times for other
users.
For SQL Server 2008 R2, SQL Server 2008, and SQL Server 2005 servers, use the following
guidelines:
For servers that have eight or fewer processors, use the following configuration where N
equals the number of processors:
max degree of parallelism = 0 to N
For servers that use more than eight processors, use the following configuration:
max degree of parallelism = 8
Page 306 of 4705
Home
For servers that have hyper-threading enabled, the MAXDOP value should not exceed the
number of physical processors.
For servers that have NUMA configured, the MAXDOP should not exceed the number of
CPUs that are assigned to each NUMA node with the max value capped to 8.
Vary the maximum value depending upon the concurrent activity on the SQL server. For example:
If CPU utilization percentage on the database server is very high (more than 85%), set
MAXDOP to 1 or 2.
If the system has a large number of concurrently executing queries relative to the number of
processors, set MAXDOP to a lower value such as 4.
If the system has small number of concurrently executing queries relative to the number of
processors, set MAXDOP to a higher value, such as 16.
Thoroughly test any value proposed against the system workload, and adjust accordingly if the
system workload changes.
The following example sets the MAXDOP to 8:
sp_configure 'show advanced options', 1;

GO
RECONFIGURE WITH OVERRIDE;
GO
sp_configure 'max degree of parallelism', 8;
GO
RECONFIGURE WITH OVERRIDE;
GO
Troubleshooting SQL Server performance

For general information about troubleshooting performance problems, see http://
www.microsoft.com/technet/prodtechnol/sql/2005/tsprfprb.mspx for SQL Server 2005, and http://
msdn.microsoft.com/en-us/library/dd672789(SQL.100).aspx for SQL Server 2008.
Performance tuning checklists
The following checklists summarize the actions that are needed to improve BMC Remedy AR
System performance:
Creating a problem statement
Tuning the mid tier
Tuning an Oracle database
Tuning an SQL database
Page 307 of 4705
Home
Creating a problem statement

Characterize throughput or response time.
Before problem was observed
After problem was observed
List any system changes that occurred just before the problem was observed.
Patch changes
Configuration changes
Workload changes
User count changes
List observations
Is the entire system slow or is the slow performance specific to particular user,
particular location, or particular transaction only?
For global deployments, is the performance issue related to users accessing the
system over WAN only? Is it related to a specific site?
Is the performance issue intermittent? If so, what is the frequency? When are issues
occurring?

Collect CPU usage data for each computer in the configuration.
Make sure less than 70% of the total CPU capacity is used on each system in the
configuration.
Record which processes are consuming most of the CPU resources.
Record whether I/O wait time is a substantial component of CPU usage. This indicates that
the I/O subsystem is not keeping up with demand.

Make sure that no system in the configuration is running out of physical memory and doing
swapping.
Be aware of 64-bit and 32-bit limitations on the OS and applications.
Track memory growth over time to identify any memory leaks.
Tuning the mid tier

This section provides information and guidelines for tuning the mid tier.

Turn on HTTP keep-alive for all network segments in your network infrastructure.
If your HTTP keep-alive service supports the following optional HTTP keep-alive parameters,
use the following values:
Keep-alive count: Infinite (minimum 5000)
Page 308 of 4705
Home
Connection timeout: 90000 ms (minimum 60000 ms)

If HTTP session affinity is necessary, set up load balancing for the web tier by using cookie
insert rather than source IP binding.
If deployment is over HTTPS, off-load SSL handling to a hardware load balancer when
possible.
If deployment is over HTTPS, secure only the necessary network segments because
additional encryption and decryption takes time and resources.

Set the host JVM PermSize as follows:
-XX:PermSize=256m
If you have more custom Data Visualization Modules, you might need to increase this item.
Monitor the JVM for the correct size.
Select your Garbage Collection (GC) according to the following table but monitor, compare,
and confirm that the selection is best because GC behaves differently for different hardware
and heap size.
Low-pause
Throughput
1 CPU
2+ CPU
1 CPU
2+ CPU
Copying Collector (
default)
Parallel Copying
Collector
-XX:+UseParNewGC
Copying Collector (
default)
Parallel Scavenge
Collector
-XX:UseParallelGC
Old generation
Mark-Compact
Collector (default)
Concurrent Collector
-XX:+
UseConcMarkSweepGC
Mark-Compact
Collector (default)
Mark-Compact
Collector (default)
Permanent
generation
GC not configurable but can be turned off via JVM arg -Xnoclassgc
Young
generation
Activate the 64-bit JVM hybrid mode:

If you run into JVM stability issues, see JVM heap size setting.
Set the host JVM heap size:
-Ms2048m -Mx2048m
Configure your Tomcat connector as follows (for standard port 80):
<Connector URIEncoding="UTF-8" acceptCount="100" connectionTimeout="
60000"maxHttpHeaderSize="8192" maxKeepAliveRequests="5000"
maxThreads="600" port="80" protocol="HTTP/1.1" redirectPort="8443"/>

To fine tune the mid tier web application, set the values as described in the following table.
Mid tier parameter or service
Recommended value
For a production environment, this parameter is always set to on.
Page 309 of 4705
Home
Mid tier parameter or service
Recommended value
Enable Cache Persistence (mid tier cache

serialization)
Prefetch or preload service
Use prefetch only when a specific set of AR System forms are known. BMC
recommends using preload.
Recommended preload procedure

1. Turn on Enable Cache Persistence.
2. Turn on preload.
3. Allow preload to finish preloading all user-facing AR System forms.
4. Turn off preload (allowing statistical service to take over).
arsystem.formhtmljs_expiry_interval
arsystem.resource_expiry_interval
Set both parameters to the same value to reflect how often you want the
browser to check with the mid tier for updates.
BMC recommends setting these to 84600 (1 day). However, if your deployment
environment is not changed, you can set the value higher, such as 604800 (1
week). For the new values to take effect, restart the mid tier.
Definition Change Check Interval
In a production environment, turn this parameter off and use manual

synchronization when your changes are applied to the AR System server.
arsystem.log_category
arsystem.log_level
These settings can also be applied by using the Mid Tier Configuration Tool.
Configure by using the Mid Tier Configuration Tool to avoid having to restart the
mid tier. The changes take effect you click Save. For more information, see
Configuring the mid tier connection pool.
Maximum Connections per Server Set to one-third the anticipated
number of maximum concurrent users.
Idle Connections per Server Use the default value of 5 unless your
need is different.
Connection Timeout Set to slightly less than the TCP idle time for
your load balancer (depending on the network latency between the mid
tier and the AR System server). If no load balancer is used, use the
default value.
Connection Lifespan Enable and set the value to 15 minutes. If you
do not have a load balancer, you can use this setting to prevent stale
connections.

Make sure that client hardware meets the following minimum recommendation: duo core
CPU with 4 GB RAM.
If Internet Explorer 6 or later is used, make sure the browser observes the cache directives.

Allocate AR System server resources.
Page 310 of 4705
Home
Create a dedicated integration server and move resource-intensive batch or

background processes to this server.
Set fast threads to 3 times the number of CPU cores, and set list threads set to 5
times the number of CPU cores. Fine tune later if needed.
Use OS tools such as Performance Monitor (Microsoft Windows) to monitor the server.
Because of the heavy memory usage of a CopyCache operation, manage administrative
changes through user behavior and correct configuration:
Perform administrative changes during nonpeak hours.
Set the Max-Num-Caches option in the ar.cfg (ar.conf) file to manually set a limit to
the number of cache copies that can exist at one time.
Set the Delay-Recache-Time option in the ar.cfg (ar.conf) file to the number of
seconds to wait before the server makes the latest cache available to all threads. The
recommended value is 300 (5 minutes).
Set the Max-Entries-Per-Query option to no more than 2000 entries.
Design efficient queries.
For Oracle Solaris, use libumem for memory management.
Increase the number of threads in the queue until your API log consistently shows thread
wait times of 0.
To limit the number of AR System server threads, assign a Private-RPC-Socket (private
queue) and set the appropriate minimum and maximum threads.
For any component that runs as a C plug-in, consider the number of fast, list, escalation,
private threads that are likely to communicate simultaneously with the particular type of
plug-in (AREA, ARDBC, Filter API) and set the appropriate option in the ar.cfg (ar.conf) file
(Plugin-AREA-Threads, Plugin-ARDBC-Threads, and Plugin-Filter-API-Threads).
Set the <numCoreThreads> value in the pluginsvr_config.xml file to the value that
provides maximum performance without consuming too many resources.
For BMC Atrium CMDB, set up a private queue with minimum and maximum thread settings
of 2 and 2 as the starting values. Adjust the thread settings based on the BMC Atrium CMDB
workload and thorough performance testing.
For the Full Text Search (FTS) private queue, adjust the default thread setting of 1 upward if
there is a backlog of entries to be indexed.
To adjust the number of sender threads, edit the following options in the
EmailDaemon.properties file as needed:
com.bmc.arsys.emaildaemon.NumberOfSenderThreads=<number>
com.bmc.arsys.emaildaemon.MailboxPollingUnitIsMinutes=false
Set the following AR System configuration parameters:
Parameter
Recommended value
Private-RPC-Socket (Fast:390620)
3 times the number of CPUs
Private-RPC-Socket (List:390635)
5 times the number of CPUs
Next-ID-Block-Size
100
Page 311 of 4705
Home
Parameter
Recommended value
1000
F (disallow)
Cache-Mode
0 (development mode off)
Debug-mode
0 (all logging off for a production environment)
Minimum-API-Version
Set to a value appropriate for your production environment
CMDB-Cache-Refresh-Interval
600 (10 minutes)
For more information on Tuning the AR System server, see the blog AR Server shared on BMC
Communities.
Tuning an Oracle database

When tuning an AR System Oracle database server, do the following:
Make sure that alert.log file is clean.
Use an appropriately sized System Global Area (SGA).
Set cursor_sharingto FORCE.
Use Automatic Workload Repository (AWR) reports to collect diagnostics data.
Review the top-timed events for potential bottlenecks.
Monitor the database for the top SQL statement. You can use an AWR report for this
purpose. Make sure that the SQL execution plans are optimal.
If high database space growth is a concern, convert CLOB storage to In Row.
If you need to make the Oracle database case-insensitive, set the NLS_COMP and
NLS_SORT parameters in Oracle 10g.
For expensive SQL statements:
Make sure that the database statistics are current and representative of the data
volume and data distribution.
Review the execution plan and look for common red flags such as Merge Join
Cartesian operation, full table scans, index full scan, bitmap from/to conversion, and
so on.
Implement additional indexes if appropriate. BMC provides indexes out of the box.
However, there might be cases where additional indexes are required based on the
way the application is configured and used. Typically these requirements are
documented in product manuals.
Tuning an SQL database

Set PARAMETERIZATION option to FORCED for the AR System database.
Set the READ_COMMITTED_SNAPSHOT database option to ON for the AR System
database.
Set the SQL Server MAXDOP option to the appropriate value.
Page 312 of 4705
Home
BSM case study

This topic details Business Service Management (BSM) case study for a load test of 300
concurrent users that was conducted by the BMC R&D Performance Team. This load test was
conducted on the full set of BMC Remedy IT Service Management 8.0 applications deployed on the
BMC Remedy AR System 8.0 platform.
Background information
Virtualized hardware
Test configuration
Plug-in settings on AR System server
Network latency detail
Pacing Information
CPU utilization
Memory utilization
Mid tier JVM utilization
Background information
All users were simulated web users.
The simulation tool was Silk Performer.
All use cases were executed over full HTTPS with F5 handling the SSL from the browsers
and Tomcat 6.0.20 handling the SSL from the F5 load balancer.
Note
This load test is more work on the Java Virtual Machine (JVM) than the standard
off-loading of SSL handling to F5 and communication from F5 to the Tomcat is in plain
HTTP.
Virtualized hardware
The virtual machines (VMs) were hosted on Intel Xeon X6550 at 2 GHz hardware with the Microsoft
Windows Server 2008SP2 OS.
The mid tier had 2 CPU and 8 GB RAM.
The AR System server had 2 CPU and 8 GB RAM.
Test configuration
The database was loaded with over 10,000 configuration items (CIs) to start.
300 users ITSM/SRM/RKM+SLM+ email
Simulated Browser Latency: 300ms
Included 1 software licensing jobs (CMDB checking software licenses on all the CIs)
Page 313 of 4705
Home
Atrium load: 7,500 CI+ Relationship (90% update to existing CIs, 10% new CIs)
Fast thread on AR System server set to: 8/12
List Thread on AR System server set to: 8/12
AR-plug-in JVM set to: 64-bit,heap size (512 MB Max)
(Full text search) FTS-plug-in JVM: 64-bit,heap size (3072 MB Max)
NE-plug-in JVM set to 64-bit,heap size (512 MB Max)
CMDB shared plug-in JVM: 64-bit, heap size (512 MB Max)
AE plug-in JVM: 64-bit ,heap size (256 MB Max)
MT server Min heap: 2 GB Min and 2 GB Max
SQL server Recovery mode set: Full
NE/RE/AR private queue values: 2/2 (min/max)
NE/RE Jobs Type: Continuous
Plug-in settings on AR System server

FTS plug-in: NumcoreThread:10, selector:2, Maxthread:10
NE plug-in: NumcoreThread:5, selector:2, Maxthread:5
CMDB plug-in: NumcoreThread:5, selector:2, Maxthread:5
AR plug-in: NumcoreThread:30, selector:5, Maxthread:30
Network latency detail

Network latency from the Silk Performer computer to the mid tier computer:
Network latency (from client to the mid tier)
Test: Under 300ms

latency
TCP PING
300
HTTP PING
1452
HTTP PING redirect
3691
Pacing Information
As an example for interpreting the following table, row 1 says 30 users are randomly logging in and
out, each randomly creating tickets for a total of six tickets for the test duration. The objective is to
model an actual workload.
Page 314 of 4705
Home
CPU utilization
The following table shows CPU utilization measured by using perfmon.
Page 315 of 4705
Home
Memory utilization
The following table shows memory utilization measured by using perfmon.
Page 316 of 4705
Home
Mid tier JVM utilization
Performance tuning
Various AR System server settings help the server operate in a robust and efficient way, while
maximizing the security of the system. The following topics provide information about performance
tuning:
Gathering baseline information
Page 317 of 4705
Home
BMC Remedy AR System debugging tools
Gathering baseline information

Baseline data gathered under normal operating conditions can be useful for objectively identifying
performance issues and providing quantitative evidence of change over time. With baseline data,
you can determine whether your performance tuning efforts are successful, and identify behavior
that is unusual for your system.
You can design baseline tests to run at regular intervals. If a repeatable test fails at an testing
interval, you can use this information to help determine if there is a issue.
Before gathering baseline information, create an analysis of your system components. As you tune
your system, you can record the changes you make to the configuration, and note the effects of
these changes. To create your analysis, answer the following questions:
What is your hardware configuration?
What is the server platform configuration?
How much RAM is installed?
What is virtual memory?
What is the system processor configuration?
What is the disk subsystem configuration?
What is your BMC Remedy AR System configuration?
How many AR System servers and web clients are part of your system?
Do your client tools run remotely?
What are the minimum and maximum threads for configured queues (fast, list, private)
?
How much physical and virtual memory is available for the BMC Remedy AR System
server?
What is your database configuration?
Is it local or remote?
What type and quantity of data spaces and devices exist?
How much memory is allocated in the database?
What non-BMC Remedy AR System applications are running on the client or server? When
do they run?
What diagnostic operations (disk defragmentation, and so on) are running on the server? On
the client?
After you have created a system analysis, you can determine how efficient the system is through
specific measurements and through user perceptions.
Users typically measure BMC Remedy AR System performance by the response time of individual
operations, such as logging in to the server and searching for data in the database. Response time
is the number of seconds it takes for these operations to complete; for example, the amount of time
it takes for the results to be displayed after a user initiates a search. Users might alert you when
Page 318 of 4705
Home
they think that performance issues exist.

Measurements can be obtained through various methods, including gathering server statistics.
Server Statistics form for baseline data

You can use the Server Statistics form to gather statistical information about the performance and
operation of your server. This form is automatically installed when you install BMC Remedy AR
System. The form gathers statistics about the time spent in various types of calls and the number of
operations being performed in the system. In addition, it contains information about the number of
current users and the number of bad password login attempts.
Server Statistics form (top 1/3 of screen)
When activated, the BMC Remedy AR System server creates an entry that contains the current
value of all the server statistics at an interval you specify. The statistics can be gathered at the
server level (summarized across all queues) or at a per-queue level. The fields in the Server
Statistics form record the same information that the ARGetServerStatistics function records.
For a complete list of the options and their descriptions, see the ARGetServerStatistics function.
BMC Remedy AR System debugging tools

BMC Remedy AR System provides a variety of log files as a resource for gathering different types
of data. Log files contain information that you can use to evaluate performance. Some log files are
generated automatically, while others must be enabled before they begin to log operations. The API
, SQL, and filter logs are particularly useful for monitoring performance.
Warning
Running a log file requires a portion of your system resources, thereby affecting
performance. Do not leave a log file running at all times. To check actions that might be
causing performance issues, enable a log file, perform the suspected actions, and then
turn off the log file. This generates a short log file of only the actions performed for the
logged operation.
Page 319 of 4705
Home
The following topics provide detailed information about the various debugging tools for BMC
Remedy AR System:
Server statistics for baseline data
Configuring application and form statistics logging
Excluding forms from application statistics logging
Server statistics for baseline data

You can use the Server Statistics form to gather statistical information about the performance and
operation of your server. This form is automatically installed when you install BMC Remedy AR
System. The form gathers statistics about the time spent in various types of calls and the number of
operations being performed in the system. In addition, it contains information about the number of
current users and the number of bad password login attempts.
Server Statistics form (top 1/3 of screen)
When activated, the AR System server creates an entry that contains the current value of all the
server statistics at an interval you specify. The statistics can be gathered at the server level (
summarized across all queues) or at a per-queue level. The fields in the Server Statistics form
record the same information that the ARGetServerStatistics function records.
Note
There is no performance issue even if the server statistics collection is enabled for
long periods of time.
For server statistics, log entries are created only when an API call is made.
To record server statistics for baseline data
Page 320 of 4705
Home
1. Update the Server Statistics settings on Advanced tab of the AR System Administration:
Server Information form. (See Setting performance and security options.)
Note
You can also record statistics by updating the Server-Stats-Rec-Mode and
Server-Stats-Rec-Interval options of the ar.conf (ar.cfg) file.
2. To view the statistics, open the Server Statistics form in Search mode, specify the criteria for
the recording you want, and click the Search button.
For a complete list of the fields, options and their descriptions, see the
ARGetServerStatistics function.
Related topic
ARGetServerStatistics
Configuring application and form statistics logging
Use application and form statistics logging to monitor the performance of the applications and forms
on your BMC Remedy AR System server as follows:
Application statistics logging Logs a summation of entry, filter, and escalation statistics
for all forms in an application. Also logs application licensing statistics.
You can specify forms to exclude. See Excluding forms from application statistics logging.
Note
Application statistics logging is supported only for deployable applications, not for
local applications.
Form statistics logging Logs entry, filter, and escalation statistics for an individual form.
To view application and form statistics, open the Application Statistics form in Search mode,
specify the appropriate search criteria, and click Search.
Application Statistics form
Page 321 of 4705
Home
If statistics logging is enabled for an application or form, a new entry for that application or form is
added to the Application Statistics form at the end of each logging interval. For example, if logging
is enabled for Application A at 20-second intervals and for Application B at 30-second intervals, five
entries are written to this form every 60 seconds--three for Application A, and two for Application B.
Each entry contains the following information for one interval:
Entry Statistics Shows the number of create, delete, get, get list, merge, and set entries;
their total processing time (in seconds); and the number of entry-related operations.
Filter Statistics Shows general filter statistics (including number of skipped filters, total
filter processing time, and total number of filter actions), number of executed Set Fields
actions (including filter API, $PROCESS$, and SQL), and number of other executed actions.
Escalation Statistics Shows general escalation statistics (including number of skipped
escalations, total escalation processing time, and total number of escalation actions),
number of escalated Set Fields actions (including filter API, $PROCESS$, and SQL), and
number of other escalated actions.
License Statistics Shows number of fixed and floating licenses consumed and number
of floating licenses denied for an application.
Because the data for application and form statistics is written to a form, you can create flashboards
that provide graphical representations of the data. This enables application performance to be
monitored and analyzed in real-time and in a user-friendly method. See Creating and managing
flashboards.
To activate or inactivate application or form statistics logging, follow this procedure.
To activate or inactivate application and form statistics logging

1. In a browser, open the Application Statistics Configuration form in one of these modes:
New Use this mode the first time that you configure statistics logging for an
application or a form.
Search Use this mode to modify an existing configuration.
Application Statistics Configuration form (New mode)
Page 322 of 4705
Home
2. If you opened the form in Search mode, find the record to modify by entering the appropriate
search criteria and clicking Search.
3. In the Logging Status list, select a status:
Enabled Activates statistics logging.
Disabled Inactivates statistics logging.
Alternatively, you can inactivate logging by deleting the record from the form.
4. In the Logging Type list, select the appropriate type:
Application Logs statistics for multiple forms and for application licensing.
Form Logs statistics for one form.
5. In the Name field, enter the name of the application or form to monitor.
To ensure that the name is correct, copy it from the application or form object in BMC
6. In the Logging Interval field, enter the interval (in seconds) at which statistics for the
application or form are logged to the Application Statistics form.
7. Click OK.
Excluding forms from application statistics logging

By default, all forms in an application are included in application statistics logging. You can,
however, exclude any form in the application. If you exclude all the forms in the application, only
application licensing statistics are logged.
To exclude forms from application statistics logging

1. In BMC Remedy Developer Studio, log on to the appropriate server.
2. In BMC Remedy AR System Navigator, expand Applications.
3. Right-click the appropriate application, and select Edit Application.
4. In the Application editor, expand the Statistics panel.
5. In the Forms for Application Statistics table, select the forms to exclude.
6. Click Remove.
7. Save the application.
For more information about creating and modifying applications, see Defining and managing an
application.
Tuning search performance

Searches are the most database resource-intensive BMC Remedy AR System transactions against
a database, and most BMC Remedy AR System operations are designed around searches.
Therefore, optimizing search performance should be a primary goal.
Page 323 of 4705
Home
Examples of BMC Remedy AR System operations that involve searches are escalation
qualifications, Set Fields actions, Push Fields actions, search menus, and table fields. The most
efficient searches are often those that use an index, because indexes are designed to reduce the
number of physical disk accesses of the DBMS. However, indexes might not be appropriate for all
types of searches.
To optimize performance, define effective search criteria that will result in the use of an index. Add
indexing to support common repeated searches.
To increase the search performance, you can:
Creating effective indexes
Avoiding unqualified searches
Creating effective indexes

Failing to use indexes effectively is a major cause of performance issues in BMC Remedy AR
System applications. The goal of indexing is to minimize search response time by reducing the
number of physical disk accesses of the DBMS. To achieve this goal, you must identify and index
frequently searched fields in your workflow.
Creating an index does not guarantee its use. When a search is performed, the query optimizer
does not automatically use an index. The optimizer chooses whether to use an index and which
index to use. If an index is not used, the database server must scan every data page in the table.
Table scans can take several minutes to process on large tables. If table scans occur frequently,
application performance will suffer.
Create indexes that the DBMS will recognize and use consistently as the best choice for retrieving
the requested information. In other words, you should index the most useful fields on a form, and
make sure that the search criteria promotes the use of indexes. Work closely with your database
administrator to keep the database tuned so that the optimizer uses an effective index whenever
possible.
Indexing specific fields

Consider using indexes for frequently searched fields, such as those that store names, employee
numbers, and categories. You might also consider indexing the following fields:
Fields used in a search qualification
For example, a user presses Return in the Last Name field, which starts a Set Fields action
that searches for more information based on that field.
Fields used in search menus
Fields used in the qualifications of Set Field, Push Field, and Open Window active links
Fields that are frequently searched (log files can help determine these fields)
Page 324 of 4705
Home
Fields that are selective

Selectivity indicates how many entries are returned for a given search. Generally, a search
that returns less than 5 percent of the total data in the form is considered to be selective.
Note
The indexing of a currency field has special considerations. Because a currency field is
represented by multiple columns in the main data table, multiple columns will be indexed.
Standard queries against a currency field will potentially use any of several different
columns, depending on the currency type specified. To provide comprehensive coverage,
indexing a currency field defines an index for the value column, the type column, and for
each functional currency column. This can produce significant overhead for the main data
table. Therefore, carefully consider indexing a currency field before doing so. For more
information about currency fields, see Currency fields.
You can use SQL logging to help you determine which fields to index. Review SQL logging
generated during the time that performance issues are reported. Find the SELECT statements
associated with searches that are reported as having poor performance. Work with your database
administrator to review these SELECT statements and determine if additional indexing is needed.
The improvement might not be adding more indexing but modifying the qualification, so existing
indexes can be utilized by the database optimizer.
Limiting the number of indexes

You can create multiple indexes for a form; however, too many indexes can slow your system. Add
an index only if there is a common and repeated search that will benefit from its being created. The
balance is in having enough indexes to optimize search operations but not so many that overall
database performance is affected. Your database administrator can provide direction to help
determine whether an additional index can be supported by the database. For more information
about indexing, see Defining indexes.
Avoiding unqualified searches

Avoid unqualified searches in your workflow. For example, an active link that performs a Set Fields
action, based on the contents of a field, should include a qualification that the field must have a
value:
Run If:*'Status' = 'Assigned'*

If Action: Set Fields.
Else Action: Then send a message to the user.
You can also require users to better qualify their searches by disallowing unqualified searches (see
the following procedure) and limiting the number of requests that can be returned by a search.
Page 325 of 4705
Home
To disallow unqualified searches

1. From the BMC Remedy AR System Administration Console, select General > Server
Information.
2. In the Server Information form, click the Configuration tab.
3. Verify that Allow Unqualified Searches is not selected.
4. Click OK.
The following sections provide detailed information about how to avoid unqualified searches:
Using a Run If qualification
Avoiding NOT operators
Placing search terms in proper order
Setting QBE Match to Equal or Leading
Designing search and SQL menus
Using FTS
Using a Run If qualification

For an active link, escalation, or filter that performs a Set Fields action based on the contents of a
field, include a Run If qualification that the specified field cannot be empty. Creating an index for the
specified field can improve search performance.
Avoiding NOT operators

Indexes are not used for NOT operations (for example, 'Status' != "Closed" ). Therefore, if NOT is
the only operation used, the entire database table is searched. If NOT is used in a search, use
additional criteria in the qualification to make sure that the index is used.
Placing search terms in proper order

For searches that reference indexed fields, isolate the indexed field name on one side of the
operator. If the field name is not isolated, the search does a table scan instead of using the index.
Example
Suppose the Create Date field is indexed. In this case, the search string 'Create Date' < $
TIMESTAMP$ - 60*60*8 performs an index search because the field name is isolated on one
side of the less-than (< ) operator. However, the search string $TIMESTAMP$ - 'Create Date'
> 60*60*8 performs a table scan because the indexed field name is not isolated.
A search that begins with a wildcard, such as %, does not use an index because the index is
ordered by the leading characters of the index key values. This means that the entire database
must be searched for matching entries. In other words, search for e%ample, not %mple.
The following table summarizes these concepts. The examples assume that there is an index on
Page 326 of 4705
Home
the referenced field.

Examples of efficient and inefficient searches
Indexed field
Efficient search (index considered)
Inefficient search (index NOT considered)
Submitter
'Submitter' LIKE "Jackson%"
'Submitter' LIKE "%Jackson%"
Status
'Status' < "Closed"
'Status' != "Closed"
Create Date
'Create Date' < $TIMESTAMP$ - 60*60*24
$TIMESTAMP$ - 'Create Date' > 60*60*24
Setting QBE Match to Equal or Leading

Query-by-Example (QBE) searches configured for Anywhere, do not limit users, but they put the
most strain on the database. Use BMC Remedy Developer Studio to change the QBE Match
setting for fields to Equal or Leading.
The default setting is Anywhere for both the Match preference in BMC Remedy Developer Studio
and the QBE Match property of character fields. When a user searches BMC Remedy Action
Request System with the Anywhere setting, the search returns requests with field values matching
any part of the criteria specified in a field.
Example
An Anywhere search for requests that match the word turn returns all the requests containing
any part of the word turn , such as right turn , left turn , turned , return , turned left , and user
returned . These searches consume system resources.
To improve performance, change the default QBE Match preference in BMC Remedy Developer
Studio and the QBE Match setting of character fields to Equal or Leading. While more restrictive
to your users, these searches are more efficient than Anywhere searches.
Designing search and SQL menus

To speed system performance, design your menus to search indexed fields. Use equal or leading
qualifications for your search menus, and design the menus to return the fewest possible values.
When you use search menus, select Refresh On Connect whenever possible. The On Connect
setting causes the menu to refresh only when you opens the menu the first time after opening the
form.
When you have a search menu that depends on a field value in a form, you must set the menu to
Refresh On Open. This setting causes the menu to be updated every time the menu is used.
Page 327 of 4705
Home
Warning
Frequent menu retrievals can slow performance. Select Refresh On Open only when
absolutely necessary.
With SQL menus, which allow any valid SQL statement to be run, use an efficient SQL statement.
Example
Rather than using select statements, specify the two columns to be used as the value and
label, and use an indexed field to qualify the query if there are many records in the table.
Using FTS
You can use the Full Text Search (FTS) option to expedite searches on diary, long character, and
attachment fields. See Enabling full text search. BMC recommends that you perform bulk indexing
during off-peak hours, such as during a maintenance window.
Tuning DSO performance

The following topics provide information about how to tune the BMC Remedy Distributed Server
Option (DSO) performance:
Setting a polling interval for the DSO server
Setting a custom backup polling interval

By default, the BMC Remedy Distributed Server Option server is a nonpolling server: it queries the
distributed pending queue in real time whenever a request is submitted to the queue. If the request
is associated with a nonpolling distributed pool (see Setting polling intervals for distributed pools ),
the server immediately notifies the pool.
Depending on your environment, this might affect the performance of the BMC Remedy Distributed
Server Option server by overloading it with unnecessary operations. For example, if 1000 requests
from the same form are submitted to the queue within five seconds, the BMC Remedy Distributed
Server Option server performs 1000 consecutive query-and-notify operations during that time
period.
To enhance the performance of the BMC Remedy Distributed Server Option server in such
environments, you can make it a polling server. Polling servers query the distributed pending queue
only at specified intervals. They do not receive real-time signals from workflow.
Page 328 of 4705
Home
Example
Suppose a server is configured to query the queue every 30 seconds. If 1000 requests from a
form are submitted to the queue within 5 seconds, the server handles all of them by performing
at most two query-and-notify operations (one operation if it polls after all requests are
submitted and two operations if it polls during the five-second period).
To set a polling interval for the BMC Remedy Distributed Server Option server
1. Open the BMC Remedy AR System Administration: Server Information form for the local
BMC Remedy AR System server.
2. Click the DSO tab.
3. In the Polling Interval field, enter a polling interval from 0 seconds (no polling) to 3600
seconds (1 hour).
The corresponding entry in the BMC Remedy AR System server configuration file is
DSO-Main-Thread-Polling-Interval.
4. Click Apply and OK.
The interval takes effect immediately. You do not need to restart the BMC Remedy AR
System server.
Setting a custom backup polling interval

By default, a nonpolling BMC Remedy Distributed Server Option server automatically checks the
distributed pending queue at two minutes after every hour (11:02 p.m., 12:02 p.m., 1:02 p.m., and
so on). This safeguard ensures that the BMC Remedy Distributed Server Option server continues
processing pending operations if an issue causes it to receive no workflow signals.
The following procedure explains how to set a custom backup polling interval. The custom interval
overrides the default backup interval.
Note
Unless an issue occurs, the BMC Remedy Distributed Server Option server continues to
receive real-time signals from workflow when backup polling is in effect. Specifying a
custom backup polling interval does not make the BMC Remedy Distributed Server Option
server a polling server.
To set a custom backup polling interval for the BMC Remedy Distributed Server Option server
1. Open the AR System Administration: Server Information form for the local BMC Remedy AR
System server.
3.
Page 329 of 4705
Home
3. In the Backup Polling Interval field, enter a polling interval from 15 seconds to 7200
seconds (2 hours).
DSO-Polling-Interval.
The interval takes effect immediately. You do not need to restart the BMC Remedy AR
System server.
Tuning performance for Approval Server

Application administrators configure forms, processes, and rules when setting up an integration with
Approval Server using the AP:Administration form. The Definition Check Interval field enables the
Approval administrator to define after which interval the Approval Server engine should re-cache
the forms, processes, and rules. This depends on how often the administrator estimates that
changes to the base configuration will be made. The Approval Server engine honors this setting by
visiting the configured forms at the scheduled interval to check whether a re-cache is required. This
check expedites API calls, which can affect performance. In production, the changes to
configuration are generally minimal, so you should coordinate this with the frequency of
configuration changes made in the environment.
For more information, see To configure the server settings on the Basic tab .
The following settings help in improving the performance of Approval Server.
What you can do...
How to do...
Private AR server RPC

socket
See step 7 in the To configure the server settings on the Basic tab .
In case you have also installed the ITSM applications, defining a private AR Server RPC socket
for approval is advisable.
Plug-in loopback RPC socket
See step 8 in the To configure the server settings on the Basic tab.
Note: Because Approval Server shares this queue with other plug-in applications but not with AR
System users, the usage of Private AR Server RPC socket should supersede usage of Plug-in
loopback socket.
Configuring business times
For information about configuring business calendars for Approval Server, see the Configuring
business times.
Configuring previews
See the Configuring previews.
Configuring the approval

server to work with flowcharts
See Configuring the approval server to work with flowcharts.
Approval rules
See the Approval Server rules.
Setup notifications
See the Adding notifications to the approval process.
Housekeeping atop AP:Detail

and AP:Signature (Approval
forms)
Manage the entries on approval forms regularly, such as once a month.
Page 330 of 4705
Home
Tuning the BMC Atrium CMDB performance

For optimal search and reconciliation performance, index CMDB classes on the attributes that are
used to identify the classes. Add these class indexes using the CMDB Class Manager and not the
underlying BMC Remedy AR System forms.
Performance of BMC Atrium CMDB operations, such as import and reconciliation, can vary greatly
from one platform to another. It is best practice to test the performance and load on systems with a
hardware and software configuration that is as close to the live environment as possible, before
going live with a new CMDB implementation.
In order to improve the performance of data load in AIE, set the following parameters:
Create Index on Class (BMC_BaseElement) for keys which are used as Primary Key
mapping.
Use number of threads in AIE under Advance Setting tab of Data Exchange as 3 times the
number of CPUs.
Database should be properly tuned:
Create a separate disk for log and data
Cursor sharing is done at database level
Move index and lob into separate tablespace
Following Query would be helpful on Oracle database
execute dbms_stats.gather_database_stats (estimate_percent=>10,
cascade=>TRUE);
Related topics
Performance Tuning for Business Service Management white paper.
Performance and Scalability of BMC Remedy ITSM Suite 7.5.01 and BMC Atrium CMDB
7.5.00 Patch 1 on Solaris 10 Conducted at the Sun Solution Center white paper.
Tuning FTS for performance and stability in a server group

You can obtain a considerable increase in performance, reliability, and FTS system stability by
using the preferred method of configuring BMC Remedy Full Text Search (FTS) in a server group
instead of the previous deprecated method explained in Configuring full text search for a server
group. This method is applicable from BMC Remedy AR System 7.6.04 versions and later.
In the previous deprecated method for configuring FTS for a server group , each instance of the
FTS plug-in resides locally on its instance of the BMC Remedy Action Request (AR) System server.
They all point to a central network location at which the index resides. All instances of the FTS
plug-in must communicate with the index files over the network, which creates a performance
bottleneck.
Page 331 of 4705
Home
The AR System server can communicate with an AR System plug-in located in any location on the
network. They need not be local to one another. To communicate, the AR System server makes
remote procedure calls (RPCs) to the configured plug-in server.
However, you can greatly increase performance by placing all instances of the FTS plug-in and the
index files local to each other. In this arrangement, the index-intensive activity happens locally
instead of over a network. Each AR System server then makes an RPC call to the appropriate FTS
plug-in over the network, which is much less intensive and does not depend on disk activity.
If the AR System server or the Primary FT Indexer server goes down, the entire FTS goes down.
The Readers cannot search the data directly, due to file system unavailability.
Use the following configuration to achieve optimal performance and stability.
Configuring FTS in a server group for performance and reliability
Note
Perform the following steps to configure your BMC Remedy AR System 8.0.00 or previous
configurations to upgrade to use the two FTS plug-ins configuration.
To configure FTS in a server group for performance and reliability, use two instances of the FTS
plug-in on the FT Indexer server (Primary) in the server group, and place the FTS index on the FT
Indexer server's local drive. Designate the two plug-in instances as primary (Writer) and secondary
(Reader). The writer instance is connected to the Primary FT Indexer server whereas the reader
instance runs on the Primary FT Indexer server but on a separate port. All servers except the
Primary FT Indexer server should connect to this instance. The Primary FT Indexer server should
connect to the Primary/Writer instance of the FTS plug-in alone.
To convert an old FTS configuration to use the two-plug-in configuration
Note
Perform these steps after the servers are shut down or according to the change controls
implemented in your environment.
1. Select a server to be designated as a primary FTS server and ensure that:

The Collection directory is available on a local drive on this server.
Both instances of the FTS plug-in are running on this server.
2. Configure the port numbers for the two plug-in instances.
For the primary plug-in instance, assign 9998, and for the secondary instance, assign 9988.
3.
Page 332 of 4705
Home
3. Ensure that the Conf and FTSCollection directories are on the local drive and that they
have sufficient disk space, approximately six times more than their existing size.
4. Ensure that the system has sufficient memory to run all the FTS plug-ins, approximately 2.5
GB to 3 GB per instance.
5. Prepare the new FTS plug-in instance directories on the designated primary FTS server.
The FTS plug-in server is located in the .../pluginsvr/fts directory. Create the following
subdirectories under the ftsdirectory:
../fts/core
../fts/primary
../fts/secondary
a. Copy the two JAR files (ftspluginVerNum.jar and tika-app-0.6.jar) located in the fts
directory to the new core directory. (VerNum represents the release version number.)
b. Copy the two XML files (pluginsvr_config.xml and log4j_pluginsvr.xml) located in
the fts directory to the new primary and secondary directories.
c. Edit the ../primary/pluginsvr_config.xml and ../secondary/pluginsvr_config.xml
files to ensure that the paths reflect the new locations of the JAR files, the collection
and conf directories, and the stop file ( arsfts.stp).
Note
Ensure that the stop file exists in the ftsconfiguration/conf directory. The
stop file is a list of words that are ignored by full text search and is
configurable.
d. Edit the port number in the ../secondary/pluginsvr_config.xml file and assign 9988
as the port number.
e. If threads for the FTS plug-in server are modified from the default settings, revert the
number of threads to their out-of-the-box default values in both primary and
secondary pluginsvr_config.xml files. (By default, 5 core threads and 2 selector
threads are available.)
f. Edit both the ../primary/log4j_pluginsvr.xml and ../secondary/log4j_pluginsvr.xml
files to append -primary and -secondary to the output files names. For example:
<appender name="PluginLog">
<param name="File" value="C:/Program Files/BMC Software/ARSystem/ARServer
/Db/arftsplugin-primary.log"/>
<appender name="FTSLog">
<param name="File" value="C:/Program Files/BMC Software/ARSystem/ARServer
/Db/arfts-primary.log"/>
6.
Page 333 of 4705
Home
6. Edit the Full Text Indexer rankings in the Server Group Operation Ranking form to rank only
the selected primary FTS Server for FTS. For more information, see Setting failover rankings
for servers and operations.
7. If you did not shut down the AR System servers at the beginning of this procedure, all the
AR System servers must be shut down now.
8. If the Collection and conf directories are not local to the primary FTS server, copy these
files to the primary FTS server.
If you are planning for a re-index, you can skip this step.
9. On the primary AR System server, edit the ar.conf/ar.cfgfile as follows:
a. Change the paths of the Full-Text-Configuration-Directory and
Full-Text-Collection-Directory settings to reflect the correct paths.
b. Ensure that no entry exists for the Private-RPC-Socket: 390602 setting or that it is
commented out.
10. On each AR System server except the designated FTS Indexing server, perform the
following steps:
a. Comment out the entry of the armonitor.conf/armonitor.cfg line that starts the FTS
plug-in locally.
b. Edit the plug-in alias in the ar.conf/ar.cfg file to use the primary FTS server name
and the new port selected for the secondary FTS plug-in instance.
c. Edit the ar.conf/ar.cfg file by changing the paths for
Full-Text-Configuration-Directory and Full-Text-Collection-Directory to reflect the
correct paths (that is, the same as edited in pluginsvr_config.xml files for these two
items)
Note
These will be the same values on the primary server. These values are what
the primary server sees and not the local server.
d. Ensure that no entry exists for the Private-RPC-Socket: 390602 setting or that it is
commented out.
11. On only the designated primary FTS server, edit the armonitor.conf/cfg file to do the
following:
a. Fix the FTS path by appending /primary to the /fts, followed by a semicolon and the
new full path to the core directory. For example, /fts/primary.
b. Copy this line and change /fts/primary to fts/secondary.
12. If a copy operation was started in step 8, ensure that it is completed before continuing.
13. Restart only the primary FTS server, ensure that is running and processing the ft_pending
records, if any.
14. Restart the AR System servers.
Page 334 of 4705
Home
BMC Remedy ITSM Suite 9.0 Solution Performance

Benchmarks
This section describes BMC Remedy ITSM Suite 9.0 Solution Performance Benchmarks that were
conducted on a clustered environment with BMC Remedy IT Service Management (BMC Remedy
ITSM), BMC Smart Reporting, BMC Service Request Management, BMC Knowledge Management,
and BMC Atrium Configuration Management Database (BMC Atrium CMDB) applications. The
topics include:
Benchmark summary
BMC Remedy ITSM Suite 9.0 Solution Benchmarks Test Environment
Methodology
Results
Software component configuration settings
Definition of performance benchmark use cases
Benchmark summary
Using the referenced small-customer model of 300 concurrent users, BMC conducted a series of
tests to determine the optimal BMC Remedy Mid Tier and BMC Atrium SSO web cluster size and
the optimal BMC Remedy Mid Tier and BMC Atrium SSO node size. The throughput and resource
usage data at the Java virtual machine (JVM) monitoring level indicated the following optimal
configurations:
Three-node BMC Remedy Mid Tier web cluster; each node with eight CPU Cores and 16 GB
of RAM
Two-node BMC Atrium SSO web cluster; each node with four CPU Cores and 8 GB of RAM
This section describes the test environment and provides the test results for the small-customer
model. The workload is a mixture of online usage and BMC Atrium CMDB processing jobs. The
benchmarks show the following:
Three-node BMC Remedy Mid Tier web cluster supports 12 tenants, each with 300
concurrent users
Two-node BMC Remedy Mid Tier web cluster shows comparable user response times to the
three-node BMC Remedy Mid Tier web cluster
BMC also conducted the following additional tests:
100 concurrent users model for tenant scalability. Results show a three-node BMC Remedy
Mid Tier web cluster supports 20 tenants.
Standalone BMC Atrium CMDB workload with 100,000 configuration items (CIs) and
relationships (CIRs)
Page 335 of 4705
Home
For these tests, a concurrent user is defined as a user who executes a specified number of
transactions per hour. See the tables in Methodology for a description of the test use cases,
including the number of transactions per hour tested for a concurrent user. The user scenarios and
workloads used in the performance and scalability tests were derived from actual customer cases.
BMC Remedy ITSM Suite 9.0 Solution Benchmarks Test Environment

This topic describes the deployment architecture of BMC Remedy ITSM Suite 9.0 Solution in BMC
performance benchmarking lab and the hardware specification of the background servers.
Hardware specification for servers

Tiers
Specification
VM
used
Server
Quantity
OS and Database
BMC Atrium Single

Sign-On
4 CPU cores at 2.4 GHz each

, 8 GB RAM
Yes
CentOS 6.5; clustered
BMC Remedy Mid

Tier

, 16 GB RAM
Yes
CentOS 6.5; clustered
BMC Remedy AR
System server

, 12 GB RAM
Yes
Microsoft Windows Server 2008 R2 Enterprise; One

Server for each tenant
BMC Smart
Reporting Server

, 16 GB RAM
Yes
CentOS 6.5; Load balanced
Page 336 of 4705
Home
Tiers
Specification
VM
used
Server
Quantity
OS and Database
Database server
20 CPU cores at 2.4 GHz

each, 512 GB RAM
No
Microsoft SQL server 2012 Enterprise on Windows

server 2012; Shared by all tenants
Methodology
End-user response times were captured for key actions in the following test cases:
Simulating a customer with a workload of 300 concurrent users 100 ms latency
Simulating a customer with a workload of 300 concurrent users 300 ms latency
The key actions for which end-user response time was captured were:
Log on to home page
Open incident in New mode
Modify incident to resolve
Create incident (redisplay after submit)
Open change in New mode
Create change
Open Request Entry console
Create service request with six questions with mapping
Search Knowledge for articles
Search Knowledge for large PDFs
View Overview console for assigned to All My Groups
The SoftPerfect Connection emulator was installed and configured on the client computer to set the
high latency.
The following information describes user log on behavior for the tests:
BMC Remedy ITSM users logged on once and performed a specified number of transactions
for a business case before logging out. BMC Remedy ITSM users were logged on for the
entire duration of the simulation.
BMC Service Request Management users logged on, performed one business transaction,
and then logged out. BMC Service Request Management users were not logged on to the
system for the entire duration of the simulation.
This setup simulates real-world user behavior for both BMC Remedy ITSM and BMC Service
Request Management.
This topic also provides information about:
Page 337 of 4705
Home
Workload
For the test cases that required a workload simulation, a mixed workload was added to the system
to simulate a common workload scenario for 2014.01 customers. The following mixed workload
was used:
Workload from BMC Remedy ITSM users
Workload from BMC Service Request Management users
Workload from BMC Knowledge Management users
Workload from BMC Email Engine (from BMC Remedy ITSM and BMC Service Request
Management workloads)
Workload from BMC Service Level Management (from BMC Remedy ITSM and BMC
Service Request Management workloads)
Workload from BMC Atrium CMDB batch jobs, Normalization Engine, and Reconciliation
Engine
The nominal workload environment was defined by the distribution of concurrent users and
transaction rates among the test scenarios. This workload was used as the baseline for
benchmarking the performance and scalability of the BMC Remedy solutions consistently over time
.
The workload from BMC Service Level Management and BMC Email Engine was based on the
BMC Remedy ITSM and BMC Service Request Management workloads. BMC Service Level
Management targets and milestones were triggered by specific BMC Remedy ITSM terms and
conditions. Email messages were created based on BMC Remedy ITSM, BMC Service Request
Management, and BMC Service Level Management workloads.
The workload from BMC Atrium CMDB batch jobs was executed during a 1-hour simulation. The
BMC Atrium CMDB batch jobs created configuration items (CIs) that were normalized, reconciled,
and merged into a BMC.Asset data set.
Nominal BMC Remedy Application workload distribution

The workload spread between BMC Remedy ITSM and BMC Service Request Management
applications was split into 63% and 37% of the total workload. The details of this split for BMC
Remedy ITSM and BMC Service Request Management are in the tables that follow.
The following table describes the workload split for BMC Remedy ITSM:
BMC Remedy ITSM scenarios
Percentage of
total
concurrent
users
Transaction rate
(per user per hour)
Projected executions
for 300 total concurrent users
in one hour
Search Incident by ID and Modify Incident to

Resolve
8%
144
Search Incident by Name
3%
18
Page 338 of 4705
Home
BMC Remedy ITSM scenarios
Percentage of
total
concurrent
users
Transaction rate
(per user per hour)
for 300 total concurrent users
in one hour
Search Records for a User via Global Search
4%
60
Search Request Record via ID in Global Search
2%
30
Open/Refresh Overview Console
5%
10
150
Create Incident with CI (Modify Request after

Submit)
9%
189
Inbound Email Based Update of Incident
8%
96
Create Change with Service CI
2%
12
Search Change by ID
3%
45
Change Approval
2%
54
Knowledge Search and View Big Document
4%
36
Knowledge Search and View Articles
4%
36
Update Work Order
6%
108
Smart Reporting - Access Incident Management

report and saves it
5 users per
tenant
30 (Need to be
changed!)
150
Smart Reporting - Access Incident Management
3 users per
30 (Need to be
90
Dashboards
tenant
changed!)
Smart Reporting - Create report on OOTB Incident

Management view
2 users per
tenant
15 (Need to be
changed!)
30
The following table describes the workload split for BMC Service Request Management:
Table
Workload split for BMC Service Request Management
BMC Service Request Management
scenario
Percentage of
total concurrent
users
Transaction rate
(per user per
hour)
for 300 total concurrent users in one
hour
View Service Request Details and Add

Activity Log
10%
60
View Services in Category and Subcategory
2%
30
Create Service Request
10%
120
Search by Keyword
15%
90
Page 339 of 4705
Home
BMC Service Level Management and email notification workload distribution

Email notifications were sent when an incident was created or modified, when a service request
was created, and when a BMC Service Level Management milestone was missed. BMC Service
Level Management targets were also triggered under the same conditions. The following table lists
the number of email notifications generated and BMC Service Level Management targets matched
for each created incident, modified incident, and created service request. This workload was done
automatically on the BMC Remedy AR System server.
Table
Email notification and BMC Service Level Management executions
Scenario
Email count per

entry
BMC Service Level Management target count per

entry
Create Incident from Browser and
1-2
Modify Incident from Browser
5 to 7
Create Service Request
Create Change
Modify Change
Workstation
CI normalization and reconciliation workload distribution

During the 1-hour simulation, 5,000 CIs were generated, normalized, and reconciled every 10
minutes. 10% of the CIs were newly created while the other 90% were updated.
Simulating the workload of 3,600 concurrent users

In this test, the following workloads were used:
BMC Remedy ITSM, BMC Knowledge Management and BMC Service Request
Management
5,000 CIs for the Normalization Engine and Reconciliation Engine
The results are displayed in the following table. Actual entries created during a 3,600
concurrent-user load with 12 tenants for three midtiers cluster.
Table
Entries created during a 3-mid tier, 3,600 concurrent-user load
Entry Type
Number of actual entries created or modified (during entire hour)
Incidents created
4,278
Service Requests created
1,738
Page 340 of 4705
Home
Entry Type
Number of actual entries created or modified (during entire hour)
Changes created
212
Incidents modified
2,300
Work Orders modified
1,385
Outbound emails
25,506
Inbound emails
349
CiR created
6,204
CI updated
56,099
Simulating tenant scalability workloads

For the tenant scalability benchmarks of 1,200, 1,600, and 2,000 concurrent users, the following
workloads were used:
BMC Remedy ITSM, BMC Knowledge Management, and BMC Service Request
Management
5,000 CIs for the Normalization Engine and Reconciliation Engine
Standalone CI normalization and reconciliation workload distribution

100,000 CIs were normalized, reconciled, and merged for the standalone CMDB workload.
Data volume
The following table summarizes the foundation data and application data inserted into the BMC
Remedy AR System database prior to starting the tests:
Table
Data volume of BMC applications
Application
Description
Number of
entries
Application Object Template (AOT)
66
Process Definition Template (PDT)
88
Navigational Category
500
Levels
Service Request Definition (SRD)
37
Entitlement Rules
26
Matching Entitlement Rule per person
10
SRD for create Service Request with 6 questions mapped to 2

incident fields
SRD for create Service Request with 6 questions but no mapping
Page 341 of 4705
Home
Application
Description
Number of
entries
Existing service requests for volume
85,755
BMC Incident Management
Incidents
91,747
Change Requests
13,858
BMC Service Request Management Work Orders
Work Orders
5001
BMC Problem Management
Problems
10,001
BMC Atrium CMDB and Foundation
Companies
25
Site
168
Org
48
Support Groups
36
Total End Users
4,000
Total Support Users
2,000
Support Functional Roles
12,000
People Permission Groups
32,006
CIs and Relationships (total)
214,113
Business Service CIs
240
Assignment Configuration
175
Service Targets
80
CIs attached to end user
4,000
Articles
10,000
External Small PDF Documents 120 KB
10,000
External Large PDF Documents 1 MB
1,000
Atrium Core CMDB processes standalone benchmark

This page has not been approved for publication.
BMC Remedy solution benchmark methodology

Data volume
Measurement of response times

All response times are measured after BMC Remedy Mid Tier and the browser contents are cached
, and after the user logs on and runs through the use cases once. Measurements are timed on the
second round of use cases but in the same session and all timings are taken against one tenant.
Page 342 of 4705
Home
Simtec HttpWatch tool is used to measure timings on a client computer with the following
specifications:
Model: VM
OS: Microsoft Windows 7, 64-bit
CPU: Two processors (Intel Xeon 2.00 GHz, single core)
RAM: 4 GB
Web browser: Microsoft Internet Explorer 11
The following are the Internet Explorer browser settings:
Clear the Do not save encrypted pages to disk check box.
Clear the Empty Temporary Internet Files folder when browser is closed check box.
Disable all browser add-on toolbars and plug-ins except HTTPWatch.
Configure the browser cache setting to Automatic.
Configure the maximum browser cache size to 250 MB.
The SoftPerfect Connection emulator is installed and configured on a client computer to set high
latency.
Definition of session types

There is concept of a First Session, a New Session, and an In Session with respect to the BMC
Remedy Mid Tier logon session. The following table describes the types for BMC Remedy Mid Tier
logon sessions:
BMC Mid Tier logon
session
Description
First session
BMC Remedy Mid Tier is cached.
Browser is not cached.
User logs on and opens console x or form Y. The browser is cached for the first time. Record
this time. Log off.
New session
Browser is cached from the first session access.
User logs on and opens console x or form Y for the first time within this session. Record this
time.
For example, a support user logs on in the morning.
In session
Browser is cached from the First Session access.
User has already logged on and opened console x and form Y.
User reopens console x and form Y from within this session. Record this time.
For example, the remainder of the day after a support user logs on in the morning
Page 343 of 4705
Home
Response times vary, depending on which session type is measured. In Session produces the
fastest response time of the session types and First Session produces the slowest response times.
In Session is the most commonly measured BMC Remedy Mid Tier logon session type because it
describes the typical work environment.
Smart Reporting standalone benchmark

Results
This section provides the results from the tests and describes how the results were measured.
The following topics are provided:
Solution Benchmarking Results
Single user response times
BMC Atrium CMDB standalone benchmarks
Smart Reporting Standalone
Mixed workload with Process Designer workflows in live
Response times and resource utilization

The response times and resource utilization described are organized by the following benchmark
tests.
Single user response times

When single user response times are taken, only one user manually interacts with the system
under test without any additional load.
The following test scenarios are covered:
Scenario
Network Latency
Web Browser
(TCP round trip between

the client and the system)
A
LAN
Internet Explorer (Version 11)
LAN
Firefox (Version 37)
LAN
Chrome (Version 41)
100 ms
300 ms
Measurement of response times

Please refer to section Measurement of response times for details.
Page 344 of 4705
Home
Response times on different web browsers

Key Single user response times (In Session) under <1 ms latency, timed from different web
browsers:
Response times on different latencies

Key Single user response times (In Session) timed from Internet Explorer (version 11) with network
latencies being <1ms, 100 ms and 300 ms:
Page 345 of 4705
Home
Table that follows displays key Single user In Session response times in numbers:
Action
Sequence
User Actions
<1 ms network
latency
100 ms network
latency
300 ms network
latency
1.
Login to home page
4.6
9.2
11.2
2.
Open Incident Console
0.1
0.1
0.1
3.
Open Incident in New Mode
0.2
0.2
0.4
4.
Modify Incident to resolve
3.5
4.8
7.7
5.
Create Incident (redisplay after submit)
2.6
4.0
5.1
6.
Open Change Console
0.1
0.1
0.1
7.
Open Change in new mode
0.1
0.2
0.4
8.
Create Change
2.4
3.1
5.4
9.
Open Request Entry Console
4.0
4.6
6.7
10.
Create Service Request with 6 questions

with mapping
2.4
2.7
4.0
11.
Knowledge Search for Articles
0.5
0.7
0.9
12.
Knowledge Search for Big PDFs
2.2
2.4
2.7
13.
Knowledge View Big PDF
2.1
6.4
13.9
14.
Open Asset Management Console
0.1
0.1
0.1
15.
Overview Console (View Assigned to All My

Groups)
1.1
1.6
2.3
Histogram of response times
Page 346 of 4705
Home
Hardware Specification
The client machine is a Windows 7 Virtual Machine with 2 cores 4 GB RAM. Refer BMC Remedy
ITSM Suite 9.0 Solution Benchmarks Test Environment for details of server hardware specification.
BMC Atrium CMDB standalone benchmarks

This topic provides details for BMC Atrium CMDB benchmarks.
Testing Scenarios
BMC measured throughput of CI Creation, normalization, and reconciliation (identification, merge
and overall) batch jobs for the following test scenarios:
Processing 100K CIs (Relationship included), using one dedicated 2 CPU Cores 12 GB
RAM AR server and one dedicated DB server.
Processing 100K CIs (Relationship included), using one dedicated 4 CPU Cores 16 GB
Processing 1 Million CIs (Relationship included), using one dedicated 4 CPU Cores 16 GB
The dedicated DB server had 20 CPU cores , 512 GB RAM and 1 local disk drive plus 3 SAN
RAIDs. Refer BMC Remedy ITSM Suite 9.0 Solution Benchmarks Test Environment for hardware
specification details.
Testing steps
A BMC Atrium CMDB standalone benchmark consists of CMDB processing only, without online or
any other load added to the system under test.
Page 347 of 4705
Home
The following testing steps are performed:

Utilize A BMC internal tool to generate synthetic CMDB configuration items (CIs) and their
Relationship data.
Run CMDB normalization job to normalize CIs with normalization type set to either CTI Only
or Name & CTI lookup.
Run CMDB reconciliation job to reconcile CIs.
Testing Results
BMC Atrium CMDB job throughput - 2 CPU cores AR server vs. 4 CPU cores AR server:
BMC Atrium CMDB job throughput - 100K CIs vs. 1 million CIs:
BMC Atrium CMDB job throughput in numbers:
Page 348 of 4705
Home
100K CIs, AR 2 CPU cores
100K CIs, AR 4 CPU cores
1M CIs, AR 4 CPU Cores
Create CI instance
194
260
189
Create CI (CMI)
254
525
557
NE CTI
160
231
255
NE CTI+NAME
178
238
261
RE/ID
283
430
262
RE/Merge
121
162
152
RE
85
116
96
BMC Atrium CMDB job CPU utilization

CPU utilization on the AR server
Processing 100K CIs using a 2 CPU cores AR server vs. using a 4 CPU Cores AR server:
Processing 100K CIs vs. Processing 1 Million CIs, using a 4 CPU Cores AR server:
Page 349 of 4705
Home
CPU utilization on the SQL server

For NE and RE job, the CPU utilization on the SQL server (20 CPU cores) is about 6.5% and 2.4%
respectively.
CMDB testing data distribution

CI volume distribution by classes:
CI ClassId
Count (100K CIs scenario)
Count (1 Million CIs scenario)
BMC_PRODUCT
28,275
282,750
BMC_DISKDRIVE
8,700
87,000
BMC_MONITOR
2,175
21,750
BMC_BIOS
2,175
21,750
BMC_OPERATINGSYSTEM
2,175
21,750
BMC_CARD
2,175
21,750
BMC_IPENDPOINT
2,175
21,750
BMC_COMPUTERSYSTEM
2,175
21,750
BMC_PROCESSOR
1,706
17,060
BMC_PROCESSOR
469
4,690
BMC_HOSTEDSYSTEMCOMPONENTS
47,850
478,500
BMC_HOSTEDACCESSPOINT
2,175
21,750
CI in Total
102,225
1,022,250
Note
Page 350 of 4705
Home
BMC_HOSTEDSYSTEMCOMPONENTS and BMC_HOSTEDACCESSPOINT are

relationship classes.
BMC Atrium CMDB batch job settings

The following settings are used during the benchmarks:
CMDB standalone batch job settings
Parameter
Value
CMDB-Inline-Normalization
NE and RE job modes
Batch
NE threads in batch pool
10
NE chunk size
50
RE logging level
Error
RE definition check interval (seconds)
300
Smart Reporting Standalone

Mixed workload with Process Designer workflows in live

Software component configuration settings
Note
This section contains only BMC Internal information that is not available to
customers.
This section provides information related to the software component configuration settings that
were used in the benchmark testing.
BMC Atrium CMDB performance benchmark configuration settings
BMC Atrium Single Sign-On performance benchmark configuration settings
BMC Remedy AR System application server performance benchmark configuration settings
BMC Remedy Mid Tier performance benchmark configuration settings
F5 load-balancer configuration
Microsoft SQL Server database configuration
Page 351 of 4705
Home
BMC Atrium CMDB performance benchmark configuration settings

The following tables contain configuration values used during the BMC Atrium CMDB performance
benchmark testing.
BMC Atrium CMDB with online load settings
Parameter
Value
Normalization Type
CTI only
NE and RE job modes
Continuous
NE private queue min/max
2/2
NE threads in continuous pool
10
NE events threshold
10
NE time threshold (seconds)
180
RE private queue min/max
2/2
RE logging level
Error
RE continuous job interval (seconds)
300
RE polling interval (seconds)
300
300
BMC Atrium CMDB stand-alone settings

Parameter
Value
Normalization Type
CTI only
NE and RE job modes
Batch
NE threads in batch pool
10
NE chunk size
50
RE logging level
Error
300
BMC Atrium Single Sign-On performance benchmark configuration settings

The following tables describe the BMC Atrium Single Sign-On configurations used during the
performance benchmark testing.
Java virtual machine (JVM) settings
Page 352 of 4705
Home
JVM Parameter and value
Comments
-XX:HeapDumpPath=/opt/bmc/AtriumSSO/tomcat/outOfMemErrDump.hprof
-XX:+UseConcMarkSweepGC
-XX:+UseParNewGC
-XX:PermSize=256m
-XX:MaxPermSize=256m
-Xms2048m
Minimum JVM heap
-Xmx2048m
Maximum JVM heap
-XX:+HeapDumpOnOutOfMemoryError
-Datsso.log.level=SEVERE
Apache Tomcat settings

Parameter
Value
Max Threads
500
Log Level
Severe
BMC Atrium Single Sign-On Agent Logging on each mid tier
Severe
BMC Remedy AR System application server performance benchmark configuration settings

BMC Remedy AR System server configuration settings
Application configuration comments
Java Plug-in thread settings for BMC Remedy AR System server
Java heap settings for BMC Remedy AR System server

The following tables describe the BMC Remedy AR System server configuration settings:
Settings
Page 353 of 4705
Home
Settings
-XX:+UseParNewGC
-XX:PermSize=256m
-Xms2048m
-Xmx4096m

Parameter and value
Comments
Max-Entries-Per-Query: 2,000
Next-ID-Block-Size: 100
Server-Side-Table-Chunk-Size: 1,000
Allow-Unqual-Queries: F
Cache-Mode: 0
Disable development cache mode
Submitter-Mode: 1
Lock submitter mode
Authentication-Chaining-Mode: 1
Enable BMC Atrium Single Sign-On
Server-Plugin-Default-Timeout: 300
measured in seconds
External-Authentication-Return-Data-Capabilities: 31
Debug-mode: 131120
Large-Result-Logging-Threshold: 1,000,000
For logging
Max-Log-History: 8
For logging
Max-Log-File-Size: 134,217,728
For logging
Plugin-Log-Level: 1,000
For severe logging
VersionControl-Object-Modification-Log-Mode: 10
For logging
VersionControl-Object-Modification-Log-Save-Definition-Files
:0
For logging
CMDB-Inline-Normalization: T
RE-RPC-Socket: 390698
Indicate which queue number will be used for reconciliation. Do

not use in Integration Server setup.
BMC Remedy AR System server thread settings

Page 354 of 4705
Home
Parameter and value
Number of threads
(port number
Comments
minimum/
maximum)
Private-RPC-Socket:
1/1
Alert queue
3/3
Escalation queue
Private-RPC-Socket:
390620
8/12
Fast queue
Private-RPC-Socket:
390621
5/12
Created during BMC Atrium Core installation. Used by Product Catalog Data
Loader.
Private-RPC-Socket:
5/5
Loopback socket queue. Use the same queue as CAI to share threads, so only
390601
Private-RPC-Socket:
390603
390626
one entry is needed. Create an entry in the CAI Plugin Registry form with
private queue number matching the number of threads.
Private-RPC-Socket:
390635
8/12
List queue
Private-RPC-Socket:
390698
2/2
Reconciliation queue. The queue number must match RE-RPC-Socket. Do not

use in Integration Server setup.
Private-RPC-Socket:
390699
2/2
CMDB RPC normalization queue. Do not use in Integration Server setup.
Private-RPC-Socket:
2/2
AR RPC normalization queue. Do not use in Integration Server setup.
Private-RPC-Socket:
390680
2/2
Approval
Plugin-ARDBC-Threads:
4/12
Threads used by the C-Plugin server to process ARDBC API calls. The default
is one thread.
Plugin-AREA-Threads:
4/12
Threads used by the C-Plugin server to process AREA API calls. The default is
one thread.
Plugin-Filter-API-Threads
4/12
Threads used by the C-Plugin server to process Filter-API calls. The default is
390681
one thread.
Application configuration comments

The following observations apply to the configuration of the Incident Management application:
Clear the check marks for additional panels on the Incident Management Console.
Incident and change notifications are enabled for individuals only. Group notifications are
disabled.
No service request is created when an incident request is submitted.
Java Plug-in thread settings for BMC Remedy AR System server

The following table contains values for the Java Plug-in thread settings for the BMC Remedy AR
System server.
Page 355 of 4705
Home
Java Plug-in
numCoreThreads
numSelectorThreads
AR Plugin
30
FTS Plugin
CMDB Plugin
NE Plugin
Java heap settings for BMC Remedy AR System server

The following table contains Java heap settings for the BMC Remedy AR System server.
Java process
Maximum JVM heap
AR Server
4048 MB
AR Plugin Server
512 MB
Assignment Engine
256 MB
Data-Integration
1024 MB
CMDB Plugin Server
512 MB
NE Plugin Server
512 MB
BMC Remedy Mid Tier performance benchmark configuration settings

The following tables describe the BMC Remedy Mid Tier configuration settings that were used.
Settings
-XX:+UseParNewGC
-XX:PermSize=256m
-Xms12288m
-Xmx12288m
-XX:+HeapDumpOnOutOfMemoryError
Page 356 of 4705
Home
Apache Tomcat settings

Parameter
Value
Unit
Accept Count
250
Max Threads
12,000
Connection Timeout
60,000
milliseconds
Keep Alive Timeout
60,000
milliseconds
Max Keep Alive Requests
5,000
Max Spare Threads
100
Min Spare Threads
50
Linux system settings

Parameter
Value
User file descriptor
50,000
System-wide file descriptor
2,000,000
BMC Remedy Mid Tier configuration settings

Key/value
Comments
Per tenant
?
arsystem.cache_update_interval=86400
Interval BMC Remedy Mid Tier

checks with the BMC Remedy AR
System server for new definition
changes.
Yes
arsystem.pooling_max_connections_per_server=80
Maximum number of connections

that BMC Remedy Mid Tier will
open to each BMC Remedy AR
System server on the BMC
Remedy AR System server list;
generally, for casual users, a ratio
of 1:4.
No.
Provided
that each
tenant in
the cluster
supporting
same
workload.
arsystem.ehcache.overflowToDisk=true
arsystem.ehcache.overflowToDiskTemp=false
Enable cache persistence to disk.
No
arsystem.ehcache.referenceMaxElementsInMemory=5835
Ehcache settings per Apache

Tomcat node in a 3-node MT
cluster serving 12 tenants.
No
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formImages=0.641
arsystem.ehcache.referenceMaxElementsInMemoryWeight.activeLinks=8.824
arsystem.ehcache.referenceMaxElementsInMemoryWeight.groups=0.003
arsystem.ehcache.referenceMaxElementsInMemoryWeight.roles=0.068
arsystem.ehcache.referenceMaxElementsInMemoryWeight.js=2.734
Page 357 of 4705
Home
Key/value
Comments
Per tenant
?
arsystem.formhtmljs_expiry_interval=86400
Browser cache directive interval

for AR forms and activelinks.
Yes
arsystem.resource_expiry_interval=86400
Browser cache directive for web
Yes
arsystem.ehcache.referenceMaxElementsInMemoryWeight.displayedFields=
0.378
arsystem.ehcache.referenceMaxElementsInMemoryWeight.fieldMaps=21.999
arsystem.ehcache.referenceMaxElementsInMemoryWeight.sysdata=9.081
arsystem.ehcache.referenceMaxElementsInMemoryWeight.compiledForms=
.335
arsystem.ehcache.referenceMaxElementsInMemoryWeight.forms=0.400
arsystem.ehcache.referenceMaxElementsInMemoryWeight.html=1.252
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formFields=40.851
arsystem.ehcache.referenceMaxElementsInMemoryWeight.sharedResources=
0.035
arsystem.ehcache.referenceMaxElementsInMemoryWeight.syncRelationships=
503.561
arsystem.ehcache.referenceMaxElementsInMemoryWeight.actorViews=0.32
arsystem.ehcache.referenceMaxElementsInMemoryWeight.actorViewsMapping
=0.32
arsystem.ehcache.referenceMaxElementsInMemoryWeight.hashCache=
618.162
arsystem.ehcache.referenceMaxElementsInMemoryWeight.refCount=51.544
resources (images, CSS, and so

on) coming from BMC Remedy
Mid Tier. This value should match
the value of the previous key for
ease of maintenance.
Log only the minimum. Can

change to Info if more logging is
needed for debugging.
No
Log only internal errors. Can add

more categories if more logging is
needed for debugging.
No
arsystem.use_loadbalanceinterval=true
No
No
arsystem.use_loadbalanceinterval_limit=15
arsystem.securitytoken_enable=false
F5 load-balancer configuration
The following tables describe the F5 load-balancer configuration settings used during the
performance benchmark testing. The F5 version is BIG-IP 10.2.4 Build 655.0 Hotfix HF4.
Page 358 of 4705
Home
The load balancer was set up with two pools: one for mid tiers and another for BMC Atrium Single
Sign-On servers.
Pool settings
F5 setting
Value
Keep-alive count
5,000
Keep-alive timeout
60 seconds
Load-balancing scheme
Round-robin with HTTP session binding cookie insert
Mid tier monitor settings

F5 mid tier monitor setting
Value
Type
HTTP
HTTP Protocol Version
HTTP 1.1
Type
Common
Interval
15 seconds
Timeout
46 seconds
Send String
GET /arsys/shared/images/bkgd_image.gif HTTP/1.1\r\nHost: Close\r\n\r\n
Receive String
HTTP/1.1 200 OK
Reverse
No
Transparent
No
BMC Atrium Single Sign-On monitor settings

F5 BMC Atrium Single Sign-On
Monitor Setting
Value
Type
HTTPS
HTTP Protocol Version
HTTP 1.1
Type
Common
Interval
5 seconds
Timeout
16 seconds
Send String
GET /atriumsso/config/auth/opensso/services/bmcrealm/html/empty.png HTTP/1.1\r\

nHost: Close\r\n\r\n
Receive String
HTTP/1.1 200 OK
Cipher List
DEFAULT:+SHA:+3DES:+kEDH
Reverse
No
Transparent
No
Page 359 of 4705
Home
Microsoft SQL Server database configuration

The following table describes the Microsoft SQL Server database-configuration settings used during
the performance benchmark testing.
Note
The database system was shared with many other active databases.
SQL Server setting
Value
ALLOW_SNAPSHOT_ISOLATION
OFF
READ_COMMITTED_SNAPSHOT
ON
PARAMETERIZATION
SIMPLE
Max Degree of Parallelism
Definition of performance benchmark use cases

This section provides descriptions of the use cases that were used in the test:
BMC Remedy ITSM performance benchmark use cases
BMC Service Request Management performance benchmark use cases
BMC Smart Reporting performance benchmark use cases
BMC Remedy ITSM performance benchmark use cases

This topic describes the BMC Remedy ITSM use cases that were run during the tests.
Search incident and modify incident to resolved
Search incident by customer name
Search records for a user via Global Search
Search request record ID via Global Search
Open/refresh Overview console and view entry
Create incidents with CI related and modify request after submit
Inbound email update incident
Create change with CI and task
Search change by ID
Knowledge search and view big PDF
Knowledge search and view articles
Update work order with a task
Run incident count by product categorization web report
Run asset print web report
Run service requests by location web report
Page 360 of 4705
Home
Search incident and modify incident to resolved

This use case ran the Search incident by ID and update incident resolved status transaction.
Table
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
Configure load-generator settings.
No
No
Transaction
As a support user, log on to the home page with the user name 05681-Test.
No
No
Transaction
Click the Incident Management Console link.
Yes
Yes
Transaction
Click Search Incident.
No; refresh
sometimes
Yes
Transaction
Enter an ID that is from the Incident Console list.
Yes
No
Transaction
Modify the Change Status field value to In Progress. Click Save.
Yes
Yes
Transaction
Change the Status field value to Resolved. Open the Status Reason menu and select No
Yes
No
Further Action Required. Enter some text in the Resolution field.

Transaction
Click Save.
Yes
Yes
Transaction
Log out.
No
No
End
Close any open files.
No
No
Search incident by customer name

This use case ran the Search incident by customer name transaction.
Table
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
No
No
Transaction
As a support user, log on to the home page with the user name 05681Test.
No
No
Transaction
No, but every so often

refresh
Yes
Transaction
Click the Search Incident link.
Yes
Transaction
Enter the customer name in the Customer field and press Enter.
Yes
Yes
Transaction
Click Search.
Yes
Yes
Transaction
Log out.
No.
No
End
No
No
Page 361 of 4705
Home
Search records for a user via Global Search

This use case ran the Search records for a user via Global Search transaction.
Table
Phase
name
Transaction step
Repeat
?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
Type a support user name (for example, 05736-Test) in the Global Search box. Click Search.
Yes
Yes
Transaction
Log out.
No
No
End
No
No
Search request record ID via Global Search

This use case ran the Search request record ID via Global Search transaction.
Table
Phase
name
Transaction step
Repeat
?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
Type an Incident ID (for example, INC000000004567) in the Global Search box. Click
Yes
Yes
Search.
Transaction
Log out.
No
No
End
No
No
Open/refresh Overview console and view entry

This use case ran the Open/refresh Overview console and view entry transaction.
Table
Phase
name
Transaction step
Repeat?
Timed?
Initialization
No
No
Initialization
No
No
Transaction
From the Overview Console, click the Show menu and select Assigned to All My Groups.
Yes
Yes
Transaction
Select an Incident record and double-click to view.
Yes
Yes
Transaction
From the incident, click IT Home.
Yes
No
Transaction
Click the Refresh button.
Yes
Yes
Page 362 of 4705
Home
Phase
name
Transaction step
Repeat?
Timed?
Transaction
Log out.
No
No
End
No
No
Create incidents with CI related and modify request after submit

This use case ran the Create incidents with CI related and modify request after submit transaction.
Table
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction

Ensure that the user option is to have "modify request after submit."
No, refresh
sometimes
Yes
Transaction
Click the New Incident link.
Yes
Yes
Transaction
Enter the first name of a customer (01000-Test) in the Customer field and press Enter.
Yes
Yes
Transaction
Enter a summary and notes.
Yes
No
Transaction
Open the Service menu and select a value.
Yes
Yes
Transaction
Open the Impact menu and select a value.
Yes
No
Transaction
Open the Urgency menu and select a value.
Yes
Yes
Transaction
Click Submit.
Yes
Yes
Note: If an error about the Product Catalog appears, click the Select Product link on the left
and choose any product. (Do not record this step.) Then try to submit again.)
Transaction
Log out.
No
No
End
No
No
Inbound email update incident

This use case ran the Inbound email update incident transaction.
Table
Phase
name
Transaction step
Repeat
?
Timed
?
Initialization
No
No
Transaction
Not done through the GUI. Script sends an email to the Exchange Server with the Incident ID in
the subject line. The message body can be any text and can contain up to 2,000 characters.
Senders are 5 unique email addresses.
Yes
Yes
End
No
No
Page 363 of 4705
Home
Create change with CI and task

This use case ran the Create change with CI and task transaction.
Table
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
Click the Change Management Console link.
No, refresh
sometimes
Yes
Transaction
Click the New Change link.
Yes
Yes
Transaction
Enter summary text.
Yes
No
Transaction
From the Service CI menu, select a value.
Yes
Yes
Transaction
Click the Dates tab.
Yes
No
Transaction
Open the Scheduled Start Date calendar and select a future date.
Yes
No
Transaction
Open the Scheduled End Date calendar and select a future date that is 1 day later than
the scheduled start date.
Yes
No
Transaction
Click the Task tab. The Request Type menu should be on Ad Hoc. Click the Relate
button.
Yes
Yes
Transaction
In the Create Task dialog box, enter a name, a summary, and notes.
Yes
No
Transaction
Click Save in the Create Task dialog box.
Yes
Yes
Transaction
For Process Flow Status Initiate, choose Next Stage.
Yes
Yes
Transaction
The Change Initialization Dialog opens. If the Manager Group value is empty, choose a
Yes
Yes
value from Org 1, Group 1. Click Save.

Transaction
Log out.
No
No
End
No
No
Search change by ID
This use case ran the Search change by ID transaction.
Table
Phase
name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Click the Change Management Console link.
No, refresh
sometimes
Yes
Transaction
Open the Change form in Search mode.
Yes
Page 364 of 4705
Home
Phase
name
Transaction step
Repeat?
Timed?
No, refresh
sometimes
Transaction
Enter a Change entry ID (use 123) and click Search.
Yes
Yes
Transaction
Log out.
No
No
End
No
No
Knowledge search and view big PDF

This use case ran the Knowledge search and view big PDF external doc transaction.
Table
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
No,
refresh
Yes
sometimes
Transaction
No,
refresh
sometimes
Yes
Transaction
Enter an ID in the Incident ID field. Use INC000000004567.
Yes
Yes
Transaction
Click Search.
Yes
Yes
Transaction
Select Links > Search Knowledge Base.
Yes
Yes
Transaction
In Advanced Search, clear all settings and check the option for External Files under
Yes
Yes
Source. Enter the search string wham in the Include all of these words text field. Click
Search.
Transaction
Click an entry from the results to view the details.
Yes
Yes
Transaction
Close the view details window.
Yes
No
Transaction
Close the window.
Yes
No
Transaction
Log out.
No
No
End
No
No
Knowledge search and view articles

This use case ran the Knowledge search and view articles transaction.
Table
Page 365 of 4705
Home
Phase
name
Transaction step
Repeat?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
No, refresh
sometimes
Yes
Transaction
No, refresh
Yes
sometimes
Transaction
Enter an ID in the Incident ID field. Use INC000000004567.
Yes
Yes
Transaction
Click Search.
Yes
Yes
Transaction
Select Links > Search Knowledge Base.
Yes
Yes
Transaction
In Advanced Search, clear all settings and check the How To option under Sources. Enter
Yes
Yes
the search string Gemini in the Include all of these words text field. Click Search.
Transaction
Click an entry from the results to view the details.
Yes
Yes
Transaction
Close the view details window.
Yes
No
Transaction
Close the window.
Yes
No
Transaction
Log out.
No
No
End
No
No
Update work order with a task

This use case ran the Update work order with a task transaction.
Table
Phase
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Click the Work Order Console link.
Yes
Yes
Transaction
Randomly select an entry and view it.
Yes
Yes
Transaction
Click the Task tab. From the Request Type menu, choose Ad hoc. Click Relate.
Yes
No
Transaction
In the Task dialog box, fill out the Name and Summary fields with any value. Click Save.
Yes
Yes
Transaction
Click Save on Work Order.
Yes
Yes
Transaction
Log out.
No
No
End
No
No
name
Run incident count by product categorization web report

This use case ran the Run incident count by product categorization web report transaction.
Page 366 of 4705
Home
Table
Phase
name
Transaction step
Repeat
?
Timed
?
Initialization
No
No
Transaction
No
No
Transaction
Click on Incident Management Console link.
Yes
Yes
Transaction
Click rhw Reports link.
Yes
Yes
Transaction
In the Report Console, select Category menu value Incidents > Open Incidents > Count by
Yes
No
Product Categorization.
Transaction
In the Task dialog box, fill out the Name and Summary fields with any value. Click Save.
Yes
Yes
Transaction
Click Run.
Yes
Yes
Transaction
Log out.
No
No
End
No
No
Run asset print web report

This use case ran the Run asset print web report transaction.
Table
Phase name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Click the Asset Management Console link.
Yes
Yes
Transaction
Click the Reports link.
Yes
Yes
Transaction
Randomly select an entry and click Print.
Yes
Yes
Transaction
Close the Report Viewer.
Yes
No
Transaction
Log out.
No
No
End
No
No
Run service requests by location web report

This use case ran the Run service requests by location web report transaction.
Table
Phase
name
Transaction step
Repeat
?
Timed
?
Initialization
No
No
Transaction
No
No
Page 367 of 4705
Home
Phase
name
Transaction step
Repeat
?
Timed
?
Transaction
Click the Service Catalog Manager console link.
Yes
Yes
Transaction
Click the Reports link.
Yes
Yes
Transaction
Click the Functions > Reports link.
Yes
Yes
Transaction
In the Reporting Console, select the entry with the report name Service Requests by Location.
Yes
Yes
Click Run.
Note: A dialog box pops up, asking you to enter the company name and the start and end dates.
Choose any Company# and then choose Jan 1, 2012 to Jan 1, 2013 .
Transaction
Log out.
No
No
End
No
No
BMC Service Request Management performance benchmark use cases

This topic describes the BMC Service Request Management use cases that were run during the
tests:
View service request and add activity log entry
View services in a category and subcategory
Create service request with 6 questions and 2 field mappings
Search request entry by keyword
View service request and add activity log entry

This use case ran the View service request and add activity log entry transaction.
Table
Phase name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
As an end user, log on to the home page, with the username 00001-Test.
No
No
Transaction
Click the Request Entry link.
Yes
Yes
Transaction
Open requests are shown on the right. Click the right arrow to show more results.
Yes
Yes
Transaction
Randomly select an entry from the results. A dialog box opens with the result.
Yes
Yes
Transaction
Type some text in the Notes field. Click the + icon to add the text.
Yes
Yes
Transaction
Close the dialog box.
Yes
No
Transaction
Log out.
No.
No
End
No
No
View services in a category and subcategory

This use case ran the View services in a category and subcategory transaction
Page 368 of 4705
Home
Table
Phase name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Yes
Yes
Transaction
Click Browse.
Yes
Yes
Transaction
Randomly click any of the available category links.
Yes
Yes
Transaction
Within the category, click a subcategory button.
Yes
Yes
Transaction
Log out.
No.
No
End
No
No
Create service request with 6 questions and 2 field mappings

This use case ran the Create service request with 6 questions and 2 field mappings transaction.
Table
Phase name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Yes
Yes
Transaction
In the search bar, enter simulation and click the magnifying glass icon.
Yes
No
Transaction
Click the service request definition with mapping.
Yes
Yes
Transaction
Click Submit to create the service request.
Yes
Yes
Transaction
Log out.
No.
No
End
No
No
Search request entry by keyword

This use case ran the Search request entry by keyword transaction.
Table
Phase name
Transaction step
Repeat?
Timed?
Initialization
No
No
Transaction
No
No
Transaction
Yes
Yes
Transaction
Randomly enter a keyword of "keyword#" where # is a value from 1 to 10.
Yes
Yes
Transaction
Log out.
No.
No
Page 369 of 4705
Home
Phase name
Transaction step
Repeat?
Timed?
End
No
No
BMC Smart Reporting performance benchmark use cases

System requirements
Consult the following topics when planning a new installation of BMC Remedy Action Request
System. If you are upgrading, you might need to upgrade your hardware or software to be
compatible with the new version of BMC Remedy AR System.
Hardware requirements
Software requirements
Server operating system platforms
Unicode requirements
Portmapper service introduction
BMC Remedy Migrator memory usage and disk space requirements
Hardware requirements
As businesses continue to grow using BMC Remedy applications for example, the full BMC
Remedy IT Service Management stack including BMC Remedy AR System and BMC Atrium Core
it is critical to provide realistic hardware requirements to run these applications successfully in an
enterprise settings.
Environment
BMC Remedy
BMC Analytics for
BMC Dashboards for
Number of managed
ITSM
(concurrent
BSM
(concurrent users)
BSM
(concurrent users)
devices
users)
Proof of concept (POC
)
50
1,000 or fewer
Small
800
50
2,000 or fewer
Medium
2000
100
10
10,000 or fewer
Large
5000
250
50
30,000 or fewer
Recommended deployment of applications and hardware
Page 370 of 4705
Home
BMC published guidelines for hardware sizing based on a series of enterprise-scale tests to
demonstrate the scalability and performance of the following applications:
BMC Remedy IT Service Management Suite (BMC Remedy ITSM Suite)
BMC Atrium Configuration Management Database (BMC Atrium CMDB) applications
Note
These tests were conducted by BMC and Dell at the Dell Solution Center in Austin, Texas
in December, 2011. For the benchmarking results, see the Performance and Scalability of
7.6.04 SP1 BMC Remedy IT Service Management Suite, BMC Service Request
Management, BMC Knowledge Management, and BMC Atrium on Windows white paper.
Review the following hardware requirements for sizing carefully.

Component
POC
Small
Medium
Large
BMC Remedy AR System mid tier servers
None: Services combined with

AR System server
2
servers
:
2
servers:
5
servers
:
2 CPU
Core
8 GB
RAM
60 GB
disk
BMC Remedy AR System Web Services

AR System server
1
server:
4 CPU
Core
8 GB
RAM
60 GB
disk
1 server
:
4 CPU
Core
8 GB
RAM
60 GB
disk
2
servers
:
Page 371 of 4705
Home
Component
SAP BusinessObjects CMS Server (for BMC Analytics for BSM)
POC
1 server:
2 CPU Core
16 GB RAM
60 GB disk
BMC Remedy AR System server (user)
Small
Medium
Large
2 CPU
Core
8 GB
RAM
60 GB
disk
4 CPU
Core
8 GB
RAM
60 GB
disk
1
server:
1 server
:
1
server:
2 CPU
4 CPU
4 CPU
Core
16 GB
Core
24 GB
Core
32 GB
RAM
60 GB
RAM
60 GB
RAM
60 GB
disk
disk
disk
4 CPU
Core
8 GB
RAM
60 GB
disk
1 server:
BMC Atrium CMDB

BMC Remedy ITSM
servers:
4 CPU Core
servers
:
servers
:

12 GB RAM
250 GB disk
2 CPU
4 CPU
Core
4 CPU
Core
8 GB
8 GB
RAM
Core
8 GB
User-loaded servers
RAM
60 GB
60 GB
disk
RAM
60 GB
disk
BMC Remedy AR System server (back end)
BMC Atrium CMDB
BMC Remedy ITSM
1 server:
4 CPU Core
12 GB RAM
250 GB disk
Non-user-loaded servers for back-end AR System processes,

integrations, reconciliation, notification
BMC Atrium Single Sign On
BMC Dashboards for BSM Server (with DIL)

AR System server

AR System server
2
servers
:
4 CPU
Core
8 GB
RAM
60 GB
disk
disk
2
servers:
4 CPU
Core
12 GB
RAM
60 GB
disk
2
servers
:
4 CPU
Core
16 GB
RAM
60 GB
disk
1
server:
1 server
:
1
server:
2 CPU
Core
4 GB
RAM
100 GB
disk
4 CPU
Core
4 GB
RAM
100 GB
disk
4 CPU
Core
8 GB
RAM
100
GB
disk
1
server:
1 server
:
1
server:
2 CPU
Core
4 GB
4 CPU
Core
8 GB
4 CPU
Core
12 GB
Page 372 of 4705
Home
Component
POC
Small
Medium
Large
RAM
100 GB
disk
RAM
100 GB
disk
RAM
200
GB
disk
SAP BusinessObjects Web Intelligence Reports Server (for BMC
1 server
Analytics for BSM)
SAP CMS server
server:
server:
2 CPU
Core
4 CPU
Core
4 CPU
Core
4 GB
RAM
8 GB
RAM
12 GB
RAM
60 GB
disk
60 GB
disk
60 GB
disk
1 server with (No HA):
2
servers
2
servers:
2
servers
4 CPU Core
8 GB RAM
100 GB disk
2 CPU
Core
Core
8 GB
4 CPU
Core
4 GB
RAM
RAM
60 GB
8 GB
RAM
60 GB
disk
disk
60 GB
disk
BMC Atrium Orchestrator Configuration Distribution Peer (CDP)

and HA-CDP
:
4 CPU
Hardware considerations for data

The disk sizes in the following table indicate the disk space that is consumed by the data and
indices. Always include additional space for additional data, OS, and other software installed. You
can download a copy of the planning spreadsheet by clicking here.
Consider the following points:
Atrium Web Registry database is not transactional in nature and hence much smaller in size.
For all small, medium, and large deployments, this database can be installed on the same
Microsoft SQL Server instance.
The sizing in the preceding table is based on benchmark tests for specific use cases only.
Transaction log sizing is mainly driven by the following factors, and BMC recommends sizing
transaction log files based these factors:
Database recovery model
Database backup strategy and frequency
Database tier
Component
POC
Small
Medium
Large
Master BMC Remedy AR System Database
1 server:
1 cluster
:
1 cluster:
1 cluster:
16 CPU
Core
16 GB
32 CPU
Core
32 GB
4 CPU Core
8 GB RAM
100 GB disk
8 CPU
Core
Page 373 of 4705
Home
Component
POC
Replicated BMC Remedy AR System
None: Services combined with AR System
Database for Reporting
database
BMC Atrium Orchestrator Database
None: Services combined with BMC Atrium

Orchestrator CDP
Small
Medium
Large
8 GB
RAM
200 GB
disk
RAM
200 GB
disk
RAM
200 GB
disk
1 server:
1 server:
1 server:
8 CPU
16 CPU
32 CPU
Core
8 GB
Core
16 GB
Core
32 GB
RAM
200 GB
RAM
200 GB
RAM
200 GB
disk
disk
disk
1 cluster
:
1 cluster:
1 cluster:
4 CPU
8 CPU
2 CPU
Core
Core
8 GB
Core
16 GB
8 GB
RAM
RAM
200 GB
RAM
200 GB
200 GB
disk
disk
Software requirements
You must meet the following software requirements before installing BMC AR System server:
You must have one of the following databases installed:
IBM DB2
Microsoft SQL Server
Oracle
Sybase
Note
If you try to install the BMC Remedy AR System server on Sybase 15.0.2/
EBF 14328, the installation might fail. You will receive this error message:
Failure during SQL operation to the database : Incorrect
syntax near the keyword 'path'.
For troubleshooting information, see Sybase error 156 in your Sybase
documentation and BMC Remedy AR System error message 552.
The Informix database is not supported.

You must install httpd server before you begin the BMC AR System server installation. For
httpd server requirements details see, Compatibility matrix. You can the find the information
under the Third-Party Product Comparability tab.
Page 374 of 4705
Home
You must have the appropriate software installed before you install BMC Remedy AR
System features and clients as outlined in the following table.
BMC Remedy
Mid tier
AR System
Web
Java
Mail
app
server*
Runtime
Environment
server
(JRE)
Email Engine
Yes
Flashboards
Yes
Mid tier
Yes
Clients
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Developer Studio
Note
For Windows platforms running on an IPv6 server, BMC Remedy AR System requires
Java SE 7. For more information, see Support for IPv6.
* For a list of the compatible web application servers, see Compatibility matrix.
Server operating system platforms

The BMC Remedy AR System server binary for Windows can be installed as a native 64-bit
executable on 64-bit operating-system platforms. The Oracle Solaris, HP-UX (Itanium), and IBM
AIX servers continue to be 64-bit releases.
The installation includes both 32-bit and 64-bit libraries, to support 32-bit and 64-bit applications.
You must install the 64-bit BMC Remedy AR System server on a compatible 64-bit operating
system platform.
Note
For Windows and UNIX, arserverd is the only 64-bit binary, the others are 32-bit.
Therefore, other binaries might have dependencies on some 32-bit operating system
libraries.
For the most up-to-date information about 64-bit BMC Remedy AR System server compatibility with
specific operating systems and versions, see Compatibility matrix in the BMC Remedy ITSM
Deployment online documentation.
Page 375 of 4705
Home
Important
64-bit servers must run with 64-bit database clients.
64-bit database client libraries

The database for a 64-bit BMC Remedy AR System server must use 64-bit database client libraries
. Before installing a 64-bit version of BMC Remedy AR System, make sure that the 64-bit database
client libraries are installed on the computer that will run the BMC Remedy AR System server (
arserver.exe).
Note
Although the 64-bit server can make use of a 64-bit address space, it stores 32-bit values
in the database and exchanges 32-bit values with API clients. It does not store 64-bit
values in the database.
When a 64-bit AR System server is installed, all its 64-bit dependent libraries are installed in a
separate lib64 directory within the AR System server installation directory, except for the
arserver.exe file, which is installed directly in the AR System server installation directory. The
existing BMC Remedy AR System sever installation directory contains all the 32-bit libraries and
other platform processes. The installer sets the <installDirectory> and <installDirectory\>lib64
path variable.
Plug-ins
On the HP Itanium platform (HPIA-64), HP-PA plug-in applications must be configured to run on the
C-based plug-in server. On the other 64-bit platforms, plug-in applications can run on either the
C-based or the Java-based plug-in server.
Java requirement
The BMC Remedy AR System Java-based applications, such as BMC Remedy Mid Tier, Email
Engine, Developer Studio, and Flashboards server, are already compiled as 32-bit for all platforms,
and require that you use a 32-bit JVM on a 32-bit operating system.
The BMC Remedy AR System Java-based applications are compiled as 64-bit for all platforms and
require that you install a 32-bit or 64-bit JVM.
The following are the exceptions for the 64-bit JVM support:
BMC Remedy Email Engine The MAPI protocol is disabled for 64-bit JVM. Requires 32bit JVM if using the MAPI protocol.
You can specify these exceptions in the installer if required for your installation.
Page 376 of 4705
Home
Note
To use the MAPI protocol for BMC Remedy Email Engine, you can install and use a 32-bit
JVM on a 64-bit computer.
Unicode requirements
This following topics help you plan for a Unicode implementation on BMC Remedy AR System:
Unicode compatibility considerations
Unicode support
For more information about Unicode than is described here, see the Unicode Consortium website
at http://www.unicode.org.
Unicode compatibility considerations

The BMC Remedy AR System 7.x and later servers and clients are generally compatible with older
BMC Remedy AR System servers and clients. However, Unicode operations require special
compatibility considerations.
Unicode character sets and lengths

Because strings stored in different character sets have different lengths, older BMC Remedy AR
System products are not compatible with the 7.x and later Unicode BMC Remedy AR System
server. All version 7.x and later products are compatible with the 7.x and later Unicode BMC
Remedy AR System server.
Because lengths in the serialized structures are in terms of Unicode characters and not the code
set of the clients, clients cannot properly deserialize the characters. This problem occurs when
external qualifications are used in table fields and in workflow. Clients using pre-7.0.01 APIs cannot
properly parse these items. The problem occurs with serialized structures that contain 8-bit or
multibyte characters (including, but not limited to, Asian languages, Eastern European, or accented
characters in Western European languages). Serialized structures that contain only 7-bit ASCII
characters (English letters, digits, and punctuation) are not affected.
If you are running an older BMC Remedy AR System product against a 7.x or later Unicode BMC
Remedy AR System server, you should upgrade those products to the 7.x or later release. If you
cannot upgrade these products, patches to the 6.0 and 6.3 APIs are available to make them
compatible with the 7.x or later server. You can obtain them from the patch pages at the Customer
Support website ( http://www.bmc.com/support).
Page 377 of 4705
Home
Unicode and version 6.3.00

Do not use version 6.3 or earlier versions of BMC Remedy Administrator with a Unicode
server. Consider disabling pre-7.x clients altogether if possible.
If you must use version 6.3 or earlier BMC Remedy AR System clients (including BMC
Remedy Mid Tier and BMC Remedy Distributed Server Option) with a Unicode server, they
will only work if the server's operating system has the same character set as the client.
For example, this combination works:
6.3 mid tier
French client operating system
German server operating system
This combination does not work:
6.3 mid tier
French client operating system
Chinese server operating system
Version 6.3 or earlier BMC Remedy AR System clients (including BMC Remedy Mid Tier
and BMC Remedy Distributed Server Option) work with a non-Unicode server only if the
operating system running the client has the same character set as the server's operating
system.
For example, a mid tier running on a French operating system (Western European character
set) can safely contact a non-Unicode server running on a German or English operating
system (also Western European character set), but not one running under a Chinese or
Japanese operating system.
Non-Unicode and version 7.x

A version 7.x or later non-Unicode client can contact a version 7.0.01 or later non-Unicode
server if the operating system running the client has the same character set as the server's
operating system.
For example, if a non-Unicode BMC Remedy AR System server is on a Chinese operating
system, the 7.0.01 version of the mid tier can contact it only if it is installed on a Chinese
operating system.
If a non-Unicode BMC Remedy AR System server is on a German operating system, the
7.0.01 version of the mid tier can contact it only if it is installed on a Western-European
operating system (the same character set as the server's operating system--English or
French or Italian, and so on).
A version 7.x or later non-Unicode client can contact a pre-7.x server if the operating system
running the client has the same character set as the server's operating system.
Page 378 of 4705
Home
A non-Unicode client can access specific language data stored on a Unicode BMC Remedy
AR System server installed on a Unicode database if the non-Unicode client is installed on
the computer with the same character set to which that language belongs.
For example, if an English computer has Unicode BMC Remedy AR System server installed
on it with a Unicode database, and the data stored is German, Japanese, and Russian:
A mid tier that is installed on a Japanese computer (Japanese character set) can work
with the Japanese data on that database.
A mid tier that is installed on a French, English, or Spanish computer (Western
European character set) can work with German data on that database.
A mid tier that is installed on a Bulgarian computer (Cyrillic character set) can work
with Russian data on that database.
Unicode clients and non-Unicode servers

You can run a Unicode client on a non-Unicode server without restrictions.
BMC Remedy AR System components and Unicode considerations

If you run the following BMC Remedy AR System 7.x and later components in Unicode mode, they
do not corrupt data when run against a Unicode-enabled BMC Remedy AR System server:
Plug-in server
DSO
RDP
The following sections discuss considerations for running specific BMC Remedy AR System
components with Unicode.

A BMC Remedy AR System server running in Unicode mode might be required to run another
program (as a Run Process action, for example) and to accept characters written by the program
through the program's standard output.
On UNIX systems, the program must write UTF-8 characters to its output. For example, a BMC
Remedy AR System server running in Unicode mode expects data returned from a Set Fields filter
action to be in UTF-8. A non-Unicode server running in the Japanese locale expects data to be
returned in EUC.
Page 379 of 4705
Home
On Windows systems, BMC Remedy AR System inspects the first 2 bytes of the program's output
to determine if it is UTF-16. If it is UTF-16, BMC Remedy AR System treats it as Unicode.
Otherwise, BMC Remedy AR System treats the program's output as characters from the system's
active code page. For example, a Japanese server runs on a operating system using Windows
codepage 932 (Shift-JIS character set.)
Note
In BMC Remedy AR System 6.x, it is possible to run a BMC Remedy AR System server in
non-Unicode mode with a Unicode database. In BMC Remedy AR System 7.x and later,
this type of configuration is not supported.
Plug-in server
Two codesets affect the plug-in server and the plug-ins that run under it:
The codeset in which the server provides characters when it calls the plug-in's callback
routines
The codeset that the plug-in uses when it makes API calls to the server
The server always uses its own codeset when delivering characters to plug-in callback routines.
Therefore, a Unicode server always delivers characters in the UTF-8 codeset.
Mid tier
Version 7.x and later of the mid tier is a Unicode client for the BMC Remedy AR System server. A
single mid tier can manage clients and transfer data in any language supported by BMC Remedy
AR System.
The mid tier's Flashboards service renders characters for display. Make sure that fonts are
available for the characters of all languages in which you provide Flashboards.
API programs
When operating in Unicode mode, the API accepts and returns characters in the UTF-8 character
encoding. It does not support the UTF-16 character encoding.
runmacro
The runmacro program, which is sometimes used to do batch exports of data, is not Unicode-safe.
Do not use runmacro with a Unicode server.
BMC Remedy ODBC driver

The BMC Remedy ODBC driver is a multi-threaded, ODBC 3.5-compliant Unicode driver that runs
a BMC Remedy AR System API client under Windows.
Page 380 of 4705
Home
If you connect ANSI applications to a BMC Remedy AR System Unicode server through the
Remedy ODBC driver, any data transferred is converted from ANSI to UTF-16, and then from UTF16 to UTF-8. If the BMC Remedy AR System server is non-Unicode, then the data is converted
from ANSI to UTF-16, from UTF-16 to UTF-8, and then from UTF-8 to the server's native character
set.
Utilities
The following utilities can be used with Unicode servers:
artext
arhelp
archgsel
archgid
arworkflow
ardisabled
arlabel

BMC Remedy Developer Studio is Unicode-safe. It has no character set restrictions.
If you internationalize BMC Remedy AR System and you continue to use the BMC Remedy
Administrator tool from versions prior to 7.5.00, you must use object names that use ASCII
characters. For more information about Unicode and BMC Remedy AR System 7.1.00, see the
BMC Remedy Action Request System 7.1.00 Installing Guide .

BMC Remedy Data Import is Unicode-safe.
BMC Remedy Data Import is also Unicode-safe when you run it from the command line (
arimportcmd). For BMC Remedy AR System 7.6.03 and later, use the Java-based import utility.
For more information, see Enabling the Data Import utility.
BMC Remedy AR System Administration Console

The BMC Remedy AR System Administration Console form is Unicode-safe only when run from a
version 7.x or later mid tier. For more information about the console, see Configuring AR System
servers.
BMC Remedy Migrator

BMC Remedy Migrator is Unicode-safe.
Page 381 of 4705
Home
Unicode support
A product that provides Unicode compliance is written using the Unicode character coding system,
which means Unicode data can flow from database to client without any conversion occurring. A
product that provides Unicode database support enables the database to contain Unicode
characters but converts them between the database and the product. Any product that accesses
the database, however, still uses a native character set.
The Unicode database option enables you to have multi- and single-byte forms, data, and workflow
stored in the same database or database instance. Unicode database support in AR System
enables you to use multiple languages on one AR System server. You are no longer restricted by
the operating system's locale.
The following section explains the Unicode support for BMC Remedy AR System.
Unicode database support for forms
Unicode support for AR System database types
Database migration to Unicode
Migrating an Oracle database to Unicode
Migrating a Microsoft SQL Server database to Unicode
Migrating a DB2 database to Unicode
Migrating a Sybase database to Unicode
Unicode database support for forms

The Unicode database option enables you to have multi- and single-byte forms, data, and workflow
stored in the same database or database instance.
Note
To use BMC Remedy AR System with the Unicode database option to support multiple
languages using a shared database, you must install an English version of BMC Remedy
AR System server before you install multi-language AR System servers.
Unicode database support in BMC Remedy AR System 7.0.00 and later enables you to use
multiple languages on one AR System server. You are no longer restricted by the operating
system's locale.

Each database type supported by BMC Remedy AR System supports Unicode at one of the levels
listed in the following table.
Page 382 of 4705
Home
Unicode
support
level
Database
type
Comments
Database
instance
Sybase,
Oracle
For these database types, you must configure the database instance before you install the new AR
System database.
Note
(Oracle only) If you use an Oracle AR System database with the Unicode database option,
problems might occur if the NLS_LENGTH_SEMANTICS parameter is not set to BYTE in the
AR System database and in the database server instance. See Preparing to install on a Unicode
database and Preparing to upgrade on a Unicode database.
Specific
column
type
Microsoft
SQL
Server
Uses Unicode data types nchar, nvarchar, and ntext.
Database
DB2
No database configuration required.
During installation, the BMC Remedy AR System installer gives you the option of creating a
Unicode database. You can safely do this if you meet the following requirements:
You are not installing on an existing AR System database.
Your database supports Unicode at the column or tablespace level, or you configured your
database instance for databases that support Unicode at the database-instance level.
Warning
If you have an AR System database, you must first migrate it to Unicode before upgrading
your AR System server. If you choose the Unicode database option during an upgrade
install against a non-Unicode AR System database, you will corrupt your database. See
the next section, Database migration to Unicode.
Database migration to Unicode

If you are upgrading an BMC Remedy AR System that already has a database, you must migrate
the database to Unicode before proceeding with the BMC Remedy AR System upgrade installation.
This ensures your data integrity.
The following procedures describe how to migrate your database to Unicode database. For more
details, see your database documentation.
Page 383 of 4705
Home

To migrate an Oracle database, follow these general steps. For detailed information, see your
Oracle documentation.
1. Confirm your Unicode Oracle database is using AL32UTF8 character set.
The character set is defined during the creation of the Unicode database. There is no
change on a character set for an existing database. During the creation of the database, the
response to the prompt for character set is AL32UTF8. The Oracle database engine
performs any conversion required during import of the original (non-Unicode) into the new
database.
2. Perform a full export and import on the whole database.
Note
UTF-8 columns usually store fewer characters compared to non-Unicode columns.
In these cases, you might be introducing data truncation. For more information, see
your Oracle documentation.

To migrate a Microsoft SQL Server database, follow these general steps. For detailed information,
see your Microsoft SQL Server documentation.
1. Create columns in the target database that correspond to the source database as shown in
the following table.
Source and target column database types
Source column type
Target column type
char
nchar
varchar
nvarchar
text
ntext
2. Migrate your data on a column-by-column basis.
Warning
If the database has Unicode and non-Unicode columns, BMC Remedy AR System
will not work.
Page 384 of 4705
Home

For DB2 databases, the database character set is a configuration parameter that you cannot
update. Therefore, existing non-Unicode DB2 AR System databases cannot be migrated to
Unicode.

To migrate a Sybase database, follow these general steps. For detailed information, see your
Sybase documentation.
1. Export the database.
2. Change the Sybase default character set to UTF8.
3. Import the data back into the Sybase database.
4. Update the tables containing text columns.
Portmapper service introduction

A portmapper functions as a "directory" of services and the ports on which those services are
running. Processes can opt to register or not register their location with a portmapper. A common
reason for not registering with a portmapper is security.
If a BMC Remedy AR System server is registered with a portmapper, your clients do not need to
know what port the server is listening on because the clients can identify the port by using the
portmapper and direct API calls to the appropriate TCP port. If a server is not registered with a
portmapper, you must assign a TCP port number to that server. Otherwise, the system must search
for an open port to communicate on each time the server is restarted. Your clients will not know
where to find your AR System server because the port might be different if the AR System server is
restarted.
Registering with a portmapper and assigning TCP port numbers are not mutually exclusive options.
You can do both. If you specify a particular port for a server and register the server with a
portmapper, clients within the firewall do not need to be configured to access the specified port
number.
If the AR System server is not registered with a portmapper:
Client processes must be able to identify the port to communicate on to contact the server.
For more information about configuring ports for the client, see Understanding port numbers.
Macros that a UNIX User tool runs as part of an escalation or filter run process cannot find
the server. To fix this, register the server with a portmapper. You can also use the runmacro
utility, which has a command-line port setting.
See Connecting to AR System at a specific TCP port .
The client/server interaction still requires the use of RPC when specific ports are used.
Page 385 of 4705
Home
Windows and portmapper services

Because many Microsoft Windows environments do not have a portmapper service, one is provided
with the AR System server. If you already have a portmapper, AR System registers with it if
requested. If not, you can specify that the AR System Portmapper service needs to be started and
used as the portmapper for the system.
No AR System Portmapper exists for UNIX because all UNIX operating systems include a
portmapper as a standard feature.
Note
By default, Windows 2008 comes with a portmapper installation. To use the AR System
portmapper, you must uninstall the Microsoft portmapper and then continue with the AR
System installation; otherwise, you can continue with the AR System installation without
the AR System portmapper.
Connecting to AR System at a specific TCP port

When using an API client on a UNIX server, you can connect to the AR System at a specific TCP
port by setting the AR TCP Port variable.
The following strategies require that all servers that the client uses are on the same port.
For the C shell, use the following commands to set ARTCPPORT:
setenv ARTCPPORT <TCPPortNumber> aruser &
For the Bourne shell, use the following commands to set ARTCPPORT:
ARTCPPORT=<TCPPortNumber>; export <ARTCPPORT> aruser &
For an API program, you can set variables through a shell or from within the program.
BMC Remedy Migrator memory usage and disk space

requirements
Before installing Migrator, make sure that your computer has the following memory and disk space:
Memory 512 MB minimum; 1 GB recommended.
Page 386 of 4705
Home
Disk space At least 1 GB free space, 5 GB recommended. If the option to delete

database and dependency files is disabled (which means that these files are retained), you
might need more disk space (between 5 GB and 10 GB), depending on the size of the files
you are using.
Security
The following topics contain information and instructions on BMC Remedy Action Request System
security planning:
Security architecture
Security considerations for BMC Remedy AR System
General security guidelines
BMC Remedy Encryption Security modifications to the JRE
Standard security modifications to the IBM JDK
Security architecture
This topic describes the BMC Remedy AR System security architecture.
Note
The IT environment and network infrastructure in which your BMC Remedy AR System
runs must be properly secured and include standard IT network security tools and
systems such as firewalls and intrusion detection systems (IDS).
System architecture
The BMC Remedy AR System architecture is multi-tiered; it consists of a Presentation layer, a
Logic layer, and a Data layer as shown here.
BMC Remedy AR System security architecture diagram
Page 387 of 4705
Home
Presentation layer
The Presentation layer consists of the web browser client connected to the mid tier with secure
socket layer (SSL) encryption. You must implement SSL to secure the connection between the
browser and the web server. BMC supports any SSL version that is supported by the HTTP web
services vendors listed in the BMC Remedy AR System Compatibility Matrix (see Compatibilty
matrix in the BMC Remedy ITSM Deployment online documentation).
Logic layer
The Logic layer includes instances of a mid tier, a JavaServer Pages (JSP) engine, a web server,
and the BMC Remedy AR System server. The JSP engine and accompanying servlets provide
dynamically generated HTML and XML documents in response to web client requests. The mid tier
installer includes and can automatically install a bundled version of the Tomcat web server.
The mid tier translates client requires, interprets responses from the BMC Remedy AR System
server, handles web service requests, and runs server-side processes that present BMC Remedy
AR System functionality to the client from the BMC Remedy AR System server. The server
executes workflow and business logic that define all BMC Remedy AR System applications.
Because all BMC Remedy AR System clients are API-based, turning on encryption ensures that all
interactions with the server are encrypted.
Data layer
The Data layer consists of one or more databases, which perform data storage and retrieval
functions. The BMC Remedy AR System server connects to the Data layer using database client
API libraries. The server can work with the database encryption libraries used to protect data that is
transmitted between the server and database.
Security considerations for BMC Remedy AR System

When planning an enterprise setup, consult the following topics for security guidelines on the BMC
Remedy Action Request System (AR System) components:
BMC Remedy AR System security
Mid tier security
Approval server security
BMC Atrium CMDB security
Email Engine and Assignment Engine security
Additional Information
Page 388 of 4705
Home
BMC Remedy AR System security

Security is an important consideration for AR System. The AR System server addresses security
through:
Access control Protects AR System data.
BMC Remedy Encryption Security Protection for data that is passed over the wire. AR
System client libraries contain built-in encryption capabilities that you can enable to secure
the connection to the AR System server. Higher levels of encryption (BMC Remedy
Encryption Performance Security or BMC Remedy Encryption Premium Security) are
available if you need stronger encryption. AR System is also tested with database encryption
products from your database vendor to ensure that this connection can be encrypted.
Protection of the server and network resources to which AR System has access AR
System can be configured to help secure the network resources used by the product. The
system can be configured so it runs with limited access privileges, and has access only to
certain resources on the host machine. This prevents a user from running malicious scripts
or programs on the installed machine. For data and resource protection configuration options
, see Configuring clients for AR System servers and BMC Remedy AR System configuration
files.
Password security AR System ensures that passwords are always encrypted. An MD5
hash of passwords is stored in the database, ensuring that the system (and therefore a
reader of the database) cannot retrieve passwords. In addition, the AR System server allows
you to use policies to enforce password changes. For password policy information, see
Enforcing a password policy introduction.
FIPS Compliance In version 7.5.00, AR System was enhanced so that data transmitted
between AR System servers and clients can comply with FIPS 140-2 encryption
requirements. BMC Remedy Encryption Performance Security now includes a FIPS
encryption option. For more information, see FIPS encryption options.
Mid tier security

The mid tier provides a secure environment by encrypting sensitive data. All passwords are stored
in configuration files as encrypted strings. For the web server, you must add any additional security
if required.
Important
BMC recommends to use a secure socket layer (SSL) or HTTPS connection to encrypt
the data between the web server and the browser client.
Enabling SSL can impact performance due to the extra overhead required to encrypt and decrypt
on both ends.
Page 389 of 4705
Home
Note
You can now log on to BMC Remedy Mid Tier using only HTTP POST requests.
Use BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security
to encrypt communication between AR System components, including the mid tier.
When securing the mid tier, consider these tips about:
SSL
XSS
WebDAV
HTTP transport
SSL
The mid tier works with SSL. SSL encryption is a few layers below the web application (
between the HTTP web server and the browser client sending the HTTP requests). All web
server vendors provide a method to create and store certificates to enable SSL encryption
over HTTP.
Configuring the environment for SSL support is beyond the scope of any guidance BMC
provides.
Apache HTTP server has an SSL mode and, when that mode is enabled, the server can
cache the encryption information to speed up performance.
XSS
Cross-site scripting (XSS) is a type of computer security vulnerability (typically found in web
application) that allows code injection by malicious web users into the web pages viewed by other
users. Examples of such code include HTML code and client-side scripts.
Cross-site scripting is addressed in every release of the mid tier by running the code through a tool
to identify potential problems to ensure no vulnerability is introduced. All user-supplied HTML
special characters are encoded into character entities, thereby preventing them from being
interpreted as HTML.
WebDAV
Web Distributed Authoring and Versioning (WebDAV) extensions on web servers allow users to
collaboratively edit and manage files on remote web servers. If your web servers has the WebDAV
extensions enabled by default, they should be disabled.
Page 390 of 4705
Home
HTTP transport
To ensure that the HTTP transport method POST is used for XML/HTTP requests in the browser,
you must set the arsystem_xmlhttp.get flag in the Config.properties file to false.
Knowledgebase article, KA333059, What are the steps to install Apache 1.3.x on Solaris
with SSL
Knowledgebase article, KM-000000018212, How to Install Microsoft Certificate Server and
Key Management Server if SSL on IIS
Encryption security online documentation:
How BMC Remedy Encryption Security enables secure communication between the
client and server
Installing BMC Remedy Encryption Security
Upgrading encryption security
Troubleshooting encryption security
Warning
If you use the pwd parameter in a URL, passwords are exposed by the browser in the
locator and in bookmarks or favorites. For URLs that include the pwd parameter, use https
:// (https://*).
Approval server security

The approval server provides a secure environment by encrypting sensitive data. For example, the
password is always encoded and never saved in any file as readable text. You can add any
additional security if required.
Use BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security
to encrypt communication between AR System components, including the Approval server.
Approval server uses the encrypted password for the Remedy Application Service user, which is
available in the ar.cfg (ar.conf) file for making any backend calls to AR System.
Page 391 of 4705
Home
BMC Atrium CMDB security

The CMDB Class Manager controls permission to access CMDB classes and attributes. This is
done by using Role IDs associated with Role definitions from the BMC:Atrium CMDB deployable
application. Two roles (-1090 and -1091) are defined to allow unlimited read or read/write access to
CMDB data. Two other roles (-1098 and -1099) allow read or read/write access subject to row-level
permission. The CMDB administrator should assign these roles to the appropriate groups in
production and test environments.
Email Engine and Assignment Engine security

For information on Email Engine security, see Securing incoming and outgoing email.
For information on Assignment Engine security, see Configuring the Assignment Engine.
Additional Information
For more information on security guidelines, see the blog Choose your request methods carefully
shared on BMC Communities.
General security guidelines

This topic presents security guidelines to consider when using BMC Remedy Action Request
System (BMC Remedy AR System).
Encryption
Secure socket layer
Secure Tomcat installation
Session management
HTTP TRACE disabled
Secure cookie filter
XSS filter enhanced
Data visualization module plug-ins
Mid-tier Return Back parameter
Mid tier and portlet containers
Mid tier access prevented by some security software
Adding inclusion list for Mid Tier
Related topic
Encryption
BMC Remedy AR System provides BMC Remedy Encryption Performance Security and BMC
Remedy Encryption Premium Security components that you can install to provide well-protected
communication among BMC Remedy AR System components.
BMC Remedy Performance Security includes a Federal Information Processing Standard (
FIPS) encryption option. When this option is enabled, network traffic is encrypted using
Advanced Encryption Standard (AES) cipher-block chaining (CBC) with a 128-bit key for
Page 392 of 4705
Home
data encryption and a 1,024-bit modulus for the RSA key exchange. It uses a secure hash
algorithm (SHA-1) for message authentication. This option supports the minimum FIPS 1402 encryption requirements.
BMC Remedy Premium Security includes a premium FIPS encryption option. When this
option is enabled, network traffic is encrypted using AES CBC with a 256-bit key for data
encryption and a 2,048-bit modulus for the RSA key exchange. It uses SHA-1 for message
authentication. This option supports premium FIPS 140-2 encryption requirements.
Secure socket layer

Use secure socket layer (SSL) to encrypt the traffic between the HTTP web server and the browser
client. Configuring the environment for SSL support is beyond the scope of guidance that BMC
provides.
Note
Enabling SSL can impact performance due to the extra overhead required to encrypt and
decrypt traffic.
Secure Tomcat installation

Because the Tomcat JSP engine is bundled with the mid tier, the BMC Remedy AR System
installation script performs the following clean-up tasks to ensure that security issues in Tomcat are
resolved:
Removes the contents of the root directory from the <TomcatInstallationDirectory>/
webapps directory
Adds an index.html file to the root directory, which appears if the administrator enters http://
<localhost>:8080 in a browser and Tomcat is running properly
Removes the tomcat-docs directory from the <TomcatInstallationDirectory>/webapps
directory
Removes the host-manager and manager web default web applications from the <
TomcatInstallationDirectory>/webapps/server/webapps directory.
Removes the deployment descriptors for the host-manager and manager applications,
host-manager.xml and manager.xml, from the <TomcatInstallationDirectory>/conf/
Catalina/<localhost> directory
Removes all unused ports from service (in particular, port 8080), stripping the default
server.xml configuration file from the Tomcat installation directory so that the installation
supports only the mid tier
These tasks make the Tomcat installation more secure; however, determining whether the mid tier
or the Tomcat engine suffered an incorrect installation can be difficult, because all extraneous
services are removed. To ease this problem, an index.html page is also installed that is displayed
when Tomcat is running.
Page 393 of 4705
Home
If the mid tier fails to run after installation, complete the following steps to determine whether the
problem is the Tomcat installation or the mid tier installation:
1. Stop Tomcat.
2. Open the <TomcatInstallationDirectory>/conf/server.xml file and uncomment the
Connector entry at port 8080.
3. Restart Tomcat.
4. In a browser on the same computer as the Tomcat installation, go to http://<localhost>:
8080.
If the Tomcat engine is running correctly, the following message is displayed in the browser:
Tomcat is running
Session management
If a session between the web browser and the mid tier is idle for 90 minutes (the default setting) or
if you close a browser, the BMC Remedy AR System license is released. To change the default
settings, you can configure idle time parameters in the Mid Tier Configuration tool.
By default, all SessionID cookies are marked as HTTPOnly to prevent unauthorized access to the
SessionID cookies.
HTTP TRACE disabled

HTTP TRACE is a default function in many web servers, primarily used for debugging. The client
sends an HTTP TRACE request with all header information, including cookies, and the server
simply responds with that same data.
To prevent cross-site tracing (XST) attacks that use XSS and the HTTP TRACE function, the HTTP
TRACE function in the mid tier is disabled by default. To disable the HTTP TRACE function
completely, you must also disable HTTP TRACE on the application server hosting the mid tier. For
information about how to enable the TRACE function, see HTTP tracing in the mid tier .
Secure cookie filter

To mark all cookies as secure, you must uncomment the secure cookie filter.
Note
Enable this filter only when BMC Remedy Mid Tier is configured to work with HTTPS or a
reverse proxy configured to work with HTTPS. When using a reverse proxy, you can
access the mid tier either through a proxy or by connecting to the computer that hosts the
mid tier.
If the reverse proxy is configured with HTTP, do not enable the secure cookie filter and
access the mid tier either by connecting through the URL that is configured as the proxy (
for example, http://xyz:8080/arsys) or by accessing the mid tier from the same computer
on which it is installed (for example, http://<localhost>:8080/arsys).
Page 394 of 4705
Home
If the reverse proxy is configured with HTTPS, you must enable the secure cookie filter
and access the mid tier only by connecting through the URL that is configured as the
proxy (for example, https://xyz:8080/arsys). You cannot, however, access the mid tier
from the same computer on which it is installed.
To mark cookies as secure

1. Edit the web.xml file in the <midTierInstallDirectory>/WEB-INF directory.
2. Locate the following secure cookie filter entry:

3. Remove <!- and -> from before and after the entry to uncomment the entry.
4. Save the web.xml file.
5. Restart the mid tier.
XSS filter enhanced

By default, the mid tier contains an XSS filter that is frequently updated with additional characters.
Data visualization module plug-ins

By default, security is disabled for data passed through the mid tier by using the data visualization
model plug-ins. To enable mid-tier security for the plug-ins, you must add the following option to the
config.properties file:
arsystem.plugin_securitycheck=true
Mid-tier Return Back parameter

The default value of the Return Back parameter is false. You must change the value to true to
prevent the mid tier from allowing a user to submit a URL containing a Return Back parameter.
To change the value, add the following setting to the config.properties file and restart the mid tier:
arsystem.allow.returnback.url=true
Page 395 of 4705
Home
If the default value is not changed, arsystem.allow.returnback.url could allow users to

alter a base return URL when the URL is sent back to the browser from the web server. This
behavior could make the system vulnerable to a phishing attack.
Mid tier and portlet containers

To prevent frame phishing vulnerabilities in the mid tier, the mid tier verifies that it is not placed
inside a portlet container or displayed in third-party frames or iFrames. If a portlet container,
third-party frame, or iFrame is detected, the mid tier automatically disconnects from the object and
displays the content in a single window.
Mid tier access prevented by some security software

Mid tier access might be prevented if your security software blocks URLs with special characters
such as < (left angle bracket), > (right angle bracket) and '(apostrophe). To resolve this issue,
change the arsystem.xmlhttp.get setting in the config.properties file from true to false and
enable the use of HTTP POST for backchannel calls.
Note
Enabling the XSS filter impacts the BMC Remedy AR System server performance.
To change the arsystem.xmlhttp.get setting

1. Shut down the mid tier.
2. Open the config.properties file, located in the <MidtierInstallDirectory>/WEB-INF/classes
/ directory.
3. Change arsystem.xmlhttp.get=true to arsystem.xmlhttp.get=false.
To enable the XSS filter

1. Edit the web.xml file in the <MidtierInstallDirectory>/WEB-INF/ directory.
2. Enable the cross-site scripting (XSS) filter by deleting the lines (in boldface font) that
comment out the filter in the XSS Filter code block as shown in the following example:
Example

3. Save the web.xml file.

Adding inclusion list for Mid Tier

You can add an inclusion list of URLs to be redirected to when you log out of the mid tier. To add
an inclusion list, add the following property in the <midTierInstallDirectory>/WEB-INF/classes/
config.properties file:
arsystem.inclusion_goto_urls=http://www.google.com,http://www.microsoft.com,
http://<midTierServer>/
Note
The inclusion list must also contain the mid tier's own URL to allow the mid tier to redirect
to itself.
Related topic
Cookies used by BMC Remedy Mid Tier

BMC Remedy Encryption Security options include:
Standard security
BMC Remedy Encryption Performance Security
BMC Remedy Premium Encryption Security
Federal Information Processing Standard (FIPS) encryption options
These options are described in How BMC Remedy Encryption Security enables secure
communication between the client and server .
Page 397 of 4705
Home

The following table will assist you in planning your BMC Remedy Encryption Performance Security
or BMC Remedy Encryption Premium Security installation. It shows how the encryption security
policy affects client-server communication. The Security Policy value in the Encryption tab
determines whether encryption is required to communicate with the server.
Encryption security policy and client-server interaction
Available client-server communication
Server
version
Security
policy
8.1 client with encryption
8.1 client
without
5.1.2 -7.1.00 client with

encryption
encryption
8.1
5.1.27.1.00
Optional
(Default) Encrypted if client

encryp-tion level matches
Unencrypted
server configuration OR
Unencrypted 1
Unencrypted 1
FIPS not
enabled 2
)
server configuration OR None
None
Required (
FIPS

enabled 2
)
Disabled
Optional
Unencrypted
Unencrypted
None
None
None
None
None
None
Unencrypted
Unencrypted
Unencrypted
Unencrypted
Unencrypted

Unencrypted

Unencrypted
Unencrypted
None
None
Unencrypted 1
Unencrypted 1

None
Pre5.1.2

Required (
Required
Pre-5.1.2
client
without
encryption
None
5.1.2 -7.1.00
client

None
Disabled
Unencrypted
Unencrypted
Unencrypted
Unencrypted
Unencrypted
NA
Unencrypted
Unencrypted
Unencrypted
Unencrypted
Unencrypted
When a server's Security Policy is Optional and a client cannot support the encryption algorithm
required by the server, their communication is unencrypted. For example, if the server is configured
to use BMC Remedy Encryption Premium Security AES or RC4 algorithms and the client has only
BMC Remedy Encryption Performance Security installed, the server will not "drop down" to
Page 398 of 4705
Home
Performance-level algorithms. Instead, communication between the server and client will take place
in plain text.
2
For information about FIPS, see FIPS encryption options and Activating FIPS compliance.

The DES and RC4 algorithms used by BMC Remedy Encryption Performance Security and BMC
Remedy Encryption Premium Security are compatible with BMC Remedy AR System 5.1.2 and
later. Therefore, if you have a 5.1.2 or later installation that uses encryption, you can install clients
and servers from the current version without upgrading all products to the current version.
Pre-7.5.00 clients and servers cannot use the AES algorithm to exchange data.
AR System 7.5.00 and later clients and servers cannot exchange any encrypted data with 5.0 or
5.1 clients and servers.
Encryption libraries are version-specific to the servers and clients on which they are used:
If a client from a version prior to 8.0 exchanges data with an 8.0 or later server that has BMC
Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security,
the client must use the encryption library file for its version, not for 8.0 or later.
(Windows only) If an application uses AR System components whose version numbers differ
and you need BMC Remedy Encryption Performance Security or BMC Remedy Encryption
Premium Security, you must add encryption libraries for all the versions. For example, if the
application uses the 7.1.00 AR System plug-in server and a 7.0.00 plug-in, you must add the
arencrypt71.dll and arencrypt70.dll libraries to your environment.
Important
Compatibility information in the product documentation is subject to change. For the latest,
most complete information about what is officially supported, see Compatibility matrix in
the BMC Remedy ITSM Deployment online documentation.
BMC Remedy Encryption Security modifications to the JRE

When you install BMC Remedy Encryption Performance Security or BMC Remedy Encryption
Premium Security on Java-based components, the JDK JRE and public JRE directories that you
specify during installation are modified as follows:
These providers are added:
RSA Crypto-J 4.0 FIPS-140
Bouncy Castle JCE 133 (AIX only)
Page 399 of 4705
Home
These files are added:

jsafeJCEFIPS.jar
bcprov-jdk15-133.jar
These JCE Unlimited Strength Jurisdiction policies are changed:
US_export_policy.jar
local_policy.jar
Warning
If you update the JRE or JDK on a computer on which the current version of
BMC Remedy Encryption Performance Security or BMC Remedy Encryption
Premium Security is installed, these modifications might be lost. To reapply
them, you must reinstall BMC Remedy Encryption Performance Security or
BMC Remedy Encryption Premium Security.
Standard security modifications to the IBM JDK

Standard security is built into the BMC Remedy AR System API. When you install a Java-based AR
System component that uses an IBM JDK on a platform such as AIX, these items are added to the
IBM JDK:
Bouncy Castle JCE 133 provider (AIX only)
bcprov-jdk15-133.jar file
Warning
If you update the JRE or JDK on a computer on which Java-based AR System 8.1
components are installed, these modifications might be lost. To reapply them, you must
rerun the component's installer.

SSO is a method of system and resource access control, used to authenticate users one time for
access to any resource residing within the bounds of the system. In simpler terms, SSO allows
system users to authenticate once and gain access to multiple resources. SSO advantages include:
Improved user productivity
Improved system security
Improved administration process
Page 400 of 4705
Home
BMC Remedy AR System can be integrated into an single sign-on (SSO) environment with a
plug-in that verifies user credential authentication. The plug-in acts as a layer between the SSO
service and the server. Because each SSO environment varies greatly, there are few applicable
standards for SSO integration. To ease the process of integrating into an SSO solution, AR System
provides vendor agnostic hooks for SSO integration.
A full SSO solution, includes BMC Atrium and uses what AR System provides. BMC Support also
has a simple proof-of-concept example, which is fully functioning. The example is not a supported
product and there is no implied support if you use it. For more information, see the Knowledgebase
article, KA286851.
Starting with BMC Remedy AR System version 7.6.04, the AR System server is integrated with the
BMC Atrium Single Sign-On (SSO) solution by introducing a Atrium SSO plug-in. To configure this
plug-in, you must provide values for certain configuration parameters on the new Atrium SSO
Integration tab, located on the AR System Administration: Server Information form.
Alternatively, you can also configure the Atrium SSO server while installing the AR System server.
To do this, you must provide the values for the configuration parameters on the new Atrium SSO
Configuration screen after selecting the Configure Atrium SSO check box.
The following table describes the components of an SSO solution.
Note
Some solutions will not include all of the listed components.
SSO Components
Component
Description
Authentication
The system verifies user identity, and provides access based on permissions awarded. Most SSO approaches
centralize authentication.
Authorization
Authorization can be centralized or managed by the target. Some solutions centralize user privilege
administration while the authorization remains with the target.
Login
automation
Sign on process automation is manifest via entry of a user name and password. Scripts are stored on a special
authentication server. The user signs on to that server using the client. The server tells the client software
which resources the user may access. When a resource is requested, the client software uses login
credentials and scripts supplied by the authentication server to establish the connection to the relevant target
resource (server, host, domain or application) on the user's behalf. From the perspective of the target
resources, little or nothing changes. Each is still authenticating as before and maintains its own set of user
privilege information.
Centralized
Security
Administration
Many vendors sell complementary centralized security administration tools that use agents on the target
systems to enable central setup and termination of accounts. These tools allow role-based administration of
user accounts, often storing account and privilege information in a centralized directory. In some cases these
administration tools are completely separate, in others they are more tightly integrated.
Page 401 of 4705
Home
Component
Description
Token-based
authentication
When the user is identified, the service creates a non-forgeable, non-reusable token to identify the user to
authorized resources.
Certificate-based
Certificate-based authentication is centralized, role-based administration of user privileges across several
authentication
resources.The SSO system identifies the user and brokers trusted credentials to the application, masking the
authentication process from the application.
Client Agent
The client agent is a web server plug-ins or agents that communicate with the authentication server.
The following table describes the components of an SSO solution.
Note
Some solutions will not include all of the listed components.
To integrate successfully with AR System, the SSO solution you choose must provide the following
components:
SSO components needed for AR System Integration
Component
Description
Service
The service is a web application to authenticate the user. Generally this web application is connected to an LDAP
directory service because LDAP is the popular choice for authenticating users in web applications.
Interceptor
The interceptor intercepts all unauthenticated requests and routes them to the service for authentication.
Client
library
The client library is used by the service to authenticate the user and to make the exchange of the SSO token for
the user credentials. In some solutions, the credentials are embedded in the request as HTTP headers, eliminating
the need for a client library. However, the HTTP header keys must be known for credentials extraction.)
When working with SSO, remember these tips:

Any SSO application can work with the AR System if a plug-in (that you or another
third-party writes) supports it. You can hook the SSO application into a generic
public Authenticator Java Interface and code the AR System external
authentication (AREA) plug-in API to verify credentials passed to it from the web
client through the mid tier.
Make sure the mid-tier timeout is less than or equal to the SSO timeout.
Sometimes SSO and proxy caches can conflict.
Page 402 of 4705
Home
Plug-ins for SSO integration

BMC AR System server can be integrated into an SSO environment using a generic public
authenticator Java Interface and the AR System external authentication (AREA) plug-in API. The
AR System server passes verified credentials, via the AREA plug-in, from the web client through
the mid tier. The following steps describe the process for integrating AR System server into your
SSO environment:
1. Configure the SSOAuthenticator to obtain the user name and authentication string.
Details about this step are described in Configuration requirements for the mid tier in an
SSO environment.
2. Obtain a user name. Authentication and other information is usually obtained to verify the
user. Details about this step are described in Specify your authenticator implementation.
3. On the server, given the set of credentials and using the technology you are integrating with,
validate that the user is a valid user. Details about this step are described in Using the AREA
plug-in for user authentication.
4. Configure the server options so that the server will pass the credentials to your
authentication check and allow the code to perform the authentication. Details about this
step are described in Configuring AR System server in the SSO environment .
Multiple authentication methods

You might be using several authentication methodologies in one centralized environment. For
example, your implementation may leverage an SSO environment within the office, but not allow
SSO access outside of the physical office environment. This strategy allows you to mix multiple
methods and let the authentication automatically validate against each, by linking to technologies
on the client to provide a complete, end-to-end implementation.
Custom API program

The AR System environment provides interfaces for Microsoft Windows and web clients. The
Custom API program provides an option for many other clients.
Detailed implementation for each possible client is outside the scope of this document, however the
implementation principles are the same.
There must be some way for the client to obtain login information. This can be hard coded, a
user prompt, or an interface to interact with an SSO service or to obtain the user name,
password, and authentication information.
The client program can determine how to obtain the login information, but the program must
obtain it in a format that the server validation logic can interpret.
Third party AR System server clients must be investigated to determine if you can integrate
with the same alternate login techniques of the clients provided with the system.
Note
Page 403 of 4705
Home
For more information see Developing an API program.
SSO user request event sequence

The following sequence of events comprises a user request in an SSO environment:
1. The user requests a resource from an application deployed in an SSO environment.
a. If the active session is already established, the user is granted access to the resource
.
b. If the user does not have an active session (initial log on or previous session expired),
the request is intercepted and then routed to the SSO service.
2. The SSO service challenges the user for credentials by presenting a login page.
3. The user provides the credentials.
4. The SSO service queries the directory service to obtain authentication of the user, based on
the provided credentials.
a. If the credentials are confirmed, the SSO service routes the request back to the
server, embedding some type of SSO token (specific to the protocol used) in the
request.
b. If the credentials are not confirmed, then user is denied access.
5. The server detects the SSO token in the request (indicating that the user has been
authenticated) and routes the original request (now paired with the SSO token) to the web
application.
This sequence of events is described visually in the following flow chart:
SSO user request event sequence
Implementing SSO integration with AR System server

This section discusses the following implementation options:
Web client integration
Page 404 of 4705
Home
Integrating the mid tier into an SSO environment

Windows client integration
Custom API code samples
Tip
A full SSO solution that leverages the BMC Remedy AR System API is available on the
BMC Developers Community. It includes a fully functioning proof of concept example.
Note that the example is not a supported product and there is no implied support if you
use it. For more information, contact BMC Support.
Web client integration

For your SSO solution to integrate with a web client, it must include the following components:
SSO Service
The SSO service is a web application to authenticate the user. Generally, the LDAP protocol
is used for authenticating users against a directory service
Client Library
The client library is a database of authorized users used to authenticate information,
supplied by the user when requesting access to the application.
Interceptor
An interceptor routes the authenticated requests to the SSO service for authentication.
When a web application is placed under an SSO service authentication tasks normally
performed by the application are routed to the service via HTTP request. Every request
routed to the web application is guaranteed as authenticated by the SSO service.
When the interceptor component is installed on the application server hosting the web
application to be placed under SSO, the following parameters are required:
URL of the web application (the SSO service)
URL to be placed in the SSO environment
The above parameters are configured when the interceptor is installed on the application server
that hosts the web application that will be served in the SSO environment. After the interceptor is
configured, all requests for the applications placed under SSO are intercepted and routed for
authentication, if not already authenticated.
Sequence of authentication events in an SSO environment

1. The user requests access to the web application.
2. The interceptor routes the authenticated requests to the SSO service for authentication, if
the request is not authenticated, or if the SSO session has expired.
3.
Page 405 of 4705
Home
3. The web application queries the client library to extract the user credentials from the
authenticated HTTP request.
Integrating the mid tier into an SSO environment
Note
The information in this section applies to BMC Remedy AR System releases 6.3 and later.
When the mid tier is integrated into an SSO environment, the authenticator extracts the requesting
user's credentials from the authenticated HTTP request. The credentials are passed to AR System
server for the authentication, via the UserCredentials data object. The authenticator extracts
the user credentials from the authenticated HTTP request, and returns the credentials as the
UserCredentials data object.
When the authenticator passes a login name, that name must match a stored system value. This
value can be stored in the AR System User form, if user credentials are stored and retrieved this
way in your environment. Other implementation options are a packaged plug-in like the LDAP
AREA plug-in, or a custom AREA plug-in with the authentication logic built in. In any case, the
server must authenticate the user using one of these techniques.
Note
AREA is invoked if the login name is stored in the User form with a blank password
Cross-reference blank passwords is invoked, and AREA is configured. AREA is also
invoked if Authenticate Unregistered Users is active, and AREA is configured. For more
information, see Cross-reference blank passwords and Authenticate unregistered users.
Configuration requirements for the mid tier in an SSO environment

To configure the mid tier for integration into an SSO environment you must do the following:
Configure the mid-tier to use the authenticator implementation (instead of the default
behavior).
Implement the AREA plug-in to perform user authentication verification, based on the
UserCredentials as passed by the mid tier.
Configure the AR System server to use the AREA plug-in for user authentication.
Following is the sequence of events triggered by a user request for access, when the mid tier is
placed in an SSO environment:
Page 406 of 4705
Home
Sequence of mid tier authentication events in an SSO environment

1. The HTTP request is routed to the mid tier application server.
2. The interceptor intercepts the HTTP request.
3. If the HTTP request is not authenticated, the interceptor routes the request to the SSO
service for the user to login.
4. Upon a successful user login, the request is routed back to the original mid tier URL.
5. The mid tier authenticator queries the client library for the user credentials from the
authenticated HTTP request.
6. The mid tier encapsulates the credentials in the UserCredentials data object.
7. The mid tier forwards the data object to the AR System server for authentication verification.
SSO implementation example (with LDAP)
(Click to expand the image.)
Unlike a normal web application, the mid tier does not authenticate users. User credentials are
forwarded to the AR System server for authentication. For this reason, in an SSO environment,
authentication verification steps must take place in an AR System server. Generally, this is
configured using an AREA plug-in, based on the user credentials passed by the mid tier.
Configure the mid tier to use the authenticator implementation

The authenticator interface provides the following methods to configure the mid tier:
init()
destroy()
getAuthenticatedCredentials()
init()
The authenticator uses the init() method for initialization. The routine is called once, when the
mid tier starts and all initialization is done in this method. After the mid tier instantiates an instance
of the authenticator using reflection, it builds a java.util.Properties object. This object is
created from properties specified in the arsystem.authenticator.config.file entry, and
the config.properties file. This file is a map of the name-value order pairs. For example:
arsystem.authenticator.config.file=myauthenticator.properties
Page 407 of 4705
Home
The myauthenticator.properties property file must be contained in the same directory as

the config.properties file (in WEB-INF/classes ).
If the config.properties file does not include a reference to the authenticator init or, if the
mid tier cannot locate or open the file, the mid tier creates an empty properties object. This object is
passed into the init() method.
Any parameters that should be externalized, and any parameters that are needed during the
authenticator initialization process, are placed in this file. The file name must be registered in the
config.properties file, as shown in the following example:
arsystem.authenticator.config.file=yourpropertiesfile.properties
destroy()
When the mid tier is unloaded from the application server, it calls the destroy() method. This
method ends the user session and performs required reallocation of resources.
getAuthenticatedCredentials()
The getAuthenticatedCredentials() is called when a user requests a new session. The
SSO implementation must use the client library to extract the user credentials from the
authenticated HTTP request, and then return the credentials as the UserCredentials data
object.
Configure your SSO environment to route every HTTP request sent to the mid tier with the
getAuthenticatedCredentials object, for authentication.
Note
If the user credentials cannot be extracted the mid tier will fall back to the application
default login method. For more information see, Fallbacks and the default login page.
User authentication verification

To implement your SSO solution on the mid tier, register your classes using one of the following
options:
Package your classes into a jar file and copy the jar file to the following directory:
<Mid-Tier dir>/WEB-INF/lib
Copy your classes to the following directory:
<Mid-Tier dir>/WEB-INF/classes
Page 408 of 4705
Home
To complete the configuration specify your authenticator implementation and use the AREA plug-in
for user authentication.
Specify your authenticator implementation

Specify your authenticator implementation in the config.properties file as follows:
The com.remedy.arsys.session.Authenticator interface is given by:
public interface Authenticator {

public void init(Map config)
public void destroy()}
public UserCredentials getAuthenticatedCredentials
( HttpServletRequest request,
HttpServletResponse response)
throws IOException;
}
If UserCredentials is a data-object class with the following constructor:
public UserCredentials(String user, String password, String authenticationStr)
The getAuthenticatedCredentials() method throws IOException to simplify the support

of the methods of the HttpServetRequest and HttpServletResponse classes.
In the default configuration of the mid tier, an instance of the
com.remedy.arsys.session.DefaultAuthenticator class performs the login and user
credentials forwarding.
Using the AREA plug-in for user authentication

When the mid tier is initialized, it uses reflection to instantiate an instance of the authenticator. The
fully qualified name of the class implementing the authenticator interface must be specified in the
config.properties file under the arsystem.Authenticator entry. (In a default deployment,
the config.properties file is found in the WEB_INF/classes directory.)
The following example defines DefaultAuthenticator as the authenticator to be used:
arsystem.authenticator=com.remedy.arsys.session.DefaultAuthenticat
or
This is the default authenticator that displays the login screen. It is used when an alternate
authenticator is not defined. Because only one registration is permitted for the instantiation of the
mid tier, only a single alternate authenticator mechanism is allowed for an instance of the mid tier.
Fallbacks and the default login page

If a problem occurs during login, the system will fall back to the standard login page. This can occur
in the following situations:
Page 409 of 4705
Home
The plug-in implementation is not found or cannot be activated.

A call returns incomplete or inconsistent data (for example, a blank user name).
The login using credentials from the plug-in returns an error indicating login failure.
Authentication has failed.
In each of these cases, the web client will display the standard login page and allow the user to
attempt connection using the standard user name, password, authentication string login.
Specifically, the DefaultAuthenticator method will be called.
Windows client integration

BMC Remedy Alert includes a hook that can be configured to specify a Dynamic Link Library (DLL),
in place of the login page. This DLL returns the user login information (from the login page) and can
be configured to:
Interact with other systems
Open windows
Perform calculations
Note
The following information applies to BMC Remedy Alert, which always requires a login
and will not support an "auto-login" mode. This is a security measure put in place because
the tool allows changing of the system definitions.
Sequence of authentication events in an SSO environment

1. At startup, the login page is launched (unless the user preference has been set to remember
login information).
2. BMC Remedy Alert will look for the ARSSOInfo.dll with the following methods exposed:
ARGetSSOLoginCredentials
ARGetSSOServerInformation (This method is optional)
ARSSOInfo.dll must be placed in the directories from which BMC Remedy Alert is
launched. Otherwise, the DLL cannot be located at startup.
Note
If the DLL is not present or if there is a problem getting the information, see
Fallbacks and the default login page.
Page 410 of 4705
Home
ARGetSSOLoginCredentials
Use the ARGetSSOLoginCredentials method to retrieve user credentials from the server, based
on the provided user login credentials. The password or key retrieved is dynamic, and tied into the
server authentication method. Use of this method is described in the following code sample:
void ARGetSSOLoginCrendentials(
ARSSOUserCredentialsStruct *pUserCredentialStruct)
ARSSO User CredentialsStruct

The user credentials are loaded into the method and returned to AR System. This call must be
implemented in the DLL.
BMC Remedy User allocates all memory for the ARSSOUserCredentialsStruct method. The
fields are initialized before the method is called. The DLL is responsible for updating the
appropriate fields in the structure. The DLL must not allocate memory for this structure (but it can
allocate and free any temporary storage needed for processing), and the DLL must not write data
outside the field length limits.
Following is an example:
struct ARSSO UserCredentialsStruct

{
char*
m_szARUserName;
char*
m_szARPassword;
char*
m_szARAuthenticationString;
BOOL
int
m_bARUsingPreferenceServer;
m_nARNumberOfServers;
};
ARGetSSOLoginCrendentials Method Fields

Behavior
Setting
m_szARUserName
m_szARUserName is the login name of the user. The maximum length is 254 bytes. The
string must be null terminated. A value must be specified for this field. There is no default
value.
m_szARPassword
m_szARPassword is the password for the user. The maximum length is 30 bytes. The string
must be null terminated. The default is an empty string.
m_szARAuthenticationString
m_szARAuthenticationString is the authentication string for the user. The maximum

length is 2000 bytes. It is 254 bytes for versions 7.0 before patch 2 of BMC Remedy User
because an nicorrect length was used initially. The string must be null terminated. The
default is an empty string.
m_bARUsingPreferenceServer
Page 411 of 4705
Home
Behavior
Setting
The m_bARUsingPreferenceServer flag indicates login via a preference server. If set to
TRUE, a preference server is expected and the m_nARNumberOfServers field must have a
value of 1 or greater. If set to FALSE, no preference server is expected. The default is
FALSE.
m_nARNumberOfServers
m_nARNumberOfServers is The number of servers that are specified, by the plug-in, for
this user. If this parameter is set to 0, no additional servers are expected. If set to a number
greater than 0, the ARGetSSOServer Information method is called to get the list of servers.
If the m_bARUsingPrefereceServe r flag is set to TRUE, the value of this parameter
must be at least 1 to accommodate a preference server. The default is 0.
ARGetSSOServerInformation (optional)
The following method is optional:
void ARGetSSOServerInformation(
ARSSOServerInformation *pServerInfo)
Where the user provides only login credentials, not server list information, this method is not
needed. If the method is not present, the system default mechanism looks at the local configuration
file to determine servers connections.
Important
If the server count field from the ARGetSSOLoginCredentials method specifies a
server count greater than 0, this method is required.
Treat the ARGetSSOLoginCredentials parameters as an array of items, with each item having
the structure described. The size of the array is determined by the server count returned in the
ARGetSSOLoginCredentials method. The server identified in the first element of the list is
treated as the preference server, if the login credentials have indicated use of a preference server.
BMC Remedy User allocates all memory for the method. The fields are initialized before the
method is called. The DLL is responsible for updating the appropriate fields in the structure. The
DLL must not allocate memory for this structure (but it can allocate and free any temporary storage
it might need for processing), and the DLL must not write data outside the length limits of the fields.
Following is an example:
struct ARSSOServerInformation
{
char*
m_szARServerName;
int
m_nARTCPNum;
int
m_nARRPCNum;
Page 412 of 4705
Home
};
ARGetSSOServerInformation Method Fields

Field
Description
m_szARServerName
m_szARServerName is the name of an AR System server to access. The maximum length is 254 bytes.
The string must be null terminated. A value must be specified for this field. There is no default value.
m_nARTCPNum
m_nARTCPNum is the TCP socket to which you will connect on this server. Setting the value to 0 indicates
that there is no predefined TCP socket to connect to (or you will look it up using portmapper). The default
value is 0.
m_nARRPCNum
m_nARRPCNum is the RPC socket to which you will connect on the AR Syst em server. Setting the value to
0 indicates you are not locking to a specific RPC socket and will let the system determine which socket to
route to. The default value is 0.
Fallbacks and the default login page

If there is a problem during login, the system will fall back to the standard login page and allow the
user to continue logging into the system through that approach.
If any of the following conditions occur, the default login page will be displayed:
The plug-in DLL cannot be found or cannot be loaded. (The DLL is expected to be in the
directory from which BMC Remedy Alert is launched.)
An expected method is not exposed from this DLL.
A method returns incomplete or inconsistent data (for example, a blank user name).
The login using credentials from the plug-in returns an error message indicating login failure.
The user selects the Login option from the Tools menu.
In each of these cases, BMC Remedy Alert will display the standard login page and allow the user
to attempt connection using the standard user name/password/authentication string login.
Custom API code samples

Use the following sample code to help you create AREA plug-ins for Microsoft Windows or the web.
Windows (.cpp file) sample

#include <string.h>
struct ARSSOServerInformation
{
char * m_szARServerName;
int m_nARTCPNum;
int m_nARRPCNum;
};
struct ARSSOUserCredentialsStruct
{
char* m_szARUserName;
char* m_szARPassword;
Page 413 of 4705
Home
char* m_szARAuthenticationString;
bool m_bARUsingPreferenceServer;
int m_nARNumberOfServers;
};
extern "C"
{
__declspec(dllexport) void
ARGetSSOLoginCrendentials(ARSSOUserCredentialsStruct
*pUserCredentialStruct)
{
// The required memory for struct ARSSOUserCredentialsStruct is allocated by user
tool,
// This dll just needs to assign values.
// eg:
strcpy(pUserCredentialStruct->m_szARUserName,"Demo");
pUserCredentialStruct->m_nARNumberOfServers=2;
}
}//End 'extern "C"
extern "C"
{
__declspec(dllexport) void
ARGetSSOServerInformation(ARSSOServerInformation *pServerInfo)
{
// The required memory for struct ARSSOServerInformation is allocated by user tool,
// This dll just needs to assign values.
// eg:
strcpy(pServerInfo[0].m_szARServerName, "ServerName1");
pServerInfo->m_nARTCPNum = 3040; pServerInfo->m_nARRPCNum
= 390622;
strcpy(pServerInfo[1].m_szARServerName, "ServerName2");
}
}//End 'extern "C"
Java (.java file) sample

/*
* Created on Jun 5, 2006 *
* Copyright 2006 BMC Software, Inc.
* All rights reserved. *
* This software is the confidential property and proprietary information of
* BMC Software, Inc.
/*
package com.yourcompany.sso;
import java.io.IOException;
import java.util.Map;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.remedy.arsys.session.Authenticator;
import com.remedy.arsys.session.UserCredentials;
/**
* This is an example of a simplistic authenticator. It assumes that your SSO
* solution embeds the credentials in the Http request header as is true in most
Page 414 of 4705
Home
* SSO solutions. The key (for extraction of the Http header) of course is
* specific to your solution. What we use here is only for illustration purposes.
/*
/*
public class MyAuthenticator implements Authenticator {
//Http header constants specific to your SSO solution.
We illustrate here:
private static final String USER = "my-sso-provider-username";
//NOTE: generally passwords are never passed around b/c of security risks.
private static final String PW = "my-sso-provider-password";
private static final String AUTH_STRING = "my-sso-provider-SSOtoken";
/**
* @see com.remedy.arsys.session.Authenticator#init(java.util.Map)
*/
public void init(Map cfg) {
//perform any SSO specific initialization here such as encryption set up.
}
/**
* @see com.remedy.arsys.session.Authenticator#destroy()
*/
public void destroy() {
//perform any resource clean up here.
}
/**
* @see com.remedy.arsys.session.Authenticator#getAuthenticatedCredentials
(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)
*/
public UserCredentials getAuthenticatedCredentials(
HttpServletRequest request, HttpServletResponse response)
throws IOException {
String user = request.getHeader(USER);
String pw = request.getHeader(PW);
String authStr = request.getHeader(AUTH_STRING);
//1. check to see if user is auth'd by SSO, ie, has username and token.
if ((user\!=null&&user.length()>0) &&
(authStr\!=null&&authStr.length()>0)) {
return new UserCredentials(user.toLowerCase(), pw, authStr);
}
else { //2. user not auth'd; return null.
//embed routing info in response object if necessary.
return null;
}
}
}
Configuring AR System server in the SSO environment

There are many options for configuring BMC Remedy AR System server to work in an SSO
environment. This section discusses:
Configuring AR System server for AREA
Page 415 of 4705
Home
AREA plugins

You might be using several authentication methodologies at the same time. You can use an SSO
environment within the office but have users enter their user name and password if they are
working from home. This strategy allows you to mix multiple methods and let the authentication
automatically validate against each, by linking to technologies on the client to provide a complete,
end-to-end implementation.
Note
AR System server uses the login name for permissions, assignments, and ownership of
records. If a user logs in from multiple locations, the user must log in with the same login
name.
Configuring AR System server for AREA

To set up AR System server for any SSO implementation, you must:
1. Install the AREA plug-in. For more information see Installed plug-in components.
2. Configure AR System server to access the plug-in server. For more information see
Configuring AR System servers.
3. Configure users in the User form, or based on your implementation.
4. Configure the AR System server to use external authentication. Information about this step is
included in this section.
AREA plugins
AREA provides a way to validate users by connecting AR System to a data source outside the AR
System database. When AR System server is configured for external authentication to an AREA
service, the user name, password, and authentication values entered are provided to the AREA
service. All security enforcement and user validation is performed on the server within the AR
System environment. No authentication is performed on the client. This architecture provides
optimum security by avoiding situations where a client could validate and allow an unauthorized
user. In this architecture the client cannot spoof or work around the security of the system to gain
unauthorized access.
To successfully implement SSO integration with AR system, use the server AREA plug-in for user
validation.
The server receives the following user authentication information:
User validation information
Page 416 of 4705
Home
Value
Required
Description
User name
Identifies the user
Password
Validates the user
Authentication string
Second factor validation
Server authentication
Server authentication must be facilitated using one of options described in the following table.
Server authentication options
Option
Use Case
AR
System
User form
The AR System server authenticates users based on information provided via the User form. BMC does not
recommend using an external system for authentication. Most authentication models, when using AR System, require
that user information be stored in the User form if the user will be modifying records or performing application roles.
LDAP
AREA
Packaged
The LDAP AREA Packaged Plug-in authenticates AR System users against external LDAP directory services.
Plug-in 1
Custom
AREA
Create a custom plug-in with the authentication logic built in, to integrate AR System with external authentication
services.
Plug-in 2
1. For a full discussion of the AREA API and how to write an AREA plug-in, see Configuring the
AREA LDAP plug-in.
2. For information see AREA plug-in API functions.
Login alias
If your authentication method does not allow you to get the real user name from the AR System,
you can look at the user name alias functionality of the AR System. The value passed to AR
System server must be the user login name. When using the User form, this login name must
match the login name field in that form (case sensitive). When using the login alias, a different
value can be passed to the AREA plug-in. But the value passed to AR System server becomes $
USER$ to preserve consistency. For more information, see Configuring after Installation.
Server configuration settings

Several server configuration settings affect the operation of the system in relationship to the AREA
plug-ins. Some are related only to the AR System server while others are associated with how AR
System interacts with the AREA environment. This section introduces and discusses interaction
with SSO/login intercept authentication for the following options:
Cross-reference blank passwords
Authenticate unregistered users
Authentication-Chaining mode
Page 417 of 4705
Home
Cross-reference blank passwords

This option allows you to configure the server to query an external mechanism for user password
validation.
This is useful if you want to define user characteristics (email address, licensing, group information)
in AR System, and have authentication occur outside of AR System. With this option, authorization
occurs within the AR System User form, and authentication occurs outside the system. The
following options are supported:
OS environment password (for the user with a matching name)
AREA plug-in
The cross-reference blank passwords feature is related only to users without a password defined
within the AR System User form. It does not accept a user with no password, but checks the user's
password against an AREA plug-in (if present) or the OS (when the
External-Authentication-RPC-Socket ar.conf value is not set). Use the following steps to
configure AR System server to cross reference blank passwords.
Note
This option is independent of the option described in the Authentication-Chaining mode
section below.
To configure AR System server to cross reference blank passwords

1. Log on to AR System.
2. Choose AR System Administration > AR System Administration Console .
3. Choose System > General > Server Information.
4. Click the EA tab.

5. Click Cross Reference Blank Password to activate the option.
6. Click Apply to confirm the setting.
Page 418 of 4705
Home
Authenticate unregistered users

This feature is used to authenticate users that do not exist in the User form. If you are maintaining a
list of users outside of the AR System User form for authentication, use this feature to require
authentication of unregistered users if you want to require that every login be authenticated within
AR System, the OS, or an AREA plug-in. Use the following steps to configure AR System server to
authenticate unregistered users.
Notes
This feature is limited, especially when using OS authentication. Users cannot be

assigned groups or licenses.
You cannot get any admin group information from the user's group list if the user is
returned through external authentication. You can get admin group information only
from the User form.
Configure AR System server to authenticate unregistered users

2. Click AR System Administration > AR System Administration Console .
3. Click System > General > Server Information.
5. Click Authenticate Unregistered Users to activate the option.
Configure AR System server to authenticate unregistered users in the configuration file (for
releases prior to 6.0)
1. Open the BMC Software installation folder:
a. On a Windows system, navigate to the following file:
Program Files > BMC Software > ARSystem > Conf > ar.cfg
b. On a UNIX (or Linux) based OS, open a terminal and enter:
vi ar.conf
2. Enter the following at the bottom of the file:
Page 419 of 4705
2.
Home
Use-Password-File: T
Authentication-Chaining mode
The authentication chaining option is a configuration setting that provides users with connection
options based on the environment. Use the following steps to configure Authentication-Chaining
mode:
To configure Authentication-Chaining mode

2. Choose AR System Administration > AR System Administration Console.
5. Use the Authentication Chaining Mode list to choose from the options described in the
following table.
Authentication-Chaining-Mode values
Behavior
Setting
Use the default behavior, available prior to release 6.3 (that is, authenticate either with AR System or with
AREA depending on the settings of other configuration options).
Use AR System internal authentication first, then use external authentication via the AREA plug-in.
Use external authentication via the AREA plug-in first, then use AR System internal authentication.
To configure AR System server Authentication-Chaining in the configuration file (for releases

prior to 6.3)
1. Open the BMC Software installation folder:
a. On a Windows system, navigate to:
Program Files > BMC Software > ARSystem > Conf > ar.cfg
b. On a UNIX-based or Linux-based OS, open a terminal and enter:
vi ar.conf
The Authentication-Chaining Mode setting in the ar.cfg ( ar.conf ) file allows you
to configure the behavior of the system.
2. Enter the following at the bottom of the file:
Authentication-Chaining-Mode: {value }
Multiple plug-ins with multiple external sources

Another option is to have multiple AREA plug-ins to authenticate against many different external
sources. In all cases of chaining in the table, authentication via the AREA plug-in includes
situations with one plug-in and those having multiple plug-ins.
Page 420 of 4705
Home
AREA HUB plug-in

In an environment with multiple AREA plug-ins, the system can be set up to use the AREA HUB
plug-in. The AREA plug-in hub provides a sequential chaining of multiple AREA plug-ins. From the
AR System perspective, there is one AREA plug-in and that is the AREA hub. That hub traverses
the various registered plug-ins, until a successful authentication is initiated or all registered plug-ins
have been tried.
AREA chaining for C AREA plug-ins, the AREA HUB Plug-in, is configured in the ar.cfg file. The
Java plug-in server supports AREA HUB ( AREA chaining) as of release 7.1. For Java, the AREA
chaining is done inside the Java Plug-in server itself. One Java AREA plug-in is configured in
ar.cfg AREA plug-in alias. The order is determined by the sequence configured in the plug-in
server configuration file.
Note
For details about using and configuring the AREA plug-in hub, see Setting up the AREA
hub.
Maximum number of bad password attempts before invalidating the account

This option sets a maximum number of bad password attempts as related to authentication within
the AR System s erver environment only. Any rules or checking for bad password attempts through
other environments are enforced strictly through that environment. Use the following steps to
configure the maximum number of bad password attempts.
To configure the maximum number of bad password attempts

2. Choose AR System Administration > AR System Administration Console .
4. Click the Configuration tab.
5. Enter the maximum number of bad attempts you want the system to allow.
Bad password attempt configuration considerations

Any AREA plug-in that interacts with an external environment will count any failed validation against
that environment as a bad authentication attempt. This is true even if the chain includes a
successful validation against another plug-in. The net effect can be a problem. If logins are allowed
using numerous mechanisms, add the most common or the ones with no lockout early in the list so
you do not lock out an account through checks against one environment when the user is logging in
using a different environment.
This option records a bad attempt event only if the login fails all of the tests. This means that when
Page 421 of 4705
Home
you want to include AR System authentication in the authentication chain, configure the chaining to
try the AR System authentication first. This is because a failure there will not count against you if
some other authentication works, and, if AR System authentication succeeds, you prevent the bad
attempts against other authentication mechanisms.
A key characteristic of AREA is that the plug-in is used for authentication, but it can also optionally
supply authorization information. A plug-in can return information like the user's email address, a
group list, and a license type (although it cannot return a fixed license). If the plug-in does not
supply this information, it can be obtained from the user record within the AR System. If the
authorization information is in neither place, the email address is the login name, the user is in no
groups, and the user is defined to have a read license. This is also further documented in the
discussion of the AREA environment in the Integrating section.
Login alias
If your authentication method does not allow you to get the real user name from the AR System,
you can look at the user name alias functionality of the AR System. The value passed to AR
System server must be the user login name. When using the User form, this login name must
match the login name field in that form (case sensitive). When using the login alias, a different
value can be passed to the AREA plug-in. But the value passed to AR System server becomes $
USER$ to preserve consistency. For more information, see the Configuring after installation section.

The following topics describe the security test products and procedures that BMC uses to reduce
security vulnerabilities:
WhiteHat Sentinel PE security penetration testing
WhiteHat Sentinel PE security penetration testing - AR 8.8 Revision
WhiteHat Sentinel PE security penetration testing - SP2 revision
AppScan testing
WhiteHat Sentinel PE security penetration testing for BMC Remedy ITSM and BMC Remedy
AR System 9.0
WhiteHat Sentinel PE security penetration testing
For BMC Remedy ITSM 8.1 Service Pack 1 (SP1) and BMC Remedy AR System 8.1 SP1, BMC
uses the WhiteHat Sentinel Premium Edition (WhiteHat Sentinel PE) service, a dynamic application
security tool (DAST), for security penetration testing. By performing security penetration testing,
BMC can identify whether applications are vulnerable to web attacks and implement the required
countermeasures to reduce vulnerabilities.
As of March 5, 2014, BMC Remedy ITSM 8.1 SP1 and BMC Remedy AR System 8.1 SP1 do not
have any security penetration vulnerabilities.
Page 422 of 4705
Home

WhiteHat security vulnerability tests
Changes required for on-premise and BMC Remedy OnDemand environments
Configuring Apache Tomcat settings to disable directory listings
Creating an SSL profile on the reverse proxy to disable RC4 ciphers
Restricting attachments by using Attachment Security
Note
For BMC Remedy ITSM 8.1 SP1 and BMC Remedy AR System 8.1 SP1, BMC schedules
automated security scans with WhiteHat Security that are run on the SaaS-based
WhiteHat Sentinel platform. Automated scans are augmented by manual penetration tests
performed by WhiteHat security experts. After the tests are completed, BMC receives
vulnerability assessment reports. For more information about WhiteHat Sentinel, see https
://www.whitehatsec.com/sentinel_services/benefits.html.
For BMC Remedy ITSM 8.1 SP1 and BMC Remedy AR System 8.1 SP1, security penetration tests
were performed using a BMC Remedy OnDemand instance deployed in the following environment:
Test environment
Component
Server specifications
VM
Operating system
used?
BMC Remedy Mid Tier 8.1 SP1 (and BMC
Atrium Single Sign-On 8.1)
BMC Remedy AR System 8.1 SP1

BMC Remedy ITSM 8.1 SP1
Yes

2008 R2 (64-bit)
Yes

2008 R2 (64-bit)
2 CPUs (Intel Xeon CPU E7

4870 @ 2.40 GHZ)
8 GB RAM
25 GB drive for BMC Remedy
applications
15 GB drive for paging
2 CPUs (Intel Xeon CPU E7

4870 @ 2.40 GHz)
8 GB RAM
25-GB drive for BMC Remedy
applications
15-GB drive for paging
Page 423 of 4705
Home

As of February 20th, 2014, WhiteHat Security has run 242 automated security scans of BMC
Remedy AR System 8.1 SP1 and BMC Remedy ITSM 8.1 SP1. Whitehat Security performs manual
testing by further exploring areas found during the automated testing. WhiteHat security experts
only had to perform one manual business logic assessment because they did not find any
significantly vulnerable areas from a security perspective.
WhiteHat Security employs the following types of tests during the security testing:
Authentication tests (brute force, insufficient authentication, weak password recovery,
cross-site request forgery, credential/session prediction, insufficient authorization, insufficient
session expiration, session fixation)
Client-side attack tests (content spoofing, cross-site scripting, HTTP response splitting)
Command execution tests (buffer overflow, format string attack, LDAP injection, OS
commanding, SQL injection, server-side include injection, XPath injection)
Information disclosure tests (directory indexing, information leakage, path traversal,
predictable resource location)
Logical attack tests (abuse of functionality, denial of service, insufficient anti-automation,
insufficient process validation)
For more information about WhiteHat Security, see the website security statement for WhiteHat
Security.
For more information about the WhiteHat Sentinel PE tests that were used and the results, which
are zero technical and business logic vulnerabilities, see the following reports:
WhiteHat Security testing report
WhiteHat Security PCI compliance report
Note
BMC and Whitehat Security are continually running tests as BMC augments the
environment or adds new security tests.

The following changes are required for on-premise and BMC Remedy OnDemand environments to
achieve zero technical and business logic vulnerabilities in BMC Remedy ITSM 8.1 SP1 and BMC
Remedy AR System 8.1 SP1:
Page 424 of 4705
Home


To prevent a security vulnerability from directory listings, BMC used the following procedure to
disable directory listings on the Tomcat web server hosting BMC Remedy Mid Tier:
1. Stop the Tomcat server.
2. Use a text editor to edit the <CATALINA_HOME>\conf\web.xml file.
3. Change the param-value for the listings parameter to false.
4. Save the change.
5. Restart the Tomcat server.
When you disable the directory listings, you will also disable online help. To enable online help:
1. Install a separate Tomcat instance on a different port on the BMC Remedy Mid Tier
computer.
2. Install online help in the Tomcat container in the Root folder of the Tomcat instance.
3. Log on to BMC Remedy Mid Tier as an administrator and open the SHARE:
Application_Properties Form.
4. Search for Property Name = Help File Path.
5. Update the Property Value for all search result entries to point to the new online Help URL
with the correct port number.
If you are using a reverse proxy (load balancer), further changes may be required
to allow access to the new online help URL.

RC4 ciphers are vulnerable to web attacks. The following procedure is an example of how BMC
modified the default cipher support of the reverse proxy (load balancer) to disable Secure Sockets
Layer (SSL) version 3 and RC4 ciphers:
The following procedure is specific to how BMC Remedy OnDemand uses SSL. An
on-premise installation requires changes to the Apache Tomcat configuration to disable
the RC4 ciphers.
1. Log on to the Configuration utility for the reverse proxy (load balancer).
2. Click Local Traffic.
3. Click Profiles.
4. From the SSL menu, select Client.
5.
Page 425 of 4705
Home
5. Click Create.
6. Type a name for the SSL profile.
7. From the Parent Profile menu, select clientssl.
8. From the Configuration menu, select Advanced.
9. Click the Custom box for Ciphers.
10. In the Ciphers box, enter the following string:
DEFAULT:!SSLV3:!RC4
11. Click Finished.
12. Associate the SSL profile with the virtual server.

BMC used the Attachment Security feature provided with BMC Remedy AR System 8.1 SP1. This
feature helps to prevent users from uploading malicious attachments and viewing them in the BMC
Remedy Mid Tier. BMC defined the following attachment extensions as the only attachment
extensions allowed for attachment uploads:
.txt
.png
.jpg
To restrict attachments, BMC used the following procedure to make the changes to the
Attachment Security tab of the AR System Administration: Server Information form:
1. Select the following options:
Allow attachments with following extensions option in the Attachment criteria
field
Allow display of attachments with the following extensions option in the Display
criteria field
2. Define the list of attachment extensions ( .txt, .png, .jpg) in the Comma separated list of
limit extensions and Comma separated list of display extensions fields.
3. Click Apply.
For additional information about how to restrict attachments, see Setting security restrictions on file
uploads.
The following image shows the changes made to the Attachment Security tab.
AR System Administration: Server Information form Attachment Security tab
Page 426 of 4705
Home
WhiteHat Sentinel PE security penetration testing - AR 8.8 Revision
For BMC Remedy AR System 8.8 and BMC Atrium Single Sign-On 8.8, BMC uses the WhiteHat
Sentinel Premium Edition (WhiteHat Sentinel PE) service, a dynamic application security tool (
DAST), for security penetration testing. By performing security penetration testing, BMC can identify
whether applications are vulnerable to web attacks and implement the required countermeasures to
reduce vulnerabilities.
As of April 16, 2014, BMC Remedy AR System 8.8 and BMC Atrium Single Sign-On 8.8 do not
Note
Page 427 of 4705
Home
For BMC Remedy AR System 8.8 and BMC Atrium Single Sign-On 8.8, BMC schedules
For BMC Remedy AR System 8.8 and BMC Atrium Single Sign-On 8.8, security penetration tests
Test environment
Component
BMC Remedy Mid Tier

8.8
BMC Atrium Single
Sign-On 8.8
2 CPUs (Intel Xeon CPU E7 4870 @

2.40 GHZ)
8 GB RAM
25 GB drive for BMC Remedy
applications
BMC Remedy AR
System 8.8

2.40 GHz)
BMC Remedy ITSM 8.1
8 GB RAM
25-GB drive for BMC Remedy
VM
used?
Operating system
Yes
Microsoft Windows Server 2008 R2 (

64-bit)
Yes

64-bit)
applications

As of April 16, 2014, WhiteHat Security has run 242 automated security scans of BMC Remedy AR
System 8.8 and BMC Atrium Single Sign-On 8.8. Whitehat Security performs manual testing by
further exploring areas found during the automated testing. WhiteHat security experts only had to
perform one manual business logic assessment because they did not find any significantly
vulnerable areas from a security perspective.
Page 428 of 4705
Home

Security.
Note

achieve zero technical and business logic vulnerabilities in BMC Remedy AR System 8.8 and BMC
Atrium Single Sign-On 8.8:

4. Save the change.
computer.
2.
Page 429 of 4705
Home
Application_Properties form.

the RC4 ciphers.
3. Click Profiles.
5. Click Create.
DEFAULT:!SSLV3:!RC4
11. Click Finished.

BMC used the Attachment Security feature provided with BMC Remedy AR System 8.8. This
.txt
Page 430 of 4705
Home
.png
.jpg
field
criteria field
3. Click Apply.
uploads.
WhiteHat Sentinel PE security penetration testing - SP2 revision
Page 431 of 4705
Home
For BMC Remedy ITSM 8.1 Service Pack 2 (SP2) and BMC Remedy AR System 8.1 SP2, BMC
uses the WhiteHat Sentinel Premium Edition (WhiteHat Sentinel PE) service, a dynamic application
security tool (DAST), for security penetration testing. By performing security penetration testing,
BMC can identify whether applications are vulnerable to web attacks and implement the required
countermeasures to reduce vulnerabilities.
As of August 16, 2014, BMC Remedy ITSM 8.1 SP2 and BMC Remedy AR System 8.1 SP2 do not
Enabling Login Failure Lockout in BMC Atrium SSO
Enforcing the default password policy in BMC Remedy AR System
Note
For BMC Remedy ITSM 8.1 SP2 and BMC Remedy AR System 8.1 SP2, BMC schedules
For BMC Remedy ITSM 8.1 SP2 and BMC Remedy AR System 8.1 SP2, security penetration tests
Test environment
Component
BMC Remedy Mid Tier 8.1

SP2
BMC Atrium Single

Sign-on 9.0
VM
used?
Operating system
Yes
Microsoft Windows Server 2008 R2

(64-bit)
Yes
CentOS
2 CPUs (Intel Xeon CPU E7 4870 @ 2.40

GHZ)
8 GB RAM
39.9 GB drive for BMC Remedy applications
2 CPUs (Intel(R) Xeon(R) CPU E7- 4870 @

2.40GHz
8 GB RAM
Page 432 of 4705
Home

8.1 SP2
BMC Remedy ITSM 8.1
SP2
Yes
2 CPUs (Intel Xeon CPU E7 4870 @ 2.40
GHz)
Microsoft Windows Server 2008 R2

(64-bit)
8 GB RAM
39.9-GB drive for BMC Remedy applications

As of August 16, 2014, WhiteHat Security has run 242 automated security scans of BMC Remedy
AR System 8.1 SP2 and BMC Remedy ITSM 8.1 SP2. Whitehat Security performs manual testing
by further exploring areas found during the automated testing. WhiteHat security experts only had
to perform one manual business logic assessment because they did not find any significantly
vulnerable areas from a security perspective.
Security.
Note
Page 433 of 4705
Home

achieve zero technical and business logic vulnerabilities in BMC Remedy ITSM 8.1 SP1 and BMC
Remedy AR System 8.1 SP1:

4. Save the change.
computer.

Page 434 of 4705
Home
the RC4 ciphers.
3. Click Profiles.
5. Click Create.
DEFAULT:!SSLV3:!RC4
11. Click Finished.

.txt
.png
.jpg
field
criteria field
3. Click Apply.
uploads.
Page 435 of 4705
Home

With the Atrium SSO Login Failure Lockout procedure, an account can be locked after a number of
failed login attempts. The number of failed attempts that triggers the lockout and the duration of the
lockout are both configurable. For the BMC WhiteHat security testing, Login Failure Lockout was
configured to lock the account for 15 minutes after three unsuccessful login attempts.
Use the Atrium SSO Realm Editor to configure Login Failure Lockout. For instructions on
configuring the Realm Editor including Login Failure Lockout, refer to the BMC Atrium SSO Realm
Editor topic.

BMC Remedy AR System uses an MD5 hash of passwords stored in the database, ensuring that
passwords cannot be retrieved. To enable and configure a password policy, refer to the topic
Enforcing a password policy introduction. For the BMC WhiteHat security testing, the default
password policy was enabled.
AppScan testing
BMC used IBM Rational AppScan, a Web 2.0 security assessment tool, as an integrated part of the
software development life cycle (SDLC) of BMC Remedy ITSM 8.0 and BMC Remedy AR System
8.0. For more information, see Security assessments.
Page 436 of 4705
Home
WhiteHat Sentinel PE security penetration testing - AR 9.0 revision
For BMC Remedy ITSM 9.0 and BMC Remedy AR System 9.0 uses the WhiteHat Sentinel
Premium Edition (WhiteHat Sentinel PE) service, a dynamic application security tool (DAST), for
security penetration testing. By performing security penetration testing, BMC can identify whether
applications are vulnerable to web attacks and implement the required countermeasures to reduce
vulnerabilities.
As of (DATE), BMC Remedy 9.0 and BMC Remedy AR System 9.0 do not have any security
penetration vulnerabilities.
Whitehat PCI Compliance Testing
Whitehat reports
Note
For BMC Remedy ITSM 9.0 and BMC Remedy AR System 9.0, BMC schedules
For BMC Remedy ITSM 9.0 and BMC Remedy AR System 9.0, security penetration tests were
performed using a BMC Remedy OnDemand instance deployed in the following environment:
Test environment
Component
BMC Remedy Mid Tier

9.0

2.40 GHz)
VM
used?
Operating system
Yes

64-bit)
Page 437 of 4705
Home
Component
VM
used?
Operating system
Yes
CentOS
Yes
8 GB RAM
39.9 GB drive for BMC Remedy
applications
BMC Atrium Single

Sign-on 8.8
2 CPUs (Intel Xeon CPU E7- 4870 @

2.40GHz
8 GB RAM
BMC Remedy AR
System 9.0
BMC Remedy ITSM 9.0

2.40 GHz)
8 GB RAM
39.9-GB drive for BMC Remedy
applications
64-bit)

As of (DATE), WhiteHat Security has run 242 automated security scans of BMC Remedy AR
System 9.0 and BMC Remedy ITSM 9.0. Whitehat Security performs manual testing by further
exploring areas found during the automated testing. WhiteHat security experts only had to perform
one manual business logic assessment because they did not find any significantly vulnerable areas
from a security perspective.
Security.
WhiteHat Security testing report (Updated report to come)
Page 438 of 4705
Home
WhiteHat Security PCI compliance report (Updated report to come)
Note

achieve zero technical and business logic vulnerabilities in BMC Remedy 9.0 and BMC Remedy
AR System 9.0:
Whitehat PCI Compliance Testing
Whitehat reports

4. Save the change.
computer.
Page 439 of 4705
5.
Home

the RC4 ciphers.
3. Click Profiles.
5. Click Create.
DEFAULT:!SSLV3:!RC4
11. Click Finished.

.txt
.png
.jpg
Page 440 of 4705
1.
Home

field
criteria field
3. Click Apply.
uploads.

With the Atrium SSO Login Failure Lockout procedure, an account can be locked after a number of
failed login attempts. The number of failed attempts that triggers the lockout and the duration of the
lockout are both configurable. For the BMC WhiteHat security testing, Login Failure Lockout was
configured to lock the account for 15 minutes after three unsuccessful login attempts.
Use the Atrium SSO Realm Editor to configure Login Failure Lockout. For instructions on
configuring the Realm Editor including Login Failure Lockout, refer to the BMC Atrium SSO Realm
Editor topic.
Page 441 of 4705
Home

BMC Remedy AR System uses an MD5 hash of passwords stored in the database, ensuring that
passwords cannot be retrieved. To enable and configure a password policy, refer to the topic
Enforcing a password policy introduction. For the BMC WhiteHat security testing, the default
password policy was enabled.
Language information
This section provides information pertinent to this release about language support and localized
forms, installation in an international environment, and double-byte issues.
Internationalization is the process of designing a software application so that it can be adapted to
various languages and regions without engineering changes. Localization is the process of
adapting software for a specific region or language by adding locale-specific components and
translating text.
All the components in the AR System platform are designed with internationalization in mind. The
AR System server is localized as well. See Localizing BMC Remedy AR System applications .
Topics include:
Supported languages and character encodings
Localized forms
Installing BMC Remedy AR System in an international environment: Oracle on UNIX
Supported languages and character encodings

BMC Remedy AR System supports data input and manipulation in the following languages and
character encodings:
Western Europe Danish, Dutch, English, Finnish, French, German, Icelandic, Italian,
Norwegian, Portuguese, Spanish, and Swedish (Windows-1252)
Central Europe Albanian, Croatian, Czech, Hungarian, Polish, Romanian, Serbian, Slovak
, and Slovenian (Windows-1250)
Cyrillic Eastern European (Russian, Ukrainian, Belarusian, Bulgarian, Serbian, and
Macedonian), Mongolian, and some Central Asian (Kazakh, Kyrgyz, Tatar, Uzbek [
HTMLUATarsPlanAndInstallFinal2:Windows-1251])
Baltic Estonian, Latvian, and Lithuanian (Windows-1257)
Traditional Chinese (Big5)
Simplified Chinese (GB2312)
Japanese (Shift-JIS and EUC-JP)
Korean (EUC-KR)
Thai (Windows-874) Windows only
Page 442 of 4705
Home
Unicode (UTF-8)
Unicode (UTF-16)
Unicode is a superset of the other character sets supported by BMC Remedy AR System.
Note
On Japanese operating systems, BMC Remedy AR System 7.0 and later support JIS X
0201-1976 and JIS X 0208-1978 Shift-JIS character sets. Because of a non-BMC
Remedy limitation, however, some Japanese characters are not supported in browsers. (
See http://www.w3.org/TR/japanese-xml/#ambiguity_of_yen for conversion issues from
Shift-JIS to Unicode.) For Kanji, JIS Level 1 and Level 2 are supported. Gaiji (extended
characters) is not supported; if Gaiji is used, data can be displayed incorrectly or be
corrupted. On Japanese UNIX servers, BMC Remedy AR System 7.0 and later support
only the EUC character set.
Non-Unicode AR System servers

A non-Unicode AR System server supports mixed-language environments if both of the following
conditions are true:
The languages belong to the same character set.
The AR System server is running on a localized operating system with a localized version of
the database.
Otherwise, characters might not be handled and displayed correctly.
For example, the following combinations are supported because the languages belong to the same
language group:
Czech and Polish clients on a server set to Hungarian
French, German, and English clients on a server set to German
Although languages from the same language group can be mixed, for some advanced
locale-specific operations involving sorting date and time format, the language version of the server
operating system and database must match that of the client to ensure optimal performance.
Unicode AR System servers

Because the Unicode character set is a superset of all the other character sets that BMC Remedy
AR System supports, a Unicode AR System server supports combining languages from different
language groups. For example, a Unicode AR System server supports the following language
combinations:
Spanish and Japanese
Page 443 of 4705
Home
Estonian and Croatian

French and Polish
Simplified Chinese and Traditional Chinese
Localized forms
The language version of the forms and data installed with the AR System server is relative to the
language selected for the installation.
With BMC Remedy AR System, the following forms are localized in French, German, Italian,
Spanish, Russian, Japanese, Korean, Brazilian Portuguese, and Simplified Chinese:
Alert Events
Alert List
AP: Rejection Justification
AP:AdhocDialog
AP:Admin-DeleteVerify
AP:Alternate
AP:Dtl-Sig-MoreInfoDialog
AP:More Information
AP:Password
AP:Reassign
AP:Show-Detail
AP:ShowDetail-DeleteVerify
Approval Central
AR System Customizable Home Page
AR System Report Console
AR System Report Designer
AR System User Central File
AR System User Preference
ARC:ConfirmDialog
Business Segment-Entity Association
Business Time Holidays
Business Time Segment
Business Time Shared Entity
Business Time Shared Entity-Entity Association_Join_Join
Business Time Workdays
Group
Home Page
MFS:MultiFormSearch
RD:Save As
Report
ReportCreator
ReportSelection
Page 444 of 4705
Home
ReportType
SHARE:Application_Interface
SHARE:Application_Properties
User
User Password Change
User Password Change Redirector
User Password Management Configuration
If you install the AR System server on an operating system set up for French, German, Italian, or
Spanish, the listed forms contain views in these languages as well as English. For example, if you
install the AR System server on an Italian operating system, these forms contain views in English,
French, German, Italian, and Spanish. The data installed is the Italian data (if you chose that
language's pack). All other language versions are also installed on your local drive and can be
imported using BMC Remedy Developer Studio and BMC Remedy Data Import.
If you install the AR System server on a Japanese operating system, the listed forms contain views
in English and in Japanese. The data installed by default is in Japanese. Only English and
Japanese definitions and data are installed on your local drive and can be imported using BMC
Remedy Developer Studio and BMC Remedy Data Import.
Installing BMC Remedy AR System in an international

environment: Oracle on UNIX
When you are installing BMC Remedy AR System in an international environment on UNIX, you
must create an Oracle database with a character set that is capable of storing your data. Also, you
must set up the database NLS parameter to support the database NLS functionality. Otherwise, the
wrong character set is used for conversion in forms and data. In addition, you will not be able to
import data correctly. The BMC Remedy AR System does not take care of these database NLS
setup issues.
Check the following language environment variables before installation:
LANG
NLS_LANG
To determine the current value of LANG, use the echo $LANG command at the shell in which you
plan to run the installer.
To determine which locales are installed on the system, use the locale -a command.
When installing a Unicode AR System server, set LANG to a Unicode locale code; typically these
end in UTF-8 or utf8. See the appropriate operating system and database documentation.
Page 445 of 4705
Home

BMC Remedy Email Engine supports internationalization through UTF-8 encoded locales by default
. To accommodate multi-byte languages, BMC Remedy Email Engine supports internationalization
in all the entities and attributes.
Unicode settings are applicable to both the incoming and outgoing messages. The email engine
always sends outgoing messages in the UTF-8 format. For incoming messages, the email engine
attempts to retrieve the CHARSET of the MIME messages that were received. If BMC Remedy Email
Engine receives the CHARSET form, it uses the same CHARSET to display email messages;
otherwise, it uses UTF-8.
Note
You cannot change the default UTF-8 settings of BMC Remedy Email Engine. BMC
Remedy Email Engine does not provide UTF-8 support for the MAPI protocol.
BMC Remedy AR System standards

BMC Remedy AR System server and the BMC Remedy Mid Tier adhere to the standards listed in
the following topics:
BMC Remedy AR System server standards

The AR System server provides encryption of information as it is passes over the wire. The
standard encryption provided by the AR System server is based on OpenSSL libraries
version 0.9.6m.
The AR System server provides an API that is based on ONCRPC.
AR System web services implementation is based on SOAP 1.1 and WSDL 1.1
specifications from W3C. SOAP 1.2 is supported for consuming web services only.
Security
Web service standards
BMC Remedy Mid Tier standards

Software standards ensure desirable characteristics of products and services such as quality,
environmental friendliness, safety, reliability, efficiency and interchangeability. The International
Organization for Standardization (ISO) is a developer of international standards. BMC strives to
make sure that each release of the BMC Remedy Mid Tier adheres to current standards.
Page 446 of 4705
Home
Remember these tips:

Use HTTP 1.1. (HTTP 1.0 is not supported.) Ensure that your browser uses HTTP 1.1 so
that the mid tier can take advantage of data compression, persistent connection, and chunk
transfer.
BMC supports any SSL version that is supported by each HTTP web server vendor listed on
the compatibility matrix.
The mid tier supports 32-bit and 64-bit version of Java runtime environment.
The following table lists standards supported by recent versions of the mid tier. See the
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation for potential
incompatibilities.
AR 7.5.00
AR 7.6.04
8.0 and later
HTTP/HTTPS
1.1
1.1
1.1
HTML
4.0+
4.0+
4.0+
Java Script
1.3+
1.3+
1.3+
SOAP
1.1 or 1.2
1.1 or 1.2
1.1 or 1.2
Servlet API
2.3+
2.3+
2.3+
JSP
1.2+
1.2+
1.2+
WSDL
1.1
1.1
1.1
CSS
CSS2
CSS2
CSS2
Java SDK
5.0 or 6.0
5.0 or 6.0
5.0 or 6.0
Support for IPv6

Note
BMC Remedy AR System supports IPv6 for only version 8.1 and later releases.
BMC Remedy Action Request System supports Internet Protocol version 6 (IPv6) network
addresses. You can deploy BMC Remedy AR System servers in an IPv6 configured network and
make them accessible to clients on IPv4, IPv6, or both IPv4 and IPv6 (dual stack) configured hosts.
IPv6 is an internet protocol that replaces IPv4. It expands the IP address space from 32-bit to 128bit to significantly increase the number of available IP addresses. To comply with a United States of
America federal mandate, the software products of government vendors must support operation on
IPv6 networks.
This topic provides the following information about IPv6:
Page 447 of 4705
Home
Post-installation or post-upgrade considerations

Supported operating systems for IPv6
Supported databases for IPv6
Supported database clients for IPv6
Tested web servers for IPv6
IPv6 considerations with BMC Remedy AR System
Post-installation or post-upgrade considerations

After a new installation or upgrade of BMC Remedy AR System, you must enable the LDAPJ
certificate to the certificate database for IPv6-configured networks. For more information, see
Enabling LDAP plug-ins for SSL connections post-installation or Enabling LDAP plug-ins for SSL
connections post-upgrade.
Supported operating systems for IPv6

BMC Remedy AR System supports the following minimum operating systems for IPv6:
Windows 2008 (x64-bit only)
Solaris 10 (64-bit only)
IBM AIX 6.1 (64-bit only)
HP-UX 11.31 Itanium (64-bit only)
Red Hat Enterprise Linux 6.1 (x64 only)
Novell SUSE Linux 11 (x64 only)
Note
For Windows, Java SE 7 is required for IPv6.
For Windows 2008 and earlier, all 32-bit versions support only IPv4.
Supported databases for IPv6

BMC Remedy AR System supports the following minimum databases for IPv6:
Oracle 11g R2
Microsoft SQL Server 2008
Sybase ASE 15.7
IBM DB2 9.7
Supported database clients for IPv6

BMC Remedy AR System supports the following minimum database clients for IPv6:
Page 448 of 4705
Home
Oracle 11g R2
IBM DB2 9.7
Tested web servers for IPv6

BMC tested the following web servers for BMC Remedy AR System in an IPv6 environment:
Apache 2.2
Tomcat 6.0.20
Microsoft IIS 7.0 plus Tomcat 7.0.11
JBoss 7.1.1
Oracle BEA WebLogic 10.3.2
IBM WebSphere 7.0
Note
For a reverse proxy, use Apache 2.4.
IPv6 considerations with BMC Remedy AR System

Opening forms from a browser with an IPv6 address in the URL
If an IPv6 address is used for the mid tier server name, enter the URL for a form by enclosing the
IPv6 address of the mid tier server in square brackets. Do not enclose the port number of the
server within the brackets. For example:
http://[2001:db8:123:1234:a12:1b23:4c56:d7e8]:8080/arsys/forms/<ARSystemServer>/<
formName>
For more information about using URLs to open forms, see URLs for opening forms and
applications.
Page 449 of 4705
Home
Installing
For the latest installation information, see BMC Remedy ITSM 9.0 Deployment online
documentation .
About BMC Remedy ITSM Suite 9.0

Deployment online documentation
The following graphic illustrates scope and the contents of this online documentation.
The following table describes the contents of the different branches in this online documentation.
Branch
Description
Planning the
deployment
This section describes the deployment scenarios for the following new components:
Click here for a list of topics in this section
Planning BMC Remedy Smart Reporting deployment
Planning BMC Remedy shared service architecture
Preparing
This section provides information about the preparation you must do before installing or upgrading any
component of the BMC Remedy ITSM Suite.
Click here for the list of topics in this section
Reviewing system requirements
Downloading the installation files
Obtaining BMC Remedy license keys
Preparing your database
Preparing the base platform
Preupgrade checks and configuration checks
Completing the planning spreadsheet
Page 450 of 4705
Home
Installing
This section provides information about the steps for performing a fresh installation.
Installing the platform components
Installing the application components
Installing offline documentation
Deploying BMC Remedy shared services
Upgrading
This section provides information about the steps for performing an upgrade.
Interactive end-to-end steps depending on the base version:
Upgrading from version 8.1 and later
Upgrading from a version 7.6.04 or 8.0.xx
Upgrading from a version earlier than 7.6.04
Upgrading information the individual components in the BMC Remedy ITSM Suite
Upgrading the platform
Upgrading the applications
Detailed information of different stages within the upgrade process:
Restrictions after restoring the database on the upgrade server
Setting up upgrade servers
Capturing a snapshot of your current environment
Creating overlays
Adjusting customizations when upgrading
Migrating customizations
Setting up a staging server
Updating hard-coded server hostname references
Migrating delta data
Update to the multi-tenancy model
Post-upgrade activities
Upgrading secondary servers
User acceptance testing
Cutover activities
Go live activities
Troubleshooting
This section provides information about troubleshooting the issues specific to install or upgrade.
Working with logs
Troubleshooting data and workflow import issues
Troubleshooting driver issues
Troubleshooting information for individual components in the BMC Remedy ITSM Suite
Troubleshooting BMC Remedy AR System issues
Troubleshooting BMC Atrium Core issues
Troubleshooting BMC Remedy ITSM issues
Troubleshooting Process Designer issues
Troubleshooting BMC Service Request Management issues
Troubleshooting BMC Service Level Management issues
Troubleshooting the multi-tenancy update
Page 451 of 4705
Home

After installation, BMC Remedy AR System administrators and security administrators should
review and perform the procedures in this section to secure the system and configure the AR
System server and related components. After performing the initial configuration, see the
Administering section for additional configuration and administrative tasks, such as setting up user
accounts.
Goal
Instructions
Logging on to various BMC Remedy AR System components
Logging on to the system
Managing BMC Remedy AR System licenses
Working with BMC Remedy AR

System licenses
Configuring servers to work with BMC Remedy AR System
Setting up a server group to provide fail-over protection
Configuring the BMC Remedy AR System cache
BMC Remedy AR System cache

management
Presenting application data and interacting with the user by using the BMC Remedy Mid
Tier
Using a hardware load balancer to improve the scalability and availability of the BMC
Configuring a hardware load balancer
Remedy AR System
with BMC Remedy AR System
Configuring Unicode database support to enable multiple languages on a single AR
System server
Monitor BMC Remedy AR System using the BMC Remedy SNMP Agent
BMC Remedy SNMP Agent

configuration
Configuring BMC Remedy AR System servers for a distributed environment
Configuring BMC Remedy Distributed

Server Option
Configuring BMC Remedy AR System web and crystal reports for the end users
Configuring the Assignment Engine properties and starting and stopping the engine
Configuring the Assignment Engine
Configuring and managing process administrator capabilities, configuring Approval

Server to work with flowcharts, and with a separate plug-in server instance
Configuring the BMC Remedy

Approval Server
Creating and configuring BMC Remedy Email Engine mailboxes and setting security
options
Configuring BMC Remedy Email

Engine
Manually changing the default behavior of flashboards by changing settings in the

config.properties file, and configuring flashboards
Configuring BMC Remedy

Flashboards
Licensing and logging on to BMC Remedy Migrator
Securing various aspects of BMC Remedy AR System
Securing BMC Remedy AR System
Configuring BMC Remedy Encryption Security to protect data passing between the client
and server
Configuring BMC Remedy Encryption

Security
Learn about the storage and performance impacts of using Oracle character large object
(CLOB) storage in a database table
Using Oracle CLOBs with BMC

Remedy AR System
Page 452 of 4705
Home
Logging on to the system

This section explains how to log on to various BMC Remedy AR System components:
Product or Component
See
Starting Data Import and logging on to AR System servers
Starting and logging on to BMC Remedy Developer Studio
BMC Remedy Migrator
Logging on to an AR System server using BMC Remedy Migrator
BMC Remedy Mid Tier
Logging on to the Mid Tier Configuration Tool
BMC Remedy Mid Tier
URLs for opening forms and applications
Modifying the config.properties file

This topic describes how to modify the config.properties file for this version of BMC Remedy Mid
Tier. You can manually change the default behavior of the mid tier by changing the settings in the
config.properties file.
The config.properties file is installed in the following directory:
<midTierInstallationDir>\WEB-INF\classes\config.properties
Note
The default value of midTierInstallationDir is C:\Program Files\BMC Software\
ARSystem\midtier.
You can modify the config.properties file to:

Change the default format of flashboards.
Customize the cache behavior.
Page 453 of 4705
Home
Change the number of entries in a report.

Configure the wait time for detecting a HOVER event.
Modify the wait cursor for actions when customizing views for forms or turn off the wait
cursor.
Set up a mid tier server to use cache table statistics.
Enable the HTTP TRACE function to return HTTP header information.
Working with BMC Remedy AR System

licenses
The following topics provide information about licensing BMC Remedy AR System:
Adding or removing licenses
Exporting or importing licenses
Displaying and Tracking server group license usage
Reviewing license usage
Generating a license usage report
Licensing for server groups

You can add or remove licenses, follow the given procedures.
Adding licenses
Removing licenses
Related Topics
Adding licenses
To add licenses to a BMC Remedy AR System server, you can enter them into a form or import
them from a file. Licenses are active as soon as they are added to the server.
To add licenses by entering them into a form

1. In the AR System Administration Console, click System > General > Add or Remove
Licenses.
Add or Remove Licenses form
2.
Page 454 of 4705
Home
2. In the Add or Remove Licenses form, click Add New.

3. In the fields under the table, enter the following information:
Fields in Add or Remove Licenses form
Field
Description
License
Type
From the list, select the type of license to activate. You can also enter a custom license type that is not in
the list.
Note
You can add only one entry for each license type except server licenses (multiple server licenses
are distinguished from each other by license keys). To increase or decrease the number of
licenses available for other license types, modify the existing entry.
Number
of
For the specified license type, enter the appropriate number of licenses.
Server, server option, and application licenses
Licenses
0 indicates the license is inactive.

1 indicates the license is active.
User licenses
0 indicates the license is inactive.
Any number greater than 0 indicates the maximum number of licenses available for use.
License
Qualifier
Used to further identify license behavior

Do not modify the contents of this field unless instructed to do so by BMC or a qualified BMC partner.
Key
(Server licenses only) Enter the appropriate license key in this field. To get a key, see Obtaining BMC
Remedy license keys.
Note
Do not enter a 6.0-7.0.x key in this field. Instead, import it from a .lic file. See Importing licenses.
Expiration
Date
For trial licenses, enter the date after which the license is no longer in effect. (In BMC Remedy AR System
7.1.00 and later, only trial licenses expire.)
4. Click Save.
To add licenses by importing them

See Importing licenses.
Removing licenses
To remove a BMC Remedy AR System license from a server, follow this procedure:
Licenses.
2. In the table at the top of the form, select the license to remove.
3. Do one of the following:
Click Delete, and then click OK in the confirmation message.
4.
Page 455 of 4705
Home
4. Set the Number of Licenses field to 0, and then click Save.
Note
Nonserver license removals take effect immediately. To remove a server license,
however, you must restart the server after removing the license.
Related Topics

You can use the Add or Remove Licenses form to export or import licenses.
Exporting licenses
Importing licenses
Related Topics
Exporting licenses
You can export license information in the Add or Remove Licenses form to a . lic file to create a
backup copy. You must export all the licenses, you cannot select specific licenses to export.
To export AR System licenses

Licenses.
2. Click Export Licenses to File.
3. In the Save Attachment dialog box, navigate to the directory in which to save the . lic file.
4. In the File name field, enter a name for the license file or accept the default ( arsystem.lic).
5. Click Save.
Importing licenses
To import licenses from BMC Remedy AR System 7. x or 6.x. lic files into a BMC Remedy AR
System 7.1.00 or later server, use this procedure.
Notes
Except for AR Server licenses, license keys are not imported. In addition, expired licenses
are not imported.
Page 456 of 4705
Home
In BMC Remedy AR System 7.1.00 or later, dedicated server licenses -provided for
common components such as the BMC Atrium Definitive Software Library or CMDB- are
not used. If you had a dedicated server license in a previous release, it is upgraded at no
cost to a full AR Server license when you import your licenses. In addition, licenses for
any applications associated with the dedicated server are automatically added to your
system.
To import AR System 7. x or 6. x licenses

Licenses.
2. Click Import Licenses from File.
3. In the Add Attachment dialog box, navigate to the location of the license ( .lic) file to import.
4. Select the file name to add it to the File name field.
5. Click Open.
6. When asked "Do you want to overwrite any matching licenses? ," click one of these
buttons:
No Merges the contents of the .licfile with the contents of the Add or Remove
Licenses form as follows:
When the form and the .lic file contain a matching license type, the entries for
that type are not imported from the .licfile.
Example
If the form has an entry for five AR User Fixed licenses and the .lic file
has an entry for three AR User Fixed licenses and another entry for four
AR User Fixed licenses, the form retains its entry, and neither entry is
imported from the .lic file.
When the .licfile contains multiple entries for a particular license type and the
form contains no matching entry, all entries in the file are imported into the
form and merged into one entry.
Example
If the form has no entries for AR User Fixed licenses and the .lic file has
an entry for three AR User Fixed licenses plus another entry for four AR
User Fixed licenses, the two entries in the .lic file are merged into one
entry in the form. The new entry in the form is for seven AR User Fixed
licenses.
Page 457 of 4705
Home
Yes Clears the contents of the form and replaces it with the contents of the .licfile.
Multiple entries in the file for the same license type are merged into one entry in the
form.
Warning
Select Yes only to update all your licenses. This option deletes all
information from the form. To replace deleted information, you must reenter
it. SeeAdding licenses.
7. In the confirmation message, click OK.
Related Topics

The following topics provide information about the license usage forms and how to track license
usage:
AR System Current License Usage form
AR System Historical License Usage form
Recording data in the license usage forms
Tracking server group license usage
Related Topics
AR System Current License Usage form

The AR System Current License Usage form tracks all licenses in use on the server.
Fields in AR System Current License Usage form
Field
Description
User Name
Name of the user who acquired the license
Group ID
ID of the pool that the license belongs to (applies only to floating licenses)
Application
Name
Application that the license applies to
License
Type
Type of license (fixed, floating, and so on)
Server
Name
Server to which the license is applied
Page 458 of 4705
Home
Field
Description
Time
Acquired
Time that the user acquired the license
Note
When BMC Remedy AR System starts recording data in this form, it creates records for every license in
use. Those records include the time that each license was acquired (or consumed), not the time that
recording started. For example, if a user acquires license A at 10:15 A.M. and BMC Remedy AR System
starts recording data in this form at 10:30 A.M., the Time Acquired for license A is 10:15 A.M.
Type of
Record
Type of record used to track license usage:

Main This record is used as follows:
For licenses not in server groups, this is the only record created to track usage.
For licenses in server groups. this is the parent record that tracks the total usage of a particular type
of license.
Subrecord (server group only) A child of a main record
When a license is initially acquired in a server group, both a main record and a subrecord are created. If the
user acquires another license of the same type on another server in the group without releasing the first
license, the second license is recorded as another subrecord of the main record. The same is true for all
additional licenses of that type acquired within the server group while the main record has at least one
subrecord. See Tracking server group license usage.
To get a report about license usage, see Generating a license usage report. You can also get
information about what type of license a user has by searching the user form.
Note
To record information in this form, you must turn on the Enable License Tracking option.
See Recording data in the license usage forms .
AR System Historical License Usage form

If a user releases a license while the Enable License Tracking option is on, an entry is added to
the AR System Historical License Usage form. The entry contains information about the usage of
that license.
Fields in AR System Historical License Usage form
Field
Description
User Name
Name of the user who acquired and released the license
Group ID
ID of the pool that the license belongs to. Applies only to floating licenses
Application Name
Application that the license applies to
License Type
Type of license (fixed, floating, and so on)
Page 459 of 4705
Home
Field
Description
Time Acquired
Time that the user acquired the license
Time Released
Time that the user released the license
Total Use Time
The total amount of time in seconds that the license was in use
Note
To record information in this form, you must turn on the Enable License Tracking option.
See Recording data in the license usage forms .
Recording data in the license usage forms

By default, BMC Remedy AR System does not record data in the AR System Current License
Usage and AR System Historical License Usage forms.
To record data in the license usage forms

1. In the AR System Administration Console, click System > General > Server Information.
2. On the Configuration tab, select the Enable License Tracking option.
3. Save your changes.
BMC Remedy AR System immediately starts recording data in the license usage forms. You
do not need to restart the AR System server.
To stop recording data in the license usage forms

Clear the Enable License Tracking option, and save your change.
All data in the AR System Current License Usage form is lost when
The Enable License Tracking option is switched off.
A standalone server is stopped.
All servers in a server group are stopped.

When a user first acquires a particular type of license in a server group, the acquisition is recorded
in the AR System Current License Usage form as a main record and a subrecord. For example, for
a user currently logged into the system, there is one main record, and for every server in the server
group the user is logged, there is one sub-record.
If the user acquires another license of the same type on another server in the group without
releasing the first license, the second license is recorded as another subrecord of the main record.
The same is true of all additional licenses of that type acquired while the main record has at least
one subrecord.
Page 460 of 4705
Home
When the user logs out of the sessions from a server by releasing one of his licenses, its subrecord
for the license is deleted. When the last subrecord is deleted, it indicates that the user has logged
out and released all the licenses from the server, the main record is also deleted and an entry for
the entire session tracked by the main record is added to the AR System Historical License Usage
form.
Related Topics

To ensure that your usage is in compliance with your purchased licenses, you can periodically
generate a license usage report for each of your AR System servers (including each server in a
server group). To gather information about license usage, each AR System server scans the
system approximately every 45 minutes and writes the results to a file named LicenseReport.txt.
Note
If you have more than one AR System server, regardless of their starting or restarting time
, the logging time stamp is synchronized across the servers and the required information
is logged in the file at the same time.
In this topic:
Reporting license usage within a date range
Verifying purchased licenses
Related Topics
The report contains the following information:
For BMC Remedy AR System and application user fixed licenses, the greatest number of
licenses assigned at the same time during the period covered by the report
For BMC Remedy AR System and application user floating licenses, the greatest number of
licenses in use at the same time during the period covered by the report
For each type of license, the maximum limit specified in the Add or Remove Licenses form
For BMC Remedy AR System and application server group licenses, the usage of licenses
across the entire server group, including the individual server against which the report is run
Note
Page 461 of 4705
Home
Although all servers in a server group use licenses from the same Add or Remove
Licenses form, each server in a group generates its own LicenseReport.txt file.
For BMC Remedy AR System and application server group licenses, the server group name
and the host ID
The report is written to a file named ReportResult.csv. You can generate it from the Administration
Console.
License usage report
To generate a license usage report

Licenses.
2. In the Add or Remove Licenses form, click Generate License Usage Report.
3. Click the calendar icon next to the License Report Start Date field, and select a date from
the calendar.
The start time is 12:00:00 A.M. on the specified date.
4. Click the calendar icon next to the License Report End Date field, and select a date from
the calendar.
The end time is 11:59:59 P.M. on the specified date.
Note
- If the selected start or end date exceeds the time period covered by the server,
the first or last date covered by the server is used instead. The time period covered
by the report is specified in the report header.
- Make sure that the time zone for BMC Remedy Mid Tier and BMC Remedy AR
System server is same, to map the start and the end date requested while
generating the License Usage Report. If the time zone for BMC Remedy Mid Tier
and BMC Remedy AR System server is different, the time zone for BMC Remedy
AR system server is considered.
Page 462 of 4705
Home
5. Click Generate Report.

A message specifying the location of the ReportResult.csvfile appears. By default, the file
is stored in this directory:
(UNIX) ARSystemServerInstallDir/Db
(Windows) ARSystemServerInstallDir\ARServer\Db
6. Click OK.
The license usage report is displayed in a CSV-compatible viewer, such as Microsoft Excel.
Note
You can also use the produse.exe utility to generate a license usage report. See
Generating a license usage report.
Reporting license usage within a date range

By default, the information in the license usage report is based on all the license usage data stored
on the server. To limit the information in the license usage report, specify a date range when
running a license usage report.
Verifying purchased licenses

To obtain an up-to-date list of your AR System licenses, you can request a reconciliation report of
purchased licenses from BMC. Contact your BMC Sales representative or Customer Support ( see
Support information).
Related Topics

To gather information about license usage, each BMC Remedy AR System server scans the
system approximately every 45 minutes and writes the results to a file named LicenseReport.txt.
You can use the produse.exe utility to generate a license usage report based on the information in
LicenseReport.txt for each of your BMC Remedy AR System servers.
Note
Although all servers in a server group use licenses from the same Add or Remove
Licenses form, each server in a group generates its own LicenseReport.txt file.
Page 463 of 4705
Home
To use produse.exe to generate a license usage report

1. Go to the directory that contains the produse.exe utility:
(UNIX) ARSystemServerInstallDir/bin
(Windows) ARSystemServerInstallDir
Important
Before running produse.exe on UNIX platforms, make sure the
ARSystemServerInstallDir/bin directory is in the library path environment

variable: LD_LIBRARY_PATH (Linux, Solaris), LIBPATH (AIX), or SHLIB_
PATH (HP-UX).
2. At the prompt, enter this command:
produse [-i <inputFilePath>] [-o <outputFilePath>] [-s <startDate>] [-e <endDate>] [-r]
Where
-i
Specifies the full or relative path to the input file. By default, the input file is LicenseReport.txt and is in this directory:
(Windows) ARSystemServerInstallDir/ARServer/Db
If this parameter is not specified, the current directory and the LicenseReport.txt file name are used.
Specifies the full or relative path to the output file. By default, the output file name is ReportResult.csv and is in this directory:
o
(Windows) ARSystemServerInstallDir/ARServer/Db
To rename it, specify a different file name. If this parameter is not specified, the current directory and the
ReportResult.csv file name are used.
Specifies the start date of the report in D/M/YYYY format. The start time is 12:00 A.M. on the specified date. If this parameter
is not specified, the report includes data from the beginning of the LicenseReport.txt file. If this parameter exceeds the range
covered by the LicenseReport.txt file, the range covered by the file is used instead, and that range is indicated in the report
header.
Specifies the end date of the report in D/M/YYYY format. The end time is 12:00 P.M. on the specified date. If this parameter is
not specified, the report includes data to the end of the LicenseReport.txt file. If this parameter exceeds the range covered by
the LicenseReport.txt file, the range covered by the file is used instead, and that range is indicated in the report header.
Backs up the current LicenseReport.txt file by renaming it LicenseReport- fileCreateDate- currentDate.txt and generating a
new LicenseReport.txt file.
Note
Page 464 of 4705
Home
You can also generate a license usage report from the Administration Console. See
Generating a license usage report.
Related Topics

Because servers in a server group use the same database, they share licenses. Each AR System
server must have its own AR Server license key, but the server group feature shares all other BMC
product licenses with all of the servers in the group. So for any product in a server group, when you
install the license, since it gets stored in the database shared by all the servers, it only has to be
installed one time. This registers it for all servers in the group.
To add a server license, see Adding licenses.
All other license types, such as all types of Fixed and Floating user licenses and application
licenses, are stored in the database and are therefore shared by all servers in the server group.
You can add these other product licenses at any time. However, for all AR System servers, except
the first server, the license must be added prior to installing the server.
Related Topics

Every BMC Remedy AR System server has a variety of configuration settings that control how the
server works and how it interacts with users. Configuration settings are specific for each server.
Use the AR System Administration: Server Information form from the BMC Remedy AR System
Administration Console to display information about the selected server and to set server options.
You must be an administrator to make changes.
For more information about the BMC Remedy AR System Administration Console, see Navigating
the BMC Remedy AR System Administration console interface .
The following table lists the tabs in the AR System Administration: Server Information form. The
information provided in each tab is described in the sections that follow.
Page 465 of 4705
Home
Tabs in the AR System Administration: Server Information form

Tab
Information
See
Advanced
Sets parameters related to AR System efficiency, security, and localization.
Setting performance and

security options
Configuration
Sets configuration options.
Setting administrative
options
Connection
Settings
Enables you to configure passwords used between the AR System server and its
external subsystems.
Setting server passwords,

RPC options, and plug-in
timeouts
Currency
Types
Specifies currency types available in AR System.
Setting currency types
Database
Displays information about the database that the selected server communicates with
. You also define a database password and configuration file location in this tab.
Setting database options
DSO
Configures options for distributed operations.
Configuring BMC Remedy

Distributed Server Option
EA
Sets parameters necessary for AR System to authenticate users to external

systems.
Setting external
authentication
options
Configuring the AR
System server for
external
authentication
Encryption
Enables you to view and modify your AR System server's encryption configuration.
Activating and
deactivating encryption
security
Full Text
Search
Configures full text search (FTS) options.
Configuring Full Text

Search
Licenses
Displays the type and number of BMC Remedy AR System licenses on a server.
You also set the Submitter Mode in this tab.
Setting license options
Log Files
Enables the logging for various log files. You also set the log level in this tab.
Setting log files options
Log Filtering
Enables you to apply restrictions on the AR System server logging, based on one or
more parameters.
Configuring AR System
server logging
Platform
Displays information about the platform on which the selected server is running.
Setting platform options
Ports and
Queues
Configures BMC Remedy AR System to communicate with client tools, services,

and other servers on the network. Displays information relevant to the user of the
multiple threads in the AR System server.
Server
Events
Sets the options for logging internal server changes.
Setting ports and

RPC numbers
Configuring a
server for alerts
Defining queues
and configuring
threads
Setting server logging

options
Page 466 of 4705
Home
Tab
Information
See
Timeouts
Sets various timeouts for the selected server.
Setting timeout options
Version
Control
Sets source control integration within BMC Remedy AR System.
Setting version control

options
WS Registry
Integration
Enables the use of the AR System Web Service Registry form by configuring a
connection to a BMC Atrium Web Services Registry. Also provides a button to
update the registry.
Setting a connection to
the BMC Atrium Web
Services Registry
Atrium SSO
Integration
Enables the integration of the AR System server with the Atrium SSO server for the
purpose of single-sign on.
Setting a connection to
the BMC Atrium SSO
server
Server
Statistics
Sets parameters related to server statistics.
Setting server statistics

options
Attachment
Security
Enables you to restrict users from uploading and viewing files with certain
extensions in BMC Remedy Mid Tier.
Setting security
restrictions on file uploads
Note
BMC recommends using the AR System Administration: Server Information form to
change server settings, but you can also change settings manually in the server
configuration file (ar.cfg or ar.conf). See ar.conf (ar.cfg).
You also need to perform the following tasks while configuring AR System servers:
Configuring firewalls with AR System servers
Configuring clients for AR System servers
Configuring a server to use plug-ins
Note
For information about the mid tier and BMC Remedy Mid Tier Configuration Tool, see
Accessing the Mid Tier Configuration Tool .
Configuring clients for AR System servers

When servers are configured to run on specific TCP ports, the clients must be configured to match.
Important
The specifics of your firewall configuration vary from manufacturer to manufacturer. Ask
the network and security professionals at your company for more information.
Page 467 of 4705
Home
For more information about TCP port numbers, see Assigning TCP port numbers to AR System
servers.
To access private queues, client computers must either set the appropriate RPC and TCP values in
the Accounts dialog box, or have the ARRPC and ARTCPPORT environment variables set.
Port 111 is used for Portmapper, and this port can be blocked for requests coming through the
firewall. Internal requests are affected by this rule because Register-With-Portmapper: T is the
default configuration setting of the portmapper. See the discussion in Configuring a server to use
plug-ins.
Configuring firewalls with AR System servers

This section describes the connections required to connect to an AR System server through a
firewall, without using a portmapper. A firewall is a security system that acts as a protective
boundary between a network and the outside world.
In the following figure, the BMC mid tier client connects to a specific port of the AR System server.
When the user makes a request of the AR System server, the response is returned on the same
TCP connection that makes the request. For more information about setting ports, see Setting ports
and RPC numbers.
Transmitting through a firewall
To enable these connections through the firewall, the AR System server and the client must be
configured to communicate on the proper ports:
AR System server The AR System administrator assigns a specific port number in the
Server TCP/IP Port box as described in Assigning TCP port numbers to AR System servers .
Client In the browser, the administrator or user configures the Advanced Server
Properties in the Accounts dialog box as described in Configuring clients for AR System
servers. In BMC Remedy Developer Studio, the administrator configures the Server List
accessed from the Login window. This informs the clients of the location on the firewall
through which they can connect to AR System servers.
Page 468 of 4705
Home
Tip
When a firewall or a load balancer exists between clients and BMC Remedy AR System
server, you must set the TCP "keep alive" value properly. The operating system of the
host BMC Remedy AR System server maintains the keep-alive socket (not the client).
Make sure that the keep-alive value on the firewall or load balancer is at least as long as
or longer than the keep-alive value on the largest host server of all BMC Remedy AR
System servers connected to the firewall or load balancer.
Running a stand-alone AR System server on Windows

On Windows, you can run a stand-alone BMC Remedy AR System server, which is disconnected
from the network (for example, on a laptop computer).
To run a stand-alone BMC Remedy AR System server

1. Open the C:\WINDOWS\system32\drivers\etc\hosts file (or the drive on which Windows
server is installed).
2. Enter the following alias entry:
<IPAddress> <localHostName>.<domainName> <localHostName>
Example
174.21.8.109 coyote.acme.com coyote
Many configurations of Windows require you to remove all DNS servers when running as a
stand-alone server. This avoids long pauses caused by the Windows networking software
trying to communicate with the network during BMC Remedy AR System interaction. Write
down what you removed so that you can add it back when reconnecting to the network.
3. Save the file.
4. Shut down and restart the system.
Configuring a server for alerts

To enable users to receive alerts from the server through the Alert form, you must configure your
server.
The earlier Notification Server command-line configuration options are not available in BMC
Remedy AR System 5.0 or later.
Page 469 of 4705
Home
To configure a server to send alerts

1. In a browser, open the AR System Administration Console, and click System > General >
Server Information.
The AR System Administration: Server Information form appears.
2. Click the Server Ports and Queuestab, and perform the following steps:
a. In the Alert Outbound Port field, enter the port number that the server uses when
sending alerts. If you enter 0, the server uses random port selection.
b. Configure the Alert queue, and adjust the minimum and maximum threads. For more
information, see Setting ports and RPC numbers.
3. Click the Timeouts tab, and in the Alert Send Timeout (seconds) field, enter the number of
seconds the server must wait during connection attempts before timing out.
4. Click the Configurationtab, and perform the following steps:
a. Select the Verify Alert Users check box to have the server verify at boot-up time that
each of the users it thinks is registered is still running and listening for alert messages
.
b. Select the Disable Alerts check box so that the server does not send alert messages
when alert events are entered into the system.
5. Click OK to close the form.
6. If you want the server to translate IP addresses before sending alert messages to users, edit
the Map-IP-Address option in the ar.conffile, see
Map-IP-Address in ar.cfg or ar.conf options E-M.
Configuring the AR System server for external authentication

After you install an AREA plug-in, you can set up the AR System server to use external
authentication. Users can be authenticated externally in the following ways:
To the operating system (UNIX only) The AR System server authenticates to the
operating system. The authentication string has no effect when authenticating to a UNIX
operating system.
To the server domain (Windows) The AR System server authenticates to the Windows
server domain. If a value is entered in the Authentication String field, that value is used as
the domain name to which the AR System server authenticates.
To the AREA service If you have configured external authentication to an AREA service,
the user name, password, and authentication values entered are provided to the AREA
service.
Note
Two of these authentication methods use the authentication string described in Login and
session information. See also Setting up an authentication alias.
Page 470 of 4705
Home
Before configuring external authentication for an AREA service, you must configure your server to
use plug-ins (see Configuring a server to use plug-ins). You must also start the plug-in server ( see
AR System server components and external utilities ).
After the service is started, set up the server for external authentication as described in the
following procedure.
To configure the AR System server for external authentication

Server Information.
2. In the AR System Administration: Server Information form, click the EA tab.
3. To enable authentication using an AREA service, set the External Authentication Server
RPC Program Number to 390695.
Entering 390695 enables authentication using an AREA service. Entering no value or 0
disables authentication using an AREA service.
If you enter 0, the AR System server makes no attempt to communicate with the AREA
server.
4. Set the RPC and SYNC time-outs for External Authentication.
External Authentication Timeout (seconds)is the amount of time within which the AREA
server must respond to a call from the Plug-in server before an error is returned. The options
are
RPC Used when making calls to the AREA server
If set to 0, the AR System server does not invoke the call to the external
authentication server. The default is 40 seconds.
Need To Sync The interval for periodically invoking the AREA server's
AREANeedToSyncCallback() call. If set to 0, the AR System server does not invoke
the call to the external authentication server. The default is 300 seconds.
5. Select one or both of the following settings:
Authenticate Unregistered Users Specifies that all users in the User form can log
on and be authenticated internally; users not in the form are authenticated externally.
If this option is cleared, AR System stops the validation process and manages the
user as a guest user.
Cross Ref Blank Password Specifies that all users in the User form can log on
and be authenticated externally if the Password field in the form is left blank for that
user. If Cross Ref Blank Password is cleared, a blank Password field in the User
form is treated as no password for that user, and that user is allowed to log on.
6. Optionally, specify an authentication chaining mode.
Authentication chaining modes
Mode
Description
Off
Disables authentication chaining.
Page 471 of 4705
Home
Mode
Description
ARS - AREA
BMC Remedy AR System tries to authenticate the user by using the User form and then the AREA
plug-in.
AREA - ARS
BMC Remedy AR System tries to authenticate the user by using the AREA plug-in and then the User
form.
ARS - OS AREA
BMC Remedy AR System tries to authenticate the user by using the User form, then Windows or UNIX
authentication, and then the AREA plug-in.
ARS - AREA
- OS
BMC Remedy AR System tries to authenticate the user by using the User form, then the AREA plug-in,
and then Windows or UNIX authentication.
7. Specify Group Mapping options:

Ignore Excess Groups Specifies that authentication requires that, for a given user
, at least one LDAP group must match a BMC Remedy AR System group.
Non-matching groups are ignored. If this option is cleared, authentication occurs only
when each LDAP group matches a BMC Remedy AR System group.
Group Mapping Specifies mappings between LDAP groups and BMC Remedy AR
System groups. This eliminates the need for one-to-one matches between LDAP and
BMC Remedy AR System groups. If you do not map groups, each LDAP group must
have an exact BMC Remedy AR System group match.
Tip
For maximum benefit, use Ignore Excess Groups and Group Mapping
together.
8. Save your settings.

The settings you specify persist across server restarts.
Configuring a server to use plug-ins

You might want to use plug-ins for these purposes:
AR System database connectivity (ARDBC) Used to create a BMC Remedy AR
System vendor form to access external data
For information about vendor forms, see Creating vendor forms.
AR System external authentication (AREA) Used to resolve user accounts against
directory services.
AR System filters (ARF) Used to make a call from workflow to external services and to
capture returned data.
Page 472 of 4705
Home
BMC Remedy AR System supports the plug-in server and API, but if you have problems with a
specific plug-in, contact the plug-in service provider for assistance.
For more information about creating ARDBC, AREA, or ARF plug-ins, see Enabling Plug-ins.
To configure a server to use plug-ins

1. Modify these settings in the ar.cfg file (Windows) or ar.conf file (UNIX):
Plugin
Number of threads, for example:
Plugin-ARDBC-Threads
Plugin-AREA-Threads
Plugin-Filter-API-Threads
Plugin-Log-Level
Plugin-Port
Server-Plugin-Alias
Server-Plugin-Default-Timeout
2. Modify the plug-in target password ( Configuring server groups).
3. Modify the plug-in log file settings ( Setting log files options).
Related topic:
ar.cfg or ar.conf
Setting version control options

Use the Version Control tab to enable or enforce version control features on the AR System
server. See Licensing AR System.
To set options for version control

Server Information.
2. Click the Version Control tab.
AR System Administration: Server Information form Version Control tab
3. Edit the options, as needed:

Version Control tab fields
Page 473 of 4705
3.
Home
Field Name
Description
Object
Reservation
Selecting Enforced causes the server to require object reservation. See Using object reservation.
Note
If you are logged in to the server in BMC Remedy Developer Studio when you enable object
reservation, you must log on again before you can reserve objects.
See To give sub-administrators access to an AR System server with object reservation enforced .
Object
Modification
Log
Selecting Enabled causes the server to log every change to objects. See Using the object modification
log.
Save
Definition
Files
Selecting Yes causes the server to write a definition file each time an object is created or changed. This
option is available only when the object modification log is enabled.
To give sub-administrators access to an AR System server with object reservation

enforced
1. Create a group with:
Group Type set to View.
Group Category set to Computed.
Group Definition set to Sub Administrator.
This group contains all users in the Sub Administrator group.
2. Grant the group Hidden permission (not sub-administrator permission) to the AR System
Version Control: Object Reservation form. A user must have access to this form to connect
to a server using BMC Remedy Developer Studio.
Setting timeout options

Use the Timeouts tab to set the timeouts for the selected server.
To set timeouts
Server Information.
2. Click the Timeouts tab.
AR System Administration: Server Information form Timeouts tab
Page 474 of 4705
Home

Timeouts tab fields
Area
name
Field
Name
Description
Process
Timeout
Prevents a server from being blocked when a process requested in a Set Fields filter or
(
seconds
The server waits a specified interval and then returns a $NULL$ value even if the process is
incomplete. The default is 5 seconds. The minimum is 1, and the maximum is 60. Specifying long
intervals can increase the response time for users.
Alert
Send
Timeout
(
seconds
)
Sets the time limit for making contact with alert clients.
Filter
Sets the time limit (in seconds) for the Filter API RPC to respond to the server's request.
The default is 40 seconds. The minimum is 1, and the maximum is 300.
API
RPC
escalation action does not return a value soon enough.
Two attempts are made to deliver an alert and if the second attempt fails, the alert registration is
removed. The default is 7 seconds.
Timeout
(
seconds
)
Floating
License
Timeout
(hours)
Write
Sets a time limit for how long a floating license remains reserved if the user is not accessing AR
System.
When a user is using a floating license, a license is reserved while the user is connected to the
server. If the user does not perform an AR System operation for the period of time specified in
this field, the license is automatically released back to the pool of available licenses. The client
tool must acquire a license for the user again when the next licensable operation occurs. The
default is 2 hours. The minimum is 1, and the maximum is 99.
Currency
Ratio
Cache
Refresh
Interval (
minutes)
Client
Refresh
Interval
Sets the interval (in minutes) that clients (for example, the Web) use when refreshing currency
conversion ratios stored on the server.
This refresh action makes sure that calculations for functional currencies are up to date.
4. Click Apply.
Setting a connection to the BMC Atrium SSO server

Use the Atrium SSO Integration tab to configure a connection to the BMC Atrium SSO server. To
configure the connection to the BMC Atrium SSO Solution, see Configuring the connection to the
BMC Atrium SSO integration.
Page 475 of 4705
Home
Setting a connection to the BMC Atrium Web Services Registry

Use the WS Registry Integration tab to configure a connection to the BMC Atrium Web Services
Registry. To use the AR System Web Services Registry form to register web services, you must
first configure this connection. See Registering a web service.
For more information about the BMC Atrium Web Services Registry, see Web Services Registry
and web service registration.
Setting platform options

Use the Platform tab to view information about the platform on which the selected server is running
.
To display platform information about the selected server

Server Information.
2. Click the Platform tab.
AR System Administration: Server Information form Platform tab

Platform tab fields
Field
Description
Server
Version
Displays the version number of the BMC Remedy AR System software on the server.
Server
Directory
Displays the folder (directory) where the AR System server is installed on the server system.
Hardware
Displays the hardware platform on which the server is running.
This value corresponds to the $VERSION$ keyword.
This value corresponds to the $HARDWARE$ keyword.

Operating
System
Displays the operating system software version running on the server system.
Server
Name
Alias
Specifies an alias that is always interpreted as the current server.

An alias enables you to use a functional name for a server rather than a computer name (for example,
This value corresponds to the $OS$ keyword.
ACME or HelpDesk). Do not enter a fully qualified domain name. An alias makes it easier to move workflow
between computers. Entering an alias in this field does not automatically assign an alias to the server. The
Page 476 of 4705
Home
Field
Description
network environment must reflect a change to the server name before entering the alias name in this field.
The alias name must be a valid host name on your network. If you change your server name alias, make
sure you supply the alias to the DNS or enter the alias name in your hosts file. Otherwise, your AR System
server cannot connect to the plug-in server. After you change the server environment, users can log on to
the browser by using the new server alias, just like any other server name. See your network operating
system documentation for information about creating an alias for the server.
Server
Time
Displays the current time on the server (in the local time zone).
4. Click Apply.
Setting log files options

Use the Log Files tab to set one or more of the log files shown in the AR System Administration:
Server Information form--Log Files tab figure. BMC Remedy AR System creates log files or forms
containing information about system activity.
After being activated, logging starts immediately. You can activate logging at any time.
Warning
Do not keep logging turned on continuously. Log files can consume increasing amounts of
disk space as messages accumulate unless you limit the log file size. Monitor your disk
resources carefully while logging is active. After you activate logging for workflow objects,
logs are created for only those workflow objects that are processed after that activation.
Log files location

On the Log Files tab, the default location for log files is
(Windows) ARSystemInstallDir\Arserver\Db
(UNIX) ARSystemInstallDir/db
You can enter a different location. You can also specify the same location and file for multiple types
of logging so that all data is logged to a single file.
Log forms considerations

If you choose to log activity to a form, users can query the log form like any other BMC Remedy AR
System form.
During server installation, all the predefined log forms are imported into ARSystemInstallDir\AR
SystemserverName\ARServer\SystemForms\en. The definition file names begin with LogForm.
They are treated as system forms and are recovered from this definition file whenever the AR
System server restarts.
Page 477 of 4705
Home
Each supported log type has a separate form, and a common form (AR System Log: ALL)
accommodates all types of logging information. You can specify whether the information should be
logged to a specific form or the common form.
The log forms are identified with their reserved fields. This enables administrators to rename the
forms at any time using BMC Remedy Developer Studio. Request IDs can be used to sort the log
entries when troubleshooting.
The following options in the AR System server configuration file help identify the forms to which
information is being logged:
Log-Form-Selected (see Log-Form-Selected)
Log-To-Form (see Log-To-Form)
Types of logs
The following table lists the types of logs you can create.
Types of logs
Type of
log
Description
Default file
name
Default
form
name
API
Logs information about all API calls made by all clients.

This information is logged on entry and exit of every API call.
arapi.log
AR
System
Log: API
Escalation
Logs information about escalation activity.

This information includes the escalations that executed, whether the escalation
arescl.log
AR
System
qualification found any matches, and any escalation actions taken.
Log:
Escalation
Filter
Logs information about filter activity for each operation.

This information includes the filters that tried to execute and all filter actions performed.
arfilter.log
AR
System
Log: Filter
SQL
Logs SQL commands sent to the database.

This information is logged for each SQL command issued, including a time stamp and
the user name of the user performing the operation.
arsql.log
AR
System
Log: SQL
Thread
Logs information about threads being started and restarted on the server.
arthread.log
AR
System
Log:
Thread
User
Logs information about connection activity for each user.

This information includes whether the user can obtain a license and when each floating
license is released. This enables you to keep an audit trail of user activity to help you
determine whether you need more floating licenses.
aruser.log
AR
System
Log: User
Alert
Logs detailed information about user registration and about the generation and delivery
of alerts.
aralert.log
Page 478 of 4705
Home
Type of
log
Description
Default file
name
Default
form
name
AR
System
Log: Alert
Full Text
Index
Logs information about full text search indexer activity.
arftindx.log
AR
System
Log: Full
Text
Index
Server
Group
Logs information about server group activity.

Records information about the starting and stopping of operations, the evaluation of
other servers, and the timing of each event.
arsrvgrp.log
AR
System
Log:
Server
Group
ARFORK (
UNIX only)
On UNIX systems, logs all arforkd activity (a process that reduces the amount of
memory an AR System server uses when forking new processes).
This file is not subject to the maximum file size specified in the Maximum Log-File Size
field.
arfork.log
No form is
created
for
DSO
If you are licensed for Distributed Server Option (DSO), logs information about DSO
server activity. See BMC Remedy Distributed Server Option logging.
ardist.log
No form is
created
for DSO.
Plug-In
Server
Logs the events of plug-ins that AR System uses. For more information about plug-ins,
see Enabling Plug-ins.
arplugin.log
No form is
created
for the
plug-in
server.
Archive
Log
Logs information about scheduled or on-demand archive by any user. For more
information about archiving, see Archiving overview.
ararchive.log
AR
System
Log:
Archive
arforkd.
For more information, see Analyzing logs.
To set log files or forms

Server Information.
2. Click the Log Files tab.
AR System Administration: Server Information form Log Files tab
Page 479 of 4705
Home
3. Select the check box next to each log that you want to create.
4. Select the type of log to create: File or Form.
Note
When the Form option is selected, various LogFiles.txt are created under the
ar_install_dir/bin directory on UNIX. Because this behavior is as designed, you
must provide read-write access to the ar_install_dir/bin directory to make sure
that this functionality works correctly.
5. In the Namefield, specify the full path to the log file or the name of the form.
Important
When naming log files, do not use special characters such as a forward slash
a question mark
or
. Use alphanumeric characters only.
6. To view a log file or form for any selected log, click View.
Log forms are opened in the Search mode.
7. Edit the other options, as needed:
Log Files tab fields
Field
Name
Description
Plugin Log
Level
Specifies the level of logging for the plug-in server. The options are
All All log information. The default value is 100.
Finest Code-level information. The default value is 400.
Finer Logs tasks as they are executed within the system. The default value is 500.
Fine Internal exceptions. The default value is 600.
Config Configuration, status, severe, and warning messages. The default value is 700.
Info Status, severe, and warning messages. The default value is 800.
Warning Severe and warning messages. The default value is 900.
Severe Only severe messages. The default value is 1000.
Page 480 of 4705
Home
Off None. The default value is 10000.

Log-File
Creation
Defines how logs are created. The options are

Create Backup Creates new log files, and the contents of the previous log files are written to
logName.bak files.
Append to Existing Log files and their contents are preserved, and new information is
appended to them.
Client-Side
Logging
Group
Defines the group that can use logging options in AR System clients. Logging options are disabled for
users who are not members of this group. For more information about client logging, see Enabling logs.
Maximum
Log-File
Size (byte)
Defines the maximum size (in bytes) for the log file. A value of 0 (the default) specifies no limit. Except for
0, the log file size cannot be set to less than 4096. When the log file reaches the maximum, new
information wraps to the top of the file, overwriting the old information. If you do not specify a maximum
size limit, you run the risk of running out of disk space on your system. This setting does not apply to the
arforkd.log file.
Maximum
Backups
Defines the maximum number of backup (.bak) log files to be allowed when the log file reaches the
Buffer
Logged
Lines
Buffers logged lines instead of having them immediately written to disk. Selecting this option decreases the
impact to AR System performance when logging is enabled. See Buffering log output.
Log Per
Creates per-thread log files. Selecting this option decreases the impact to AR System performance when
logging is enabled. See Thread log.
Thread
Maximum Log-File Size value and a new log file is created. By default, the number of backup log files
allowed is 1, and the maximum number of backup log files allowed is 999.
8. Click Apply.
Setting server logging options

Use the Server Events tab to select the server activities to log.
When you select specific server events, those events are logged in to the Server Events form,
thereby making server-related changes available to workflow and API programs. For information
about the Server Events form, viewing recorded server events, and using server events in workflow
, see Capturing server events for workflow or API calls .
To set options for server events

Server Information.
2. Click the Server Events tab.
AR System Administration: Server Information form -- Server Events tab
Page 481 of 4705
Home

Server Events tab fields
Area
Name
Server
Event
Type
Field
Name
Description
Server
Events
Specifies the name of the form populated with information about specific server events. BMC
Remedy AR System automatically generates this form, and the form is defined from a unique
Form
combination of BMC Remedy AR System reserved fields. Only one Server Events form per server
is allowed. The default name is Server Events; you can rename the form, as needed.
Server
Cache
Changes
Determines the objects for which changes are recorded in the Server Events form. Select the check
box next to any of the following events to log changes to these objects:
Active Link
Container
Escalation
Field
Filter
Import
Menu
Form
View
User/
Group
Determines whether to log additions, modifications, or deletions to Users or Groups in the User or
Changes
Changes are recorded in the Server Events form.
Server
Setting
Changes
Determines whether an entry is created in the Server Events form as a result of an
Archive
Determines whether an entry is created in the Server Events form as a result of archiving data to an
Group form, or any user or group changes using the access control utilities arcache and arreload .
ARSetServerInfo call.
archive form.
Server
Group
Actions
Determines whether an entry is created in the Server Events form as a result of server group
activities.
4. Click Apply.
Setting ports and RPC numbers

Use the Ports and Queues tab to set server ports and RPC numbers as needed to communicate
with other servers, clients, and services on the network. The Server Queue region on this tab
enables you to configure server queues and threads as appropriate for your server, taking
advantage of the multithreaded design of BMC Remedy AR System.
Page 482 of 4705
Home
In this topic:
Assigning TCP port numbers to AR System servers
To set server ports and queues
Assigning TCP port numbers to AR System servers

You assign one TCP port number for the AR System server. All initial contact with the server is
through a single port. If you run multiple servers on the same computer, each server must use a
unique port.
Clients must be configured with the server port number to enable server access without the use of
a portmapper. If you do not allow the server to register with a portmapper, you must assign a TCP
port number for the AR System server. For more information about configuring clients, see
Configuring clients for AR System servers .
Do not assign port numbers that conflict with port numbers used by other applications or programs
running on your system. If you assign conflicting port numbers, your servers might not start as
expected. To find out which port numbers are in use, enter one of the following commands at the
command-line prompt:
UNIX rpcinfo -p
Windows netstat -a
Client tools can use ports 0-65535.
Ports 1-1024 are reserved ports; avoid using these ports. On UNIX, port numbers within the range
1-1024 are available only for the superuser, and many of these numbers are reserved.
To set server ports and queues

Server Information.
2. Click the Ports and Queues tab.
AR System Administration: Server Information form--Ports and Queues tab
Page 483 of 4705
Home
3. Edit the options as needed:

Ports and Queues tab fields
Field name
Description
Server TCP
/IP Port
Defines the TCP/IP port number for the AR System server. Enables clients to have access to the server
without a portmapper. When set to 0, which is the default, the portmapper assigns the port.
Ensure that you set the same port number as the value of the server_port parameter in the
pluginsvr_config.xml file that is located in the <Install Dir>/pluginsvr directory.
Note
If you set the Server TCP/IP Port field to a value less than 1024, older clients cannot connect.
Distributed
Server RPC
Program
Number
Obsolete. See Assigning an RPC program number to DSO.
Number of
Selector
Threads
Defines the number of threads that can be used to monitor all live client socket connections for IO activity.
JMX Port
Defines the JMX port number that enables administrators to connect to JVM by using Java Messaging
When the thread detects any activity, it forwards the call to the appropriate queue. The default value is 1.
Extensions (JMX). The default port number is 61500.

Message
Broker Port
The specific port to which the JMS broker binds when sending messages to registered clients. The default
Cache Peer
Listener
Port
Defines the port number where all ehcache instances from different servers communicate with each other.
Alert
Outbound
Port
The specific TCP port to which the server binds when sending alert messages to registered clients. If
multiple alert threads are started, the number represents the starting port number in a consecutive range
of numbers available for the alert threads. If no port number is specified or if 0 is entered, the portmapper
randomly assigns an available port to the server.
Plugin
Loopback
RPC
Program
Number
Defines a private queue for all loopback calls from the plug-in server, regardless of which plug-in
application initiates the call.
For more information about Plugin Loopback RPC Socket, see Private queues for loopback calls.
port number is 61617.
The default port number is 40001.
Page 484 of 4705
Home
Field name
Description
Register
with
Portmapper
Defines whether the AR System server and the plug-in server are registered with AR System Portmapper.
If the check box is
Selected They are registered. The server is registered if not previously registered. AR System
clients can get the port number of the AR System server and the plug-in server from AR System
Portmapper.
Cleared They are not registered. If the server was previously registered, this option removes the
registration. AR System clients cannot get the port number of the AR System server and the plug-in
server from the portmapper.
If you are running multiple servers on a single computer, you can select the Register with Portmapper
option for one server only.
Enables you to define server queues specific to your needs. For most types of server queues, you can
specify a minimum and maximum number of threads. For the escalation queue, only the maximum threads
number is used, and all threads are started at startup time.
If you do not specify a fast or list queue or specify only one thread, three threads are started to
meet the minimum system requirements for each queue.
If the server starts more threads than specified to meet system requirements for fast and list
queues, it does not change the number specified.
For all other types, if you do not specify a number, the system defaults to one minimum and one
Server
Queue
maximum thread per server queue.

For more information, see Defining queues and configuring threads.
4. Click Apply.
5. Restart the server for the changes to take effect.
Note
To change the port number that the AR System server uses when communicating
with the plug-in server, edit the Plugin-Port option of the ar.cfg (ar.conf) file, and
restart the server. See Plugin-Port .
Setting database options

Use the Database tab to view and configure information about the database that you are using.
To display and update information about the database

Server Information.
2. Click the Database tab.
AR System Administration: Server Information form Database tab
Page 485 of 4705
Home
The information displayed on this tab varies depending on the relational database you have
installed.
Database tab fields
Field Name
Description
Database
Displays the type of database that the AR System server is using.
Type
Database
Home
(UNIX only) Displays the directory path of the underlying database that the AR System server is using.
Database
Name
Displays the name of the database created for AR System in the underlying database server.
Database
Displays the version of the database that the AR System server is using.
Version
Database
Displays the user name that BMC Remedy AR System uses to access the database.
User Name
Database
Password
(Sybase, Oracle, Microsoft SQL Server, and DB2 databases only ) Enables you to define the password
that BMC Remedy AR System uses to access the database. The existing password is not displayed. To
change the password, enter a value in the Database Password field. The default database password
created by BMC Remedy AR System is AR#Admin#. If you changed the password and do not
remember it or if you changed it outside AR System and must reflect the change in AR System, log on
to the database as the database administrator and change it back to the default. If the encrypted
password is in the ar.confconfiguration file, delete it from that file.
Database
Configuration
File
Displays the contents of the ardb configuration file used by the advanced BMC Remedy AR System
feature that appends clauses to the SQL statements that create tables and indexes. For more
Database
Case
Sensitive
Indicates whether the database in use is case sensitive. This field is read-only.
Request ID
Uses
Clustered
Index
(Microsoft SQL Server, Sybase, and DB2 databases only ) Indicates whether AR System creates the
Store CLOB
In-Row
(Oracle databases only) Specifies how Oracle CLOBs are stored:

By default, this option is not selected, and CLOBs are created "out row." Out-row CLOBs can
cause the database to grow rapidly.
If this option is selected, CLOBs are created "in row." In-row CLOBs can degrade CPU
performance.
information about the ardb file, see ardb.cfg or ardb.conf.
Request ID field as a clustered index to boost performance. By default, this option is selected.
Page 486 of 4705
Home
Field Name
Description
Note
Before installing BMC Remedy AR System applications, select this option so that all database
tables for applications are created in-row.
4. Click Apply.
Setting currency types

Use the Currency Types settings to specify which currency types become the allowable and
functional currency types by default when you add a currency field to a form in BMC Remedy
Developer Studio. These currency types (represented by three-character abbreviations such as
USD) are stored in the BMC Remedy AR System Currency Codes form. The types appearing in the
Currency Types tab are those marked as active in the Currency Codes form.
When you add or remove currency types in the BMC Remedy AR System Administration: Server
Information form, the BMC Remedy AR System configuration file ( ar.cfg or ar.conf) is updated with
your changes.
Note
Web reports support currency fields, but do not support currency value and currency type
. BMC Remedy AR System reports support currency value and currency type.
See Currency fields.
To set currency types

1. In a browser, open the BMC Remedy AR System Administration Console, and click System
> General > Server Information.
2. Click the Currency Types tab.
AR System Administration: Server Information form Currency Types tab
3.
Page 487 of 4705
Home

Currency Types tab fields
Area
name
Description
Choose
Default
Allowable currency types are types that are valid entries in a currency field. These currency types are
visible in menus or lists in BMC Remedy Developer Studio and in client screens. From the list in the left
Allowable
Types
column, select a currency type, and click Add. Your selection is added to the table on the right, which
shows the three-character currency type and the default decimal precision level for that currency type. For
example, the currency type USD has a default of two decimals of precision. You can modify this precision
level by entering a new value in the Precision column. For example, to specify four decimals of precision,
enter 4. To remove a currency type, select it and click Remove.
Choose
You must also specify the functional currencies stored as part of the field value. When a request is
Default
Functional
submitted that includes a currency value, the server converts that value to a functional currency type and
stores it. You must include at least one functional currency type. You can specify an unlimited number of
Types
functional currency types; however, adding more than five currency types might have an adverse effect on
server performance. From the list in the left column, select a functional currency type, and click Add. Your
selection is added to the table on the right, which shows the three-character currency type and the default
decimal precision level for that currency type. For example, the currency type USD has a default of two
decimals of precision. You can modify this precision level by entering a new value in the Precision column.
For example, to specify four decimals of precision, enter 4. To remove a currency type, select it and click
Remove.
4. Click Apply.
Setting license options

Use the Licenses tab to display information about the type and number of BMC Remedy AR
System licenses on a server. You can also set the Submitter Mode in this tab.
To display server license information and set the submitter mode

2. Click the Licenses tab.
AR System Administration: Server Information form--Licenses tab

Licenses tab fields
Page 488 of 4705
3.
Home
Field
Name
Description
Server
License
Type
Displays the license type of the server.
Fixed
Write
Licenses
Displays the total number of Fixed licenses on the server.
Floating
Write
Licenses
Displays the total number of Floating licenses on the server.
Max
Forms
Displays the number of forms your license allows you to create on the server. If this field reads Unlimited,
you can create as many forms as you want.
Allowed
on Server
AR
System
Server ID
Displays the BMC Remedy AR System identifier code attached to the server license.
Submitter
Mode
Defines the conditions under which submitters can modify the requests they initially submit (that is, where
their names are in the Submitter field). Select one of the following options:
Locked Users can modify requests they submit without a write license. This does not apply to
users with a Restricted Read license who cannot modify requests under any circumstances. In the
locked submitter mode, after the entry is submitted, the value in the Submitter field cannot be
changed.
Changeable (Default) Users must have a write license to modify requests.
Note
Changes to the Submitter Mode settings do not take effect until the server is stopped and
restarted.
4. Click Apply.
Setting external authentication options

Use the EA (External Authentication) tab to specify the parameters necessary for BMC Remedy AR
System to authenticate users with external systems.
To set BMC Remedy AR System Administration: external authentication

parameters
2.
Page 489 of 4705
Home

AR System Administration: Server Information form EA tab

EA tab fields
Area name
Field Name
Description
External
Enables an external authentication (AREA) server. The RPC program number for
the plug-in service is 390695. Entering no value or 0 disables authentication using
an AREA service, and the BMC Remedy AR System server accesses the operating
system for authentication purposes.
Authentication
Server RPC
Program
Number
Note
You must have an AREA server built and prepared before you set the RPC
Socket number here.
For more information about how to set up an external authentication server, see
Configuring the AR System server for external authentication (AREA) . For
information about configuring an AREA LDAP plug-in, see Using the AREA LDAP
plug-in.
External
Authentication
Server
Timeout (
seconds)
RPC
Sets the time limit (in seconds) within which the plug-in server must respond to the
BMC Remedy AR System server when making external authentication (AREA) calls
before an error is returned. If this is set to 0, BMC Remedy AR System server uses
the default of 40 seconds.
Need To Sync
Sets the interval for periodically invoking the AREA server's

AREANeedToSyncCallback() call. If this option is set to 0, BMC Remedy AR
System server does not invoke the call to the external authentication server. The
default is 300 seconds. For more information about the external authentication
server, see Configuring a server to use plug-ins, and AR System external
authentication.
Authenticate
Unregistered
Users
Defines how BMC Remedy AR System validates a user who has no record in the
User form. When a user logs in to BMC Remedy AR System, the server tries to
validate the user against registered users (users who are listed in the User form). If a
match is found, that user definition and the permissions specified in the matching
User record are used. If no match is found, BMC Remedy AR System continues
trying to validate the user or stops the validation process depending on whether this
option is selected. If the check box is
Selected, and External Authentication is not configured (Default on
UNIX servers) On a UNIX server, BMC Remedy AR System searches the /etc
/passwd file or NIS password map for a match. If a match is found, the user
is considered a valid user (not a guest) of the system. The UNIX group
Page 490 of 4705
Home
Area name
Field Name
Description
specification from the file or NIS is retrieved, and the user is considered a
member of the BMC Remedy AR System group whose Group ID matches the
UNIX group. On a Windows server, BMC Remedy AR System authenticates
to the default domain. The optional authentication string that the user enters
when logging in is used as the Windows domain name for authentication
purposes. On Windows servers, the user is considered a member of the
group whose Group ID is 0.
Selected, and External Authentication is configured BMC Remedy AR
System sends a request to the external authentication server to authenticate
the user. If a match is found, the user is considered a valid user (not a guest
user) of the system. SeeConfiguring a server to use plug-ins. The
authentication string entered by the user when logging in is passed to the
external authenticator for its use.
Cleared (Default on Windows servers) BMC Remedy AR System stops the
validation process and manages the user as a guest user if Allow Guest
Users is enabled.
For information about configuring external authentication, see To set server ports
and queues.
Cross Ref
Blank
Password
Defines how BMC Remedy AR System authenticates a user whose User form record
has no password. When a user logs in, BMC Remedy AR System searches its own
database for that user. If the user has a password, the system uses it. If the
Password field is empty and this option is
Selected BMC Remedy AR System tries to validate the password against
one of the following items:
An external authenticator if one is configured
The password in the Windows server domain
The UNIX server's /etc/passwd file
Cleared (Default) BMC Remedy AR System concludes that an empty
password field means that the user has no password.
In the Login window, users see an Authentication field. If your AR System server is
running on Windows, the contents of this field are used as a domain name when the
server authenticates the user with the operating system. If the server is instead
configured to use an external authenticator, the contents of this field are passed to
the authenticator. See Setting up an authentication alias. If you enable the
Cross-Reference Blank Password option, make sure that it does not conflict with
the User Password Management feature. If you enforce a password policy, BMC
Remedy AR System periodically forces users to set a password that cannot be blank
. If a user's password is authenticated outside of BMC Remedy AR System and that
user sets a non-blank password, BMC Remedy AR System performs the
authentication. This is not an issue if enforcement of a password policy is not
enforced. If a policy is enforced, you must disable the policy for users whose
passwords should be blank. For information about enforcing password policies, see
Enforcing a password policy introduction. To disable the policy for users whose
passwords should be blank, see Disabling password management for individual
users.
Authentication
Chaining
Mode
Specifies the order in which BMC Remedy AR System tries to authenticate users
when they log on:
Default Disables authentication chaining.
ARS - AREA 1) the User form; 2) the AREA plug-in.
AREA - ARS 1) the AREA plug-in; 2) the User form.
ARS - OS - AREA 1) the User form; 2) Windows or UNIX authentication; 3) the
AREA plug-in.
ARS - AREA - OS 1) the User form; 2) the AREA plug-in; 3) Windows or UNIX
authentication.
Page 491 of 4705
Home
Area name
Field Name
Description
Group
Mapping
LDAP Area
name
The name of the LDAP group to map to the BMC Remedy AR System group in the
same row of the Group Mapping table.
AR Group
Name
The name of the BMC Remedy AR System group to map to the LDAP group in the
same row of the Group Mapping table.
Ignore Excess
Groups
Enables BMC Remedy AR System to authenticate a user when any single LDAP
group to which the user belongs matches a BMC Remedy AR System group.
Setting performance and security options

Use the Advanced tab to create settings for performance and security:
2. Click the Advanced tab.
AR System Administration: Server Information form Advanced tab
3. Edit the options listed in the following table, as needed, and click Apply.
Advanced tab fields
Area name
Field name
Description
Default Web
Path
Specifies the base URL for the mid tier and is used by clients such as Flashboards. The
URL looks like this:
http://<hostName>/<contextPath>
hostName is the name of the server (for example, eng.remedy.com).

contextPath is the URL context path of the AR System application registered with
the servlet engine. This is set up during installation. The default value is arsys. If
your company has multiple domains, use a fully qualified path name.
Maximum
Depth for
Hierarchical
Query
For forms that contain hierarchical data, such as manager and employee relationships,
specifies the maximum number of levels in the hierarchy that a recursive query
retrieves. By default, the maximum is 25. Enter any integer greater than 0. See
ARGetListEntryWithMultiSchemaFields.
Page 492 of 4705
Home
Area name
Field name
Description
Maximum
Vendor
Temp
Tables
Specifies the maximum number of temporary tables that can exist on an AR System
server for a single vendor form. The ARGetListEntryWithMultiSchemaFields
function stores data from vendor data sources in these tables. By default, only one
temporary table can exist for each vendor form. This setting applies to all vendor forms
on the server. It is overridden by the value of an individual vendor form's Maximum
Vendor Temp Tables property. Enter any integer greater than 0. See
Email
Suppress
Suppresses the server domain in the URL. The option is clear by default.
Server
Domain in
URL
Maximum
Line Length
in Email
Email
Notification
Web Path
Specifies the maximum line length that can be in an email. The default is 1024. If a
single line of the message is over this length, a return is automatically inserted. Limits
the line length of email messages passed through the mail server to protect users from
excessively long lines.
Specifies the base URL that appears in email notifications. If this field is left blank, the
Default Web Path is used. (The Email Notifications Web Path field is available because
the Default Web Path is specified for other applications like Flashboards, and it might
be different from the mid tier web path for opening requests in a notification.) If your
company has multiple domains, use a fully qualified path name.
Security
Transaction
Control
Localized
Error
Messages
Active Link
Run
Process
Directory
Specifies the only directory that the Run Process active link action can run from, for
Active Link
Run
Process
Shell (UNIX
servers only
)
Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no
path is specified, administrators can specify any shell.
Allow
arcache and
arreload
Enables the administrator to use the arcache and arreload utilities. See arcache.exe or
arcache and arreload.exe or arreload. The option is selected by default.
Maximum
Connections
Specifies the maximum number of client managed transactions (CMT) which are
allowed on the system. Valid values are 0 to 100. When set to 0, CMT is disabled on
that system. The default is 10.
Transaction
Timeout (
seconds)
Specifies the maximum allowed time interval (in seconds) between client managed
transaction API calls. When a client managed transaction starts, if the consecutive API
call is not made within the specified time interval by the client, then the server rolls back
the transaction and the transaction handle becomes invalid. Valid values are 0 to 600.
The default is 60.
Localize
Server
Enables the administrator to enable or disable localization of the server.
example, C:\arsys. If no directory is specified, active link processes can run from any
directory.
Selected The server is localized and is enabled for such tasks as searching
entries in localized forms, or using BMC Remedy AR System Message Catalog
to load the message. Clients are enabled to display localized messages, but
clients still have local catalogs, such as the user.dll. You must select the
Localize Server check box to see localized error messages.
Page 493 of 4705
Home
Area name
Field name
Description
Cleared (default) The server is not localized. Such tasks as searching
localized forms and the localization of messages are disabled. The server does
not use the BMC Remedy AR System Message Catalog form, and messages are
shown from the error catalog. The default message is displayed.
Note
If users in a different locale open a form with localized views before you select
this option, you must flush the mid tier cache after setting this option to make
the localized view available on the web. See Configuring the Cache Settings
page.
Filters
Catalog
Form Name
Displays the name of the form the server uses to resolve error messages when
Maximum
Filters for
Specifies the number of filters that can be performed in an operation. The default and
recommended number is 10000. Increase this number at your own risk only if you reach
a limit in your system and you have verified that your workflow is valid.
an
Operation
Maximum
Stack of
Filters
Server Group
Localize Server is selected. For more information about the BMC Remedy AR System
Message Catalog form, see Localizing BMC Remedy AR System applications.
Specifies the maximum number of nested filters and filter guides that execute to prevent
recursive actions on the server. The default and recommended number is 25. Increase
this number at your own risk only if you reach a limit in your system and you have
verified that your workflow is valid.
Server
If the server belongs to a server group, specifies the name of the group. All servers in
Group
Names
the server group share this setting.
Check
Interval
Specifies how often the server communicates with other servers in the group. Each
server can register its own status, determine whether any server is delinquent, establish
the parameters needed for sending signals, and determine operational responsibilities.
Values are
Default 30 seconds
Minimum 10 seconds
Maximum None
All servers in the server group share this setting, and when it is changed, all the
AR System servers in the group must be restarted.
Preference
Server
Preference
Server
Option
Specifies where user preferences are read from. The options are
User Defined Users can select whether to use a preference server, and this
server might or might not be used depending on whether the Centralized
Preference forms are defined.
Use This Server Users must use a preference server, and this server is an
available preference server.
Use Other Server Users must use a preference server, and this server is not
available as a preference server.
See Establishing a mandatory preference server.
Preload
Tables
Configuration
Preload
Tables At
Init Only
If the number of preload threads is not zero, specifies whether the threads are used
only at server startup or for all cache reloads from the database. See Setting the
Preload Tables Configuration option. Values are
Yes If preload threads are configured, use them only at server startup.
Page 494 of 4705
Home
Area name
Field name
Description
No If preload threads are configured, always use them when loading the
cache from the database.
For information about the corresponding configuration file setting, see
Preload-At-Init-Only.
Number of
Preload
Threads
Specifies the number of preload threads used when information is loaded from the
database into the server cache. The maximum value is 30 or twice the number of
preload segments, whichever is lower. The server might reduce the number of threads
at runtime if it determines that threads would be started with no work to do. If this field is
set to 0, the Preload Tables Configuration option is off. For information about the
corresponding configuration file setting, see Num-Preload-Threads.
Number of
Preload
Segments
Specifies the total number of preload segments handled by the preload threads. Vary
this setting to balance the load between preload threads and to optimize cache load
time. A good initial setting for this option is 1/3 the number of schemas (forms) in the
AR System server. See Determining the optimum preload settings. For information
about the corresponding configuration file setting, see Num-Preload-Schema-Segments
.
Setting server passwords, RPC options, and plug-in timeouts

The Connection Settings tab enables you to perform these tasks:
Change application server passwords, which are required passwords used by BMC Remedy
applications when they connect to the AR System server. Components that use application
server passwords include BMC Remedy Mid Tier, plug-in servers, the DSO server, the
Flashboards server, the Email Engine, and custom applications. Most application server
passwords are initially set when you install BMC Remedy AR System, but you can change
them at any time by using the Connection Settings tab.
If you change an application server password on a BMC Remedy AR System server, you
must also make the change for the application that connects to that server. For more
information, see the Configuring the Connection Settings page in the table below.
Set the RPC program number and port information for plug-in and DSO servers.
Configure timeout settings for the plug-in servers.
To set connection settings

2. Click the Connection Settings tab.
AR System Administration: Server Information form Connection Settings tab
Page 495 of 4705
Home
3. Edit the options on the tab as needed:

Connection Settings tab fields
Tab
name
Field name
Description
Application
Service
Specifies the password that the Email Engine and Flashboards server use to access the
Password
AR System server. Asterisks in the field indicate that a password is defined. If you change
this password on the AR System server, you must also change it for the Email Engine and
Flashboards server if they are installed. To change the Application Service Password for
the Email Engine, update theEmailDaemon.properties file (see EmailDaemon.properties
file). To change the Application Service Password for the Flashboards server, update the
server.conffile (see Resetting the Application Service password).
Mid-Tier
Administrator
Password
Specifies the password used by the mid tier to access the AR System server. If you change
this password on the AR System server, you must also change it in the Mid Tier
Proxy server
Obsolete as of release 7.5.00.
Configuration Tool, which updates the config.properties file (seeConfiguring the Change
Password page). In the Mid Tier Configuration Tool, this password is called the Admin
Password.
settings for
Java VM
Plug-In
Server
Local
Password
Sets a password for other BMC Remedy AR System servers to use when they connect to
this server's plug-in server. If this option is specified, the plug-in server accepts connections
only from AR System servers configured to use the same password. If you change this
password, you must also change the appropriate plug-in server target password on any AR
System servers that connect to this plug-in server. See Setting server passwords, RPC
options, and plug-in timeouts. If this option is not specified, the plug-in server accepts
connections from AR System servers not configured to use a plug-in server target
password.
Plugin
Default
Timeout
Specifies the number of seconds in which the plug-in server must respond to the AR
System server before an error is returned.
Plugin
Default Port
Specifies the default port for the plug-in server.
Server Name
Specifies the name of the AR System server associated with the target plug-in server.
Note
Page 496 of 4705
Home
Tab
name
Field name
Description
In this tab's table, you enter target connection settings. The AR System server
uses these settings to connect to other plug-in servers.
Port Number
Specifies the name and port number for the target plug-in server.
Password
Specifies the password for the target plug-in server. The server name and port number
create a unique entry. If you modify a server name or port number, the password is cleared
. If you remove the password for a particular entry, you can specify a server name and port
number with no password for that entry. The next time you display the table, the entry is not
displayed. The edit masked option is not supported in tables on forms. Therefore, when
you type a new password in the Password column, it is visible. Saved passwords are
masked.
DSO
DSO Local
Server
Password
DSO Local
RPC Program
Number
Target
connection
settings
Specifies the password that a DSO server uses to access this AR System server. If you
change DSO Server password, you must also change the target password for any DSO
servers that connect to this AR System server. See Configuring BMC Remedy Distributed
Server Option .
Specifies a dedicated (private) RPC program number that a DSO server uses for all
communication with the AR System server. If you leave this field blank, the fast and list
queues process all distributed operations.
Specifies RPC program numbers, TCP/IP ports, and DSO passwords that a DSO server
uses when accessing remote AR System servers. See Configuring BMC Remedy
Distributed Server Option .
tables
Remote
Local
Workflow
Password
Specifies the password that another AR System server uses to access this server through
workflow. If you change this password, you must also change the appropriate remote
workflow target password on any server containing workflow that connects to this server.
Server Name
Specifies the name of the remote server.
Note
In this tab's table, you enter target connection settings. The AR System server
uses these settings to connect to other AR System servers when required by
workflow.
Password
Specifies a password to use when this server accesses the specified remote server
through workflow. This occurs when an active link contains an SQL or Process command
against the remote server and is activated by a non administrator user. If the remote server
specifies a workflow password, you must register that server and password, or you cannot
access that server through workflow. The edit masked option is not supported in tables on
forms. Therefore, when you type a new password in the Password column, it is visible.
Saved passwords are masked.
4. Click Apply.
5. Restart the AR System server for the Connection Settings to take effect.
Note
Page 497 of 4705
5.
Home
If your environment contains AR System servers earlier than release 5.1, set the
minimum API version to 9 to ensure that secure servers cannot communicate with
servers running previous BMC Remedy AR System versions. For information about
setting the API version, see Setting administrative options.
Setting administrative options

Use the Configuration tab to set administrative options.
To set configuration options

AR System Administration: Server Information form Configuration tab

Configuration tab fields
Field Name
Description
Users Prompted
For Login
Specifies whether users are prompted for their log on credentials.

By Preference --- The prompt appears by preference.
Once Only The prompt appears only once per session.
Always The prompt appears every logon session.
Max Entries
Returned by
GetList
Limits how many database entries are returned from a search. For example, setting the maximum
entries to 50 would return a maximum of 50 entries, even if more entries satisfied the search
qualification. BMC Remedy AR System warns users that the search matched more entries than
the administrator allows to be retrieved. If users specify a maximum in their preferences, the
lesser value is used. A value of 0 (default) specifies no limit.
Server Table Field

Chunk Size
For server-side table fields, determines the number of entries (or size of the chunk) that the server
retrieves at one time from the database and stores in-memory to process during filter or filter guide
actions. The server then retrieves, stores, and processes the next chunk until all the rows are
processed. Entering a value of 0 causes the server to retrieve an unlimited number of rows. The
default is 1000 rows. Entering a low value in this field causes the server to process smaller chunks
Page 498 of 4705
Home
, which keeps the server memory usage down, but results in slower processing because the
server needs to access the database many times, especially for large tables. Entering a high value
causes the server to retrieve and process large chunks of data and access the database fewer
times. This results in higher performance at the cost of memory use.
Server Language
Displays the language and character set of the computer on which the server is running.
User Email
Notifies From
Identifies the sender of email notifications. The default sender for email notifications is ARSystem.
To specify another user name, enter that name in this field. The name must match the name you
use in the BMC Remedy AR System Email Configuration Form for notifications. For more
information about configuring a mailbox for notifications, see Sending notifications.
Minimum API
Specifies the oldest version of the C and Java APIs with which the server communicates. The
corresponding API and BMC Remedy AR System versions are as follows:
API 20 and AR System 8.1.00
Version

If you set the minimum API version to 14, clients earlier than version 7.5.00 cannot communicate
with the BMC Remedy AR System 7.5.00 or later server. If you set the API version to 0 or none,
all clients can communicate with the server. For information about setting passwords to increase
security, see Configuring server groups.
Default Home
Form
Specifies the path to a home page form to be used system-wide as the default home page for this
server when a user logs in. This default Home form is only used if one of the following statements
is true:
This server is designated as the server for the home page in the BMC Remedy AR System
User Preference form.
This server is designated as the home page server on the General Settings page in BMC
Remedy Mid Tier Configuration Tool. See Homepage Server.
No home page is specified in the BMC Remedy AR System User Preference form.
Note
If the home page form is deleted, this field is cleared and you must re-enter a default
home page.
Max Number of
Password
Attempts
Specifies the maximum number of consecutive bad password attempts a user is allowed. If you
enter 3, the user has 3 chances to log on. If all 3 attempts have bad passwords, the user account
is marked INVALID. Values for this field are 0 (turns features off) and all positive integers. This
option can also be set with the Max-Password-Attempts option in the ar.conf (ar.cfg ) file.
This parameter can be used in conjunction with Display-General-Auth-Message. See ar.cfg or
ar.conf options C-D. See also the description for error 624.
Next Request ID
Block Size
Specifies whether to allocate Next-IDs in blocks rather than one at a time. Allocating in blocks
increases performance during a create operation. To allocate in blocks, enter a positive number
greater than 1 (up to 1000). The default value is 1 (Next-IDs are not allocated in blocks). If 0 or a
negative number is used, the server uses the default value of 1. You do not need to restart the
server for the change to take effect. The option is started immediately. Warning: The use of this
configuration setting might result in unpredictably large Next-ID sequence gaps. The likelihood of
this occurring increases with the use of multiple servers that share a database. The BMC Remedy
AR System server does not malfunction because of this gap and should not be considered a
defect.
Page 499 of 4705
Home
Allow Guest Users
Specifies whether BMC Remedy AR System permits access to guest users, who are not
registered users of the system, to log on. If the check box is selected (default), guest users can
log on and perform the following tasks:
View all forms and fields for which the Public group has Visible permission.
Execute all active links for which the Public group has permission.
View all fields for which the guest user is the submitter or assignee, if the Submitter Group
or Assignee Group has View permission for the field.
Submit new requests if the fields on a form have the Allow Any User to Submit check box
selected. See Special submit setting.
Modify all fields for which the guest user is the submitter, if the Submitter Group has
Change permission for the field and if the Submitter Mode is Locked, as described in
Setting license options.
Give Guest Users

Restricted Read
Defines whether guest users receive a restricted read license when they log on to BMC Remedy
AR System. If this option is not selected, guest users receive a read license.
Allow Unqualified
Searches
Defines whether the server accepts unqualified searches (searches for which no search criteria
are specified). If the check box is
Selected (default) All database searches are allowed.
Cleared You force users to enter a search criteria when performing queries.
Note
Consider restricting unqualified searches to prevent the performance penalty of retrieving
and returning large blocks of data because of accidental unqualified searches to the
database.
Administrator-Only
Mode
Enables only administrators and sub-administrators to access BMC Remedy AR System. Users
who are not administrators or sub-administrators cannot perform any BMC Remedy AR System
operations. This is useful during system maintenance. By default, this option is not selected. Only
administrators (not sub-administrators) can set the Administrator-Only Mode. After an
administrator sets this option, sub-administrators can access only forms for which they have
permission.
Disable Archive
Disables the archive operations on the server. You can disable one server operating with one
database, but in the case of multiple servers attached to the same database, you can disable all
servers except one to prevent conflicts. By default, this option is not selected. See Archiving data.
If the Server Group Member option is selected, this setting is ignored. Server groups can be
configured in the BMC Remedy AR System Server Group Operation Ranking form to make sure
that only one server performs the operation. See Configuring server groups.
Development
Cache Mode
Turns on a cache mode optimized for application development. If the check box is not selected (
the default), the server is in production cache mode.
Notes
In this mode the Sync Cache feature cannot be used. For more information about using
this option see Using the sync cache option.
Development cache mode is intended for a development server, not a production server.
In this mode, any operation with an extended run time can cause blocking. In particular,
administrative operations cannot begin until in-progress user operations are completed.
Subsequent user operations are blocked until the administrative operation is completed.
Due to this, the server often gives the false impression that it has stopped responding.
Page 500 of 4705
Home
See Configuring server groups.

Server Group
Member
Indicates whether the server is a member of a server group. By default, this option is not selected.
Disable Admin
Operations
Disables certain operations performed only by administrators and sub-administrators, which

enable you to control changes to the database by disabling administrator (Developer Studio)
operations. You can disable one server operating with one database, but in the case of multiple
servers sharing same database, use this setting to disable all servers except one to prevent
conflicts. If the check box is
Selected Administrators cannot perform operations that affect the server's data
dictionary.
Cleared (default) Administrators can perform their usual operations including all data
dictionary restructuring operations.
If the Server Group Member check box is selected, this setting is ignored. Server groups can be
that only one server performs these operations. See Configuring server groups.
Disable
Escalations
Enables you to stop escalations running on the server. You can disable one server operating with
one database, but in the case of multiple servers attached to the same database, use this setting
to disable all servers except one to prevent conflicts. By default, this option is not selected. If the
Server Group Member check box is selected, this setting is ignored. Server groups can be
that only one server performs escalations. See Configuring server groups.
Disable Alerts
Enables you to prevent alert messages from being sent to users when an alert event is entered in
to the system. No threads are run in the Alert Queue. This setting is acknowledged only at startup,
so any changes do not take effect until the server is restarted. By default, this option is not
selected.
Verify Alert Users
Indicates whether the server needs to check its list of registered alert clients to determine if they
are listening and ready to receive alert messages. This setting is acknowledged only at server
startup, so any changes do not take effect until the server is restarted. Selecting this option can
result in a large amount of network activity at server startup. If the check box is
Selected The server verifies the list of clients. If the clients are not listening, they are
removed from the list of registered clients.
Cleared (default) The server does not perform the verification.
Regardless of the setting, if a subsequent alert message is sent to a client that is not listening, the
client is removed from the list of registered clients.
Enable Multiple
Enables multiple roles, groups, and user names to be stored in the row-level security Assignee
Assign Groups
Group field (ID 112) and in dynamic group fields (ID 60000-60999). This enables multiple users,
or users from multiple groups, to access the same entry (as in the sample qualification, 'Assignee
Group' = ";50;51;-90;'Mary Manager';" ). If the check box is not selected (the default), only one
role, group, or user name can be stored.
Disallow Non
Unicode Clients
When selected, restricts server access to Unicode-safe clients. This option applies to all
non-Unicode clients. This check box is visible only for AR System 7.0.00 servers or later. If the
server uses a non-Unicode database, the check box is disabled.
Record Object
Relationships
Determines whether the AR System server records the relationships between workflow objects. If
the check box is
Selected The server creates entries in a database table to track the relationships
between many types of workflow objects.
Cleared(default) The server does not record relationships.
Note
Page 501 of 4705
Home
If using a server group, all servers within the same server group must have the
same setting for this option. If they do not, the servers in the group inconsistently
populate and un-populate the object relationship database should they be the
highest ranked server for the Administration operation when they are restarted.
Only the highest ranked server for the Administration operation in the server
group will perform the required object relationship actions when restarted.
When the server is recording relationships, it updates the relationship data whenever an
object is created, modified, or deleted. You might notice that installing an application or
importing a large number of objects takes longer because of additional database operations
.
Note
You must restart the AR System server before a change to this setting takes place
.
When you select the check box and restart the server, it records the relationships of
all server objects before it accepts connections from clients. Therefore, the first time
you restart the server after selecting this option, you cannot connect to the server
with any client for a period of time, which depends on how many objects are defined
on the server. With a large number of objects, such as with an ITSM application
installed, this could take as long as an hour or more depending on the performance
of the database. (Subsequent server startups are not affected by this setting.) When
you can connect, the recording of object relationship data is complete.
When you clear the check box and restart the server, it removes all the recorded
relationships from the database. This option must be selected on a development
server to enable the following features of BMC Remedy Developer Studio:
Analyzer
Search
Show Relationships
For more information about Analyzer, see Using Analyzer to find problems in your applications.
For more information about Search and Show Relationships, see Relationships tab. Also, BMC
Remedy Developer Studio uses that object relationship data, if available, to improve performance
of some features, including object lists, related working lists, and exporting related objects. To
view these relationships directly, use the BMC Remedy AR System Object Relationships form.
Max Attach Size
Specifies the maximum size of the attachment in bytes. The default is 0, which allows users to
attach files of any size.
Use Prompt Bar

For
Specifies whether system messages appear in the prompt bar or a pop-up box. The options are:
Notes and Warnings (default) Notes and warnings appear in the prompt bar, but Errors
appear in a pop-up box.
All System Messages All system messages appear in the prompt bar.
None, Show in Popup No messages appear in a prompt bar. Instead, all messages
Recache Delay
The number of seconds that the recache is delayed.
Required Field
Identifier
Specifies the character to add to the label of a field whose entry mode is Required.
Prefix on Label Add the character to the beginning of the label.
Suffix on Label (default) --- Add the character to the end of the label.
Identifier The character to add to the label. The default is an asterisk.
For information about field entry modes, see Field Properties.
Display Property
Caching
Page 502 of 4705
Home
This option can be set to restrict the number of form display properties the server loads into
memory at startup. The result of a restricted option ( Cache Only Server Display Properties) is
less memory use at start-up, and more memory available for the server process to grow. Form
display properties are used for the background image of form views and the display properties of
each form field. If an unloaded display property is needed, the server loads it on demand instead
of caching it up front. Use the radio button to select one of these options: Restart the server after
changing this setting.
Cache Only Server Display Properties Only display properties associated with server
workflow are cached. This setting does not decrease start-up time because the server still
must read all properties for load selection. Reduced memory use impacts performance
when data must be read from the database. It might also adversely affect server
performance, database performance, or both when used with mid tier caching.
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.
Cache All Display Properties (default) All display properties are loaded into the cache.
This increases the memory requirement for the cache but can improve the performance of
the server when a form is first opened by the client.
Note
To configure settings for individual forms, use the check boxes on the Basic page
of the Form Properties dialog box. See Setting form properties.
License Tracking
Determines whether information is recorded in the AR System Current License Usage and AR
System Historical License Usage forms. By default, this option is not selected (information is not
recorded in the forms). For information about tracking license usage, see Displaying and Tracking
server group license usage.
Disable ARSignals
Causes the system to disable ARSignals. By default, this check box is not selected.
Disable Audit Only
Causes the system to record all fields when auditing a record. By default, this check box is not
selected, indicating that only those fields whose values have changed during a transaction are
audited.
Changed Fields
Monitoring service operations

You can track the number of service operations performed by the AR System server. You can track
:
The number of emails sent from AR System server in an hour
The number of emails received by AR System server in an hour
Note
Using the 2014.01 version, you can monitor only email services.
Page 503 of 4705
Home

Enabling service operations
Adding service operations that you want to track
Viewing the service operations details
Related topic
Enabling service operations

As a BMC Remedy administrator, you can track the incoming and outgoing emails by selecting a
check box in the AR System Server Information Advanced tab. If you have not selected this
option, you will not be able to track the service operations.
To enable tracking of service operations

Server Information.
2. In the AR System Administration: Server Information form, click the Advanced tab.
3. In the Enable Service Recording drop-down list, indicate whether you want to enable the
system for tracking service operations. By default, tracking is disabled.
Adding service operations that you want to track

You can configure the service operations that you want to track using the AR System Service
Statistics Configuration form. This form allows you to enable service operations for particular
service types. Using the 2014.01 version, you can monitor only email services.
Recommendation
You must follow the steps displayed in this section to configure the tracking of service
operations. If you have not set the following parameters for a service operation, it will not
be tracked.
To add service operations

1. Open the AR System Service Statistics Configuration form by typing the URL in a
browser in this format: http://<midtier>:<port>/arsys/forms/<server>/AR+System+
Service+Statistics+Configuration.
The AR System Service Statistics Configuration form opens.
Page 504 of 4705
Home
2. Enter the values for the following fields:

Service Type - Indicates the service type, for example, com.bmc.arsys.email.
Select the service type from the available service types.
Service Operation Indicates the service operation, for example, incoming,
outgoing. Select the service operation from the available service operations.
Monitoring Status Indicates the status of a service operation for tracking. Select
ON or OFF from the list to enable or disable tracking.
Viewing the service operations details

The information about the tracked emails is recorded in the AR System Service Statistics form.
To view the details, open the AR System Service Statistics form by typing the URL in a browser
in this format: http://<midtier>:<port>/arsys/forms/<server>/AR+System+Service+Statistics .
The AR System Service Statistics form displays the following fields:
AR System Service Statistics form fields
Field name
Description
Service type
Indicates the service type

For example, com.bmc.arsys.email.
Service
operation
Indicates the type of service operation

For example, incoming, outgoing
Count
Indicates the total number of service operations. For example, incoming and outgoing emails.
Start
Timestamp
Indicates the time when the service tracking started. Start time is specified in hours. The tracking time frame is
1 hour.
End Timestamp
Indicates the end time of service tracking

For example, if the start time is 5/25/2013 2:00:00 AM , the end time will be 5/25/2013 3:00:00 AM.
Server
Indicates the IP address of the computer where the AR System server is running
Related topic
Setting performance and security options
Page 505 of 4705
Home
All servers include an Admin queue; it is the default server setting and cannot be configured. The
Admin queue can have only one thread at any time.
When you define additional queues, you must assign corresponding RPC program numbers, and
you must define the minimum and maximum number of threads for each queue that you are using.
To add server, escalation, or full text indexer queues and to configure threads
2. Click the Server Ports and Queues tab.
3. In the Server Queue box, click at the bottom of the Type column.
4. Click in the RPC Port Numbercolumn, and enter the appropriate number for the queue that
you want to add:
Type
RPC Prog Number
Default
Min
Threads
Default
Max
Threads
Alert
390601
Full Text
Indexer
390602
Escalation
390603
Fast
390620
Line
390635
Private
An RPC program number in the following ranges:

390621-390634
390636-390669
390680-390694
Note: If you do not configure a private queue, its operations are executed by
the default dedicated queue (Fast, List or Admin).
Note
To enable the debug queue, the Min Threads and Max Threads count must
be 1.
If you do not want to enable the debug queue for the list and fast threads,
the minimum number of threads must be 2.
Even if you delete the escalation queue, the AR System server starts the
thread in the background.
5.
Page 506 of 4705
Home
5. In the Min Threads field, enter the minimum number of threads that you want started at
startup.
The default is 1.
6. In the Max Threads field, enter the maximum number of threads that your system is allowed
to start.
The default is 1. When all the existing worker threads are in use, the system starts additional
threads as needed until the maximum number is reached. These additional threads remain
active until the server is rebooted.
For the escalation queue, the maximum number of threads are started when the server
starts up.
7. Select the Yes check box to create a debug queue to work with the workflow debugger.
See Configuring the server for debugging workflow .

When you return to the form, the new queues are listed.
Note
If you have removed a queue or decreased the maximum number of threads for a
queue, restart the server for the changes to take effect.
Changing a server name when using a duplicated or migrated

environment
BMC Remedy AR System Server changing server name checklist
Update the Customization Comments column and check the tasks as you complete them.
Download checklist
This section describes the configuration procedures required to change the server name of a BMC
Remedy Action Request System (BMC Remedy AR System) server. The steps involve updating
one or more of the following items:
(Windows only) Registry information using regedit

Configuration files using a text editor
Form data using a BMC Remedy AR System client, such as a browser
Server-Name is the alias name by which an AR System server recognizes itself. You might need to
change a Server-Name alias because:
Page 507 of 4705
Home
Use
case
Description
Use
case
1
You are setting up a staging server (as part of the upgrade process) by installing all of the products first and then restoring
the database from the production server. The database might contain references to the production server, which might not
be applicable to the staging environment. In this case, you need to change only the form data.
Use
You are setting up a staging server (as part of the upgrade process) by restoring the database first and then installing the
case
2
new BMC Remedy AR System environment (this is called an accelerated installation). In this case, you need to change
only the form data.
Use
case
3
The Server name is changing due to a policy or host name change. In this case, you must change the Registry (on
Windows), the configuration files, and the form data.
Use
case
You are moving the server into a server group and using a new Server-Name alias. In this case, you must change the
Registry (on Windows), the configuration files, and the form data.
Note
The steps describe both Microsoft Windows and UNIX environments. In some cases (
such as working with the Registry), the steps apply only to Windows.
The following section provides information about procedures you need to perform to change the
sever name of BMC Remedy Action Request components and applications.
Related topics
Duplicating the production server database for upgrades with overlays
Duplicating the production server database for upgrades without overlays
Configuring the AR System server to rename the server

To configure the AR System server, you must update configuration files. On Windows, you must
also update the Registry. On UNIX, you must also update the arsystem script.
Updating the configuration files
ar.cfg (ar.conf)
armonitor.cfg
pluginsvr_config.xml
server.conf
Making service registration changes on Windows
Updating UNIX environments
Page 508 of 4705
Home
Updating the configuration files

ar.cfg (ar.conf)
In the ar.cfg (ar.conf) file, update the following properties. (You might not need to update all
directory and file path properties, but update any properties that point to AR System servers and
the mid tier.)
Property name
Comment
Db-name
Update with newDatabaseName
Db-user
Update with newDatabaseUserName
Default-Web-Path
Update with http://<newMidTierServerName>:<portNumber>/arsys
Server-Name
Update with newServerName
Server-Connect-Name
Update with newServerName
Server-Plugin-Alias
Update every occurrence of this parameter with newServerName
armonitor.cfg
In the armonitor.cfg file, replace the old AR System server name with the new AR System server
name in the following string: -x <newServerName>
You will see several lines that contain this string. Edit each occurrence.
In the pluginsvr_config.xml file, the server_name user-defined tag contains the server name for
the following plug-ins. Adjust the server_name value with newServerName.
Typically, when you install the BMC Remedy ITSM Suite, several Java plug-in servers are installed.
Be sure to replace the server_name value for each plug-in server. To find the location of these
plug-in servers, look at the -classpath parameter for each Java command in the armonitor.cfg
file.
server.conf
Find and replace the occurrences of < oldServerName> by <newServerName>.
Making service registration changes on Windows

The following is the process for deregistering and registering services:
1. Before changing the services, export the following Registry entries from
HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services.
BMC Remedy Action Request System Server - < oldServerName>
BMC Remedy Email Engine - <oldServerName 1>
BMC Remedy Flashboards Server - < oldServerName>
Page 509 of 4705
Home
Stop the services of BMC Remedy Action Request System, Email Engine,
and Flash boards before proceeding with the next steps.
2. Create new BMC Remedy Action Request System Server service in the Registry.
a. Open the registry backup of BMC Remedy Action Request System Server - <
oldServerName> taken at step 1.

b. Save this file as BMC Remedy Action Request System Server - < newServerName
>.
c. In the same file, find and replace the occurrences of < oldServerName> by <
newServerName>.
d. Save the file.
e. Right-click on the BMC Remedy Action Request System Server - <
newServerName> file and click Merge to update the Windows registry settings.
3. Create a new BMC Remedy Email Engine service in the Registry.
a. Open the registry backup of BMC Remedy Email Engine - < oldServerName 1> taken
at step 1.
b. Save this file as BMC Remedy Email Engine - <newServerName 1>.
c. In the same file, find and replace the occurrences of < oldServerName 1> by <
newServerName 1>.
d. Save the file.
e. Right-click on the BMC Remedy Email Engine - <newServerName 1> file and click
Merge to update the Windows registry settings.
4. Create a new BMC Remedy Flashboards Server service in the Registry.
a. Open the registry backup of BMC Remedy Flashboards Server - < oldServerName>
taken at step 1.
b. Save this file as BMC Remedy Flashboards Server - <newServerName>.
c. In the same file, find and replace the occurrences of < oldServerName> by <
newServerName>.
d. Save the file.
e. Right click on the BMC Remedy Flashboards Server - <newServerName> file and
click Merge to update the Windows registry settings.
Updating UNIX environments

1. Create a matching /etc/arsystem/serverName directory that contains the armonitor.conf
file for your server.
In UNIX and Linux environments, the AR_SERVER_ID (set in the arsystem script) is used
to find the subdirectory of /etc/arsystem/ that stores the armonitor.conf file.
2. Edit the arsystemscript to set the following parameters correctly for the new server:
INSTALL_DIR
AR_SERVER_ID
CONFDIR (This is where the ar.conf file is located.)
TWO_TASK
Page 510 of 4705
Home
Updating the server name in application forms to rename the server

The following procedure describes how to update the server name in the various application forms
listed in the following table.
1. In a browser, open the form in Search mode.
2. In the field listed in the following table, enter the old server name, and click Search.
Do not enter any information in the other fields before performing the search.
3. In the field listed in the following table for each record, replace the old server name with the
new server name, and save the record.

Product
Form
Field name
Field ID
BMC Remedy
AR System
AR System Searches Preference
Server
51004
BMC Remedy
AR System
Server Login List
20100
BMC Remedy
AR System
Report
Server
2000018
BMC Atrium
CMDB
BMC.CORE.CONFIG:BMC_FederatedDataInterface
ARServerName
530003200
Atrium Impact
AIS:GlobalPreferences
charAISCellHost
530046754
Atrium Impact
Simulator
AIS:GlobalPreferences
iAISCellPort
530046756
BMC Remedy
IT Service
AR Login Info
Server
301286600
BMC Remedy
IT Service
Management
AST:ComplianceARBased_Advanced
AR Server Name
303000501
BMC Remedy
SYS:Escalation
Record Server
230000011
BMC Remedy
IT Service
Management
SYS:Attachments (If the out-of-box data for Survey is modified by

replacing the <arserver> or <midtierserver> placeholders with the
host names, only then change these values to the correct server
host name.)
URL
1000002261
BMC Service
Request
Management
SRM:AppInstanceBridge
AppInstanceServer
301368400
BMC Service
Request
Management
SRM:AppInstanceBridge
SRServer
301368500
BMC Service
Level
Management
SLM:Config Preferences
MidTier
(enter new URL)
Simulator
Management
IT Service
Management
Page 511 of 4705
Home
Product
Form
Field name
Service
Management
Process
Model
SYS:Integration Management
MidTier Port
Service
SYS:Integration Management
MidTier Host
Field ID
Management
Process
Model
Replacing server references in database forms
Tip for reviewers

Changes made after the first draft are in blue .
This topic explains how to update server references when moving a database to a new
environment by using the BMC Remedy AR System Maintenance Tool.
Server reference updates are required multiple times during an upgrade. They are also required
when copying a production database to a development, test, or sandbox environment.
The Maintenance Tool is capable of updating the data in AR forms to replace server name, port
and related references. You must provide input XML, which lists all the forms that need to be
updated.
Note
The procedure explained in this topic is performed outside of the BMC Remedy ITSM
Preconfigured Stack Installer (SSI installer).

Limitations of using the Maintenance Tool to replace server references
Before running the Maintenance Tool utility
To rename the server name references in the database form by using the Maintenance Tool
Limitations of using the Maintenance Tool to replace server references

Limitations to using the Maintenance Tool to replace server references in database forms include
the following:
Command line execution only is supported.
Page 512 of 4705
Home
Configuration files are not updated, therefore server rename changes are not made in the
file system.
Server groups are not updated with respect to server name changes in the database.
When run in a server group configuration, the procedure in this topic updates the
server reference group for only the primary server and not the secondary or other
servers. In other words, the form name, field ID and value parameters are updated for
only the primary server. (Reviewers: is this statement correct? Does it need additional
information? Do we need to list the information that won't be updated in the secondary
server?)
Before running the Maintenance Tool utility

Before running the Maintenance Tool, you must create an options.txt file. An example
ARSystem-ini-template.txt file contains all options you can place in an options.txt file. You can
find the example file in the utility folder of the BMC Remedy AR System installer files.
For more information about the options.txt file, see Automatically generating an options.txt file and
Example options.txt file. (Reviewers - these links are applicable for 8.1 and would change for 8.0.)
To rename the server name references in the database form by using the Maintenance Tool
1. Create a silent options.txt file that contains the options for the ARSystemMaintenanceTool
utility.
For example, an ARSystem-ini-template.txt file would include the following options:
-J BMC_AR_USER=Demo
#Specify an encrypted password. Use the maintenance tool to generate
the encrypted password.
-J BMC_AR_PASSWORD=
-J BMC_AR_CONFIRM_PASSWORD=
-J BMC_AR_PORT=0
-J BMC_AR_SERVER_NAME=arservername
2. Download the ARFormsRenameUpdateTask.xml file for your release version from this
BMCDN topic .
Note
The XML file is version-specific. Download the XML file designated for your release
. For example, use the ARFormsRenameUpdateTask_7604.xml file if you are
making updates for the 7.6.04 release.
3.
Page 513 of 4705
Home
3. Copy the silent options.txt file and ARFormsRenameUpdateTask.xml into the <
ARSystemServerInstallDir>\arsystem directory.
4. Open a command (Windows) or shell (UNIX) window.
5. Navigate to <ARSystemServerInstallDir>\arsystem.
6. Run the ARSystemMaintenanceTool utility with the following command:
(Windows) ARSystemMaintenanceTool.cmd -silent -post_config post_config -DOPTIONS_FILE=ARSystem-ini-template.txt DPROGRAM_FILE= ARFormsRenameUpdateTask _7604.xml
(UNIX) ./ARSystemMaintenanceTool.sh -silent -post_config post_config -DOPTIONS_FILE=ARSystem-ini-template.txt DPROGRAM_FILE= ARFormsRenameUpdateTask _7604.xml
Configuring the BMC Remedy Mid Tier to rename the server

This topic describes how to update the BMC Remedy Mid Tier components.
Updating the configuration with the BMC Remedy Mid Tier Configuration Tool
1. Use the following URL to open the BMC Remedy Mid Tier Configuration Tool: http://<
midTierServerName>:8080/arsys/shared/config/config.jsp.
Replace midTierServerName with your mid-tier server name to form the actual URL in your
case.
The system prompts you for a password (default is arsystem) to open the Mid Tier
Configuration Tool.
2. Update the AR Server Settings.
a. Click AR Server Settings.
b. Add the new AR System server.

c. For name resolution, register newServerName in the new environment, and delete
the existing servers (if any) in the host file or DNS.
3. Update the General Settings.
a. Click General Settings.
Page 514 of 4705
Home
b. Update the following fields with the newAR System server name:
Preference Server(s)
Data Visualization Module Server(s)
Homepage Server
Authentication Server (if you want the mid-tier to use a specific authentication
server)
4. Click AR Server Settings, and delete the old AR System server name.
5. Update the Report Settings.
a. Click Report Settings.
b. If the BOXI/Crystal Report Server 11 Location field is not empty, update the field
with the new BOXI/Crystal server name.
c. Make sure that the Report Working Directory field is pointing to the correct directory
.
Cleaning up files in the mid tier

1. After you rename the server for the mid tier, stop the Java Virtual Machine (JVM) on which
the mid tier is running.
2. Delete all the contents of the midTierInstallationFolder/cache folder and
3.
4.
5.
6.
midTierInstallationFolder/cachetemp folder (if it exists).

Delete the viewStats.dat and viewStats.dat.bak files if they exist under
midTierInstallationFolder/WEB-INF/classes folder.
In you are using the prefetchConfig.xml file in midTierInstallationFolder/WEB-INF/
classes folder to precache forms, update the server-name element to the new server name.
Start the JVM mid tier.
Delete the browser's temporary internet files.
Page 515 of 4705
Home
Configuring the BMC Remedy Email Engine to rename the server

The following procedure describes how to update the server name in the BMC Remedy Email
Engine:
1. In the EmailDaemon.properties email server configuration file, replace oldServerName
with newServerName. For example:
com.bmc.arsys.emaildaemon.servers=<oldServerName>.labs.bmc.com
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.TCP=0
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.RPC=0
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Language=en_US
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Password=
M7D17cnnrgyyQnLF1RgTctJ6w6xtv+Tzdb9Ag3SdrbBgfgQ6SV54mic6HG/
xtJM1Fyu8FABW/C4h0zOv/rObN3CLl/Y9Y12VVw0ngJe5r+VCyqE5vo95FA==
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Interval=30
com.bmc.arsys.emaildaemon.<oldServerName>.labs.bmc.com.Authentication=
2. In a browser, open the AR System Email Mailbox Configuration form. (This form appears
only if Email Engine is installed.) Go to http://<newServerName>:<port>/arsys/forms/<
newServerName>/AR+System+Email+Mailbox+Configuration/Default+Admin+View/ .
3. In the Email Server Name/IP field, enter the new email server's name. (Make this change
only if the actual Email Post Office server has changed.)
Configuring the BMC Remedy Flashboards server to rename the server

To update the server name in the Flashboards server, update the ARServerName property with the
new server name in the server.conf file in the Flashboards folder.
Configuring the BMC Remedy AR System Web Services registry to rename the
server
The following procedure describes how to update the server name in the BMC Remedy AR System
Web Services registry.
1. In a browser, open the BMC Remedy AR System Web Services Registry form.
2. For all occurrences of each record on this form, replace the old server name with the new
server name.
Updating help file paths to rename the server

The following procedure describes how to update the server name in the paths to the help files for
BMC Remedy applications.
1. In a browser, open the SHARE:Application_Properties form.
2. Search for all records where the Property Name field has an entry of Help File Path.
3. Modify all occurrences of the mid tier and AR System server names with the new names.
Page 516 of 4705
Home
Configuring BMC Atrium Integration Engine to rename the server

The following procedure describes how to update the server name for BMC Atrium Integration
Engine.
1. Within an administrative Notepad session, open the aie.cfg file, and change the AR System
server name, user name, and password.
Note
To open Notepad as an administrator, choose Start Menu > Accessories >
Notepad, right-click on the Notepad icon, and choose Run as administrator.
2. If you change the user name and password, complete the following steps:
a. From the Services panel, stop the AIE service if it is running.
b. In a web browser, open IT Home, and click BMC Atrium Integration Engine
Console.
c. Select Configuration > Integration Engine App.
d. Update the Admin Login Name and Admin Password fields.
e. In the Help File Path field, replace the old AR System server name with the new
name.
f. Click Save.
3. Run the REPAIR option for aiexfer:
a. Open an administrative instance of Command Prompt.
To do this, choose Start Menu > Accessories > Command Prompt , right-click on
the Command Prompt icon, and choose Run as administrator.
b. Enter the following command, substituting the <hostName>, <userName>, and <
password> placeholders for the server that you are repairing:
aiexfer.exe -REPAIR -x <hostName> -l <userName> -p <password> -path "C:\

Program Files\BMC Software\AtriumCore\aie\service64
Page 517 of 4705
Home
The path to the service64 folder might be different, depending on the installation path
chosen for the BMC Suite.
c. Click on Start > Run and enter Services.msc to open the Services MMC.
d. Right-click the BMC AIE Service, and choose Start.
e. Ensure that the BMC Remedy Action Request System service is Started.
f. In a browser, open the AIE Console via the Home Page form. (You must be logged in
as an administrator.)
g. In the left column of the AIE Console, select Integration Engine App.
h. In the dialog box that appears, verify that the user name is an administrator within
your system, and re-enter the password for that user.
i. Click Save and close the AIE Console form.
j. Restart the BMC AIE Service.
To do this, choose Start > Run, and enter Services.msc. Right-click on the BMC AIE
Service entry, and select Restart.
k. In the browser, re-open the AIE Console and verify that you are viewing the Data
Exchange screen.
l. Open each Data Exchange entry and click the Instance drop-down menu.
m. Select the Instance listed, and click Save and Close.
Configuring BMC Remedy IT Service Management to rename the server

The following procedure describes how to update the server name for BMC Remedy IT Service
Management.
1. Update the server name in the CAI Application Registry form.
a. In a browser, open the CAI Application Registry form in Search mode.
b. In the Server field, enter the old server name, and click Search.
Do not enter any information in the other fields before performing the search.
c. In the Server field for each record, replace the old server name with the new server
name, and save the record.
2. Search for records in the following BMC Remedy IT Service Management forms, and
replace the old server name with the new server name.
AST:ARServerConnection
AST:ComplianceARBased_Advanced
TMS:ApplicationRegistry
SYS:Escalation
SYS:Attachments (If the out-of-box data is modified by replacing the arserver or
midtierserver placeholders with the host names, only then change these values to the
correct server host name.)
Note
Some forms might not be available (depending on the BMC Remedy IT Service
Management installation).
Page 518 of 4705
Home
Configuring BMC Service Request Management to rename the server

The following procedure describes how to update the server name for BMC Service Request
Management.
1. In a browser, open the Application Settings form:
a. Open the Application Administration Console.
b. Click the Custom Configuration tab.
c. Select Service Request Management > Advanced > Application Settings .
2. In the Mid Tier Path field, replace the mid-tier server name with the new mid-tier server
name and the port number (for example, newMidTierServerName:8080).
3. Update the server name in the PDL:ApplicationSettings form.
a. In a browser, open the PDL:ApplicationSettings form.
b. In the Hostname field, enter the newServerName.

4. Update the server name in the Report form.
a. In a browser, open the Report form.
b.
Page 519 of 4705
Home
b. In the Server field, enter the oldServerName, and perform a search.

c. Replace the oldServerName with the newServerName.
5. If you are using advanced interface forms (AIFs), update the Server field in each
configuration entry with the new server name.
Note
For existing service request records, when a user views the Process View tab
under Service Request Details, the URL for the fulfillment application (see the ID
field in the following screenshot) will refer to the old server name specified in the
CAI Application Registry. Consequently, the URL will not work. The URL cannot be
updated, so the user must open the corresponding fulfillment application manually.
New service requests (submitted after the server name was changed) will pick up
the updated CAI Application Registry server name, and the URL will work correctly.
Configuring Atrium Integrator to rename the servers

The following procedure describes how to update the server name for Atrium Integrator.
You need to update the new server name at the following locations:
Page 520 of 4705
Home
1. Update the UDM:Config form.

a. In a browser, open the UDM:Config form.
b. Update the Host field with the new host name.
2. Update the UDM:RAppPassword form.
a. In a browser, open the UDM:RAppPassword form.
b. Update the new server name in the Server Name field.
c. Update the new password in the RApp Password field.
3. Remove all existing entries from the UDM:ExecutionInstanceform.
a. In a browser, open the UDM:ExecutionInstance form.
b. Delete all the existing entries.
4. Perform this step only if you have executed jobs on the old server by modifying the UDM:
PermissionInfo form.
For the executed jobs, remove the old server entry from the UDM: PermissionInfo form.
a. In a browser, open the UDM: PermissionInfo form.
b. Update the new server name in the Atrium Integrator Engine field.
5. Change the server name in the Atrium Integrator console.
a. Launch the Atrium Integrator console.
b. Open the Manage Datastores tool dialog box.
c. Select the data store.
d. Update the new server name the AR Server Name field.
6. Update the server name in Atrium Integrator Spoon.
a. Open the Atrium Integrator Spoon.
b. Open any one job which uses the old server name.
c. Open a transformation.
d. In the Explorer pane click Database connections> <old server name>. Database
connection dialog box is displayed.
Page 521 of 4705
Home
e. In the Settings section, update the new server name details.

f. Click OK.
g. Click Save.
7. Update the new server name in Job scheduler.
a. Open the Atrium Integrator console.
b. Open the Manage Job Schedule dialog box.
c. In the Carte Server drop-down list, select the new server name.
d. Click Save.
Setting security restrictions on file uploads

You can restrict BMC Remedy AR System users from uploading and viewing files with certain
extensions in BMC Remedy Mid Tier. This feature helps prevent users from uploading malicious
attachments and viewing them.
Restricting attachments
Disabling views
Page 522 of 4705
Home
Restricting attachments
Use the Attachment Security tab in the AR System Administration: Server Information form in the
BMC Remedy AR System Administration Console. You must be logged on as an administrator to
perform this procedure.
To restrict attachments
Server Information.
2. Click the Attachment Security tab as shown in the following figure:
3. Enter the attachment options that you need, and click Apply.
The following table describes the available options:
Field name
Attachment
criteria
Description
Include all attachments No restrictions on uploading attachments

Allow attachments with following extensions Upload attachments with extensions listed in Comma
separated list of limit extensions.
Disallow attachments with following extensions Do not upload attachments with extensions listed in
Comma separated list of limit extensions. All other attachments are allowed.
Comma
separated
list of limit
extensions
Attachment extensions that are allowed or not allowed, based on the Attachment criteria selected.
Attachment
exception
list
The list of Form names (field ID) for which attachment limitations do not applyfor example, Data Visualization
Module(3450298).
If the user uploads any attachment in the form fields specified in attachment exception list, these fields are not
validated and the attachments are uploaded without verification in the fields.
Attachment
validation
plugin name
Name of the custom validation plug-in that you developed for verifying attachments
Page 523 of 4705
Home
Field name
Description
The custom validation can perform any function per your requirements. You can develop the plug-in for
performing functions like verifying the attachment containing malicious content, verifying whether the attachment
is a virus, verifying whether the user has changed the extension for uploading the attachment, and so on.
Example: EXAMPLE.ARF.SIMPLE (name of the custom plug-in that you developed)
If you are using a C plug-in, add the .dll/.so path in the ar.cfg/ar.conf file in the following format to load the plug-in
: Plugin: <CompletePath>/myplugin.dll
Specifications for plug-in development:
The custom validation plug-in should be a Filter API Plug-in, which has only one API. Following is the prototype
for the API:
void ARFilterApiCall(void *object, ARValueList *inValues, ARValueList *outValues,
ARStatusList *status)
object Name of the object
inValues Indicates that it has only one value, which is of attachment type
outValues Indicates that it has only one value, which is of attachment type only when status is
warning; otherwise, the value is Null
status Indicates the status of the attachment validation ( OK, Warning or Error). If the status
is Warning, the outValue is used for saving attachment data.
Attachments flowchart
The following flowchart helps you understand the attachment security based on the options that you
select from the Attachment criteria list.
Attachment security flowchart
Scenarios for restricting attachments

The following table lists examples of parameter values for requests that include attachments:
Page 524 of 4705
Home
Parameter
Scenario 1
Scenario 2
Scenario 3
Scenario 4
Scenario 5
Scenario 6
Attachment criteria
Include all
attachments
Allow
attachment
Allow
attachment
Allow
attachments
Disallow
attachments
Disallow
attachments
with the
following
with the
following
with the
following
with the
following
with the
following
extensions
extensions
extensions
extensions
extensions
Comma separated
doc
doc
doc
doc
exe
exe
list of limit
extensions
xls
jpg
xls
jpg
xls
jpg
xls
jpg
dll
db
dll
db
gif
gif
gif
gif
Data
Visualization
example.doc
,
example.jpg
example.exe,
example.db
example.doc,
example.txt
example.exe,
example.dll
File is
attached.
Its extension
is
on the list of
permitted
extensions.
File is not
attached.
Its extension is
not
on the list of
permitted
extensions.
File is attached
.
Its extension is
not on the list
of
disallowed
extensions.
File is not
attached.
Its extension is
on
the list of
disallowed
extensions.
Attachment
exception list
Module(41006),
Report
(2000012)
Attached File
examples
example.dll,
example.gif
example.jar
(JAR File field
on Data
Visualization
Module form)
File is attached.
All attachment
options
are permitted.
Status
File is attached.
The JAR File
field ID
is added to the
attachment
exception list.
Disabling views
You can also restrict users from viewing the content of certain types of files. Use the Attachment
Security tab in the AR System Administration: Server Information form in the BMC Remedy AR
System Administration Console. You must be logged on as an administrator to perform this
procedure.
Server Information.
2. Click the Attachment Security tab, shown in the following figure
Page 525 of 4705
Home
3. Enter the display options that you need, and click Apply.
The following table describes the available options:
Field name
Description
Display criteria
Allow display of all attachments Users can view all the attached files by clicking the Display
button in the Attachments pool.
Allow display of attachments with the following extensions Users can view attached files
that have extensions specified in Comma separated list of display extensions.
Disallow display of attachments with the following extensions Users cannot view attached
files that have extensions specified in Comma separated list of display extensions. All other
attachments are allowed.
Disallow display of all attachments Users cannot view any attachment.
The display criteria are applied to all the existing extensions in the BMC Remedy Mid Tier application.
Comma separated
list of display
extensions
Lists the attachment extensions that you want to allow or not, based on Display criteria
For any particular attachment that you want to view, the Display button in BMC Remedy
Mid Tier or the Display menu command in the BMC Remedy User Tool is enabled only if
Display criteria enables you to view that attachment. For all other attachments, the
Display button or menu command is dimmed.
Setting server statistics options

The AR System server enables you to gather performance statistics on the server. You can also
gather statistics about the longest running SQL and API calls.
The AR System server adds exception logging, where API and SQL performance exceptions are
recorded in a new log file, arexception.log.
Finding out which calls are causing delays can help you troubleshoot performance issues.
For details about the performance exception logging feature, see Exception Logging.
Page 526 of 4705
Home
To gather statistics about the longest running SQLs and APIs

1. On the AR System Administration: Server Information form, click the Server Statistics tab.
2. In the API/SQL Performance Tracking section, complete the following fields:

Field
Description
Enable
Console
Display
When selected, displays API and SQL events in the console when an automatic save is triggered (by the time
specified in the Auto Save and Purge Interval (min) field) and when you click one of the Save buttons:
Save Completed API
Save Completed SQL
Save Pending API
Save Pending SQL
This is a debugging aid that is available if you are running the server from a command window. (This option is not
available when you are running the server on Windows as a service because there is no console.)
The default is off (not selected).
Enable
When selected, enables exception logging, where all API and SQL calls that exceed the value specified in the
Exception
Logging
Minimum Elapsed Time (mSec) field are immediately written to the arexception.log file.
Number of
Saved
Operations
Defines the maximum number of completed longest operations that can be saved in memory. The number applies
to both API and SQL lists of operations.
The default is 20. If you decrease this number, you must restart the server for the change to take effect. (A restart
is not required if you increase the number.) Although 20 is the recommended value to control the overhead of
statistics management, you can increase this number up to 100.
Auto Save
and Purge
Interval (min
)
Defines the interval (in minutes) for when the longest operations saved in memory are flushed to the
corresponding forms in the database and then purged.
Minimum
Elapsed
Time (mSec)
Sets the minimum duration of the longest API and SQL events saved in the memory buffer in milliseconds. Any
event shorter than this value is discarded.
The default is 0 (no interval); no automatic save and purge are performed. If you change the interval, the new
interval is used if it is less than the time remaining for the old interval. Otherwise, the new interval is used after the
current interval expires.
Page 527 of 4705
Home
Field
Description
If an event is at the minimum or a greater number of milliseconds, it qualifies to be saved. Consequently, if the
event is not one of the longest operations in the list, it is not saved. (The maximum is defined by the Number of
Saved Operations field.)
The default is 5,000 milliseconds. If you enter 0, all events (up to the limit set in the Number of Saved
Operations field) are saved.
To manually flush the statistics and view the results

1. On the AR System Administration: Server Information form, click the Server Statistics tab.
2. Click the appropriate button for the type of statistics you want to gather:
Save Completed API
Save Completed SQL
Save Pending API
Save Pending SQL
The Save Pending API and Save Pending SQL buttons record the API calls and SQL
commands that are currently in process. In-process events are not subject to the Minimum
Elapsed Time setting.
The Save Completed API and Save Completed SQL buttons record the longest API and
SQL operations that are currently saved in memory. After flushing to the corresponding
forms in the database, the currently saved operations are cleared from memory.
3. To view the results:
a. Open the appropriate form by entering one of the following URLs:
http://<midTierServer>/arsys/forms/<ARSystemServer>/Server Statistics:
Longest APIs
http://<midTierServer>/arsys/forms/<ARSystemServer>/ Server Statistics:
Longest SQLs
b. Enter search criteria, and click Search.
Information gathered in the statistics forms

The Server Statistics: Longest SQLs form or the Server Statistics: Longest APIs form contains the
following information:
Field
Contents
API name
Text name of the API associated with the event (or INTERNAL)
User
User name associated with the event (or SYSTEM)
Thread ID
ID of the thread associated with the event
Result
Code
Error code that resulted from the event. If there is no error, 0 is the error code.
Start Time
Time that the event started
Server
Name
Name of the server where the event occurred. All servers in a server group share the same form.
Page 528 of 4705
Home
Field
Contents
Parameters
(API only) Additional details about the API call (for example, the form name on entry-related calls)
SQL
Command
(SQL only) First 1,000 characters of the SQL command issued to the database
Extended
Data
If the API parameters or SQL command exceed 1,000 characters, the entire string is contained in this field.
Elapsed
Time (in milliseconds) required to complete the event. For SQL events, this time represents the statement
execution only. It does not include any subsequent record retrieval time.
Time (
mSec)
Client Type
Text name of the type of client used to send the API (or Unidentified Client)
RPC ID
Unique ID of the event RPC, or 0 (if generated internally)
Create
Origin of the event recording:
Mode
Auto Longest API or SQL event that was recorded at an Auto Save and Purge Interval (the option
selected on the Server Statistics tab on the AR System Administration: Server Information form).
Demand Longest API or SQL event that was recorded from an on-demand request
In Process Incomplete API or SQL event that was recorded from an on-demand request
Queue
Delay (
mSec)
(API only) Time (in milliseconds) in the thread queue before processing started
Data
Retrieval (
mSec)
(SQL only) Reserved for future use
Create
Date
Date and time the entry was added to the form (not the event time)
Exception Logging
The BMC Remedy AR System server adds exception logging to the API and SQL server statistics
feature. This feature provides additional options for managing API and SQL performance statistics.
The key additions are:
A new log file, arexception.log, is the repository for all exception-logging activity. The
arexception.log file is managed like the arerror.log file.
API calls that reach the server and are not completed before the client times out are logged
to arexception.log. A client timeout server event is also available that allows client timeouts
to be detected through server workflow.
API and SQL calls that exceed the defined minimum time threshold are logged immediately
to arexception.log if the exception-logging option is enabled.
You enable exception logging for the performance statistics feature on the Server Statistics tab of
the Administration Server form by selecting Enable Exception Logging in the API/SQL
Performance Tracking form.
Page 529 of 4705
Home
For more information about the API/SQL Performance Tracking form, see Setting server statistics
options.
Server Statistics tab
This document covers the following topics:

arexception.log contents
Logging Messages
Logging long-running API and SQL to the exception log
Client timeout logging
1. Pre-execution check
2. Post-execution check
Long-running API and SQL calls
Standalone SQL
Standalone SQL that produced an error
SQL call within an API call
API call
Server Event support for client timeouts
Server event workflow
arexception.log contents
Like the arerror.log file, the arexception.log file is created automatically with no options for its
name or location. Log lines are always appended to arexception.log, and the file does not have an
artificial size limit. The AR Server version string is written to arexception.log every time the server
starts up.
The contents of a log segment consist of the following components:
Message that describes why logging is occurring
Timing statement to quantify why this operation is being logged
Log lines (in the same format as if they had been logged to the API or SQL log)
Status messages, should any notes, warnings, or errors occur during execution
Page 530 of 4705
Home
The following figure shows an example of the arexception.log file:
Logging Messages
The format of the exception log is similar to the arerror.log file in that each entry starts with a
message, followed by supporting information. A message is tagged as an ARNOTE. The following
messages are used in exception logging:
SQL operation elapsed time has exceeded the configured threshold (
ARNOTE 595)
API operation elapsed time has exceeded the configured threshold (
ARNOTE 596)
API operation did not complete prior to the client timeout (ARNOTE
597)
API and SQL operation did not complete prior to the client timeout (
ARNOTE 598)
Logging long-running API and SQL to the exception log

With the existing performance statistics feature, API and SQL calls that exceed the threshold value
and are within the top 20 (or the value specified in the Number of Operations field) were saved in
the AR Server's memory. That collected data can be written to a form on a scheduled basis or on
demand. When exception logging is enabled, all long-running API and SQL calls are immediately
written to the arexception.log file. Writing to the exception log is independent of saving the top 20
collected calls: both methods may be used, one may be used, or neither may be used.
The threshold value for long-running API and SQL calls is specified in the Minimum Elapsed Time
field of the API/SQL Performance Tracking form. The threshold value is shared with the
performance statistics feature, with a default value of 5,000 ms (5 seconds).
Client timeout logging

Logging client timeouts for calls that reach the server is not optional: each time the AR Server
detects this condition, it is written to the exception log based on pre-execution or post-execution
checks:
Page 531 of 4705
Home
1. Pre-execution check
This occurs when an API has just started being processed by the thread assigned to the call, and
the call is not one that performs updates. This check ensures that the call has not already spent all
of its time in the Dispatcher queue and that it does not start performing any work when the client is
no longer waiting. This type of call is logged as a failure, because the server records an error in the
status. For example:
2. Post-execution check
This occurs when the call is completed and the API performance statistics have been gathered.
This type of call is logged as a success or failure depending on what occurs when the call runs.
There are two variations of this occurrence:
An API call with no SQL identified as the root cause of the timeout -- If multiple SQL
statements within the API exceed the client timeout by themselves, only the first and most
important SQL statement is included.
An API call with an SQL statement that exceeds the client timeout value - -If multiple SQL
statements within an API each contribute to the excessive overall time, but none in particular
exceed the client timeout, no SQL statement is included. Diagnosing this case still requires
full API/SQL/filter logging.
The following figures show examples of the two cases. The first shows an API call with no SQL,
and the second shows an API call with an SQL call that exceeds the client timeout:
Long-running API and SQL calls

Logging long-running API and SQL calls to the exception log depends on enabling exception
logging in the API/SQL Performance Tracking form. After they are enabled, all calls that exceed the
minimum elapsed time value are immediately recorded in the exception log. Gathering performance
Page 532 of 4705
Home
statistics occurs regardless of whether exception logging is enabled. Saving the top 20 long-running
API or SQL calls in memory does not influence logging behavior. Qualifying items are not saved in
the Top 20 list if the list already has 20 items of greater elapsed time, but all long-running API and
SQL calls are logged. The following logging scenarios are possible:
Standalone SQL
The following example shows a typical logging sequence for an SQL call with no associated API
call:
Standalone SQL that produced an error

The following example shows an SQL call that exceeds the threshold does not complete
successfully:
SQL call within an API call

The following example shows an SQL call that exceeds the minimum elapsed time threshold,
causing its API call to exceed the threshold as well:
API call
An API call that exceeds the threshold without any corresponding SQL looks like this:
Page 533 of 4705
Home
Server Event support for client timeouts

The AR System server adds a server event type for client timeouts. With this feature, a server
event entry is created that provides information about the API call that experienced the timeout.
Client timeouts can be detected with server event workflow, which provides expanded capabilities
for communicating with administrators and users. For example, if a long-running API call caused a
client timeout, server event workflow could email the affected user and notify the administrator
about the details of the timeout.
You enable server event support for client timeouts by selecting Client Timeout on the Server
Events tab of the Admin Console:
The information provided in the Server Event form is tailored to notifications, with fields that can be
easily used in the qualification and as substitution parameters in the notification text. For more
information, see Types of events you can record and Viewing client timeout server event details .
Server event workflow

The standard BMC Remedy AR System does not include server event workflow, and the client
timeout feature does not provide workflow with the form. The administrator must create the server
event workflow. The following figure shows an example of the filter workflow an administrator might
use to be notified of a user timeout:
Page 534 of 4705
Home
Renaming the AR System server

You must scan for AR System server names and rename servers in the following circumstances:
You move your database to a new environment during an upgrade.
You copy a production database to a development or test environment.
You use a standard image to instantiate a virtual machine for BMC Remedy AR System.
You move your existing AR System server into a multitenant mid tier environment, which
requires that each AR System server is uniquely named.
Use the BMC Remedy AR Server Rename utility to rename an AR System server and to ensure
that the server name used by the mid tier and the AR System server is the same.
Using the Rename utility, you can:
Scan the database for the AR System server name
Replace the AR System server name in the following locations:
Specified forms and fields in the database
Specific configuration files and property files
Windows Services and Registries
Repair server name references for BMC Atrium Integration Engine
This topic explains how to use the Rename utility to scan for and replace the server name:
Sequence of server name replacement tasks

Rename utility command and options
Scanning the database for the server name
Replacing the server name in the database
Replacing the server name in files, services, and registry entries
Page 535 of 4705
Home
Repairing server name references in BMC Atrium Integration Engine
Sequence of server name replacement tasks

Perform the server name replacement tasks in the following order:
1. Replace the server name in the database. In a server group environment, perform this
operation only on the primary AR System server.
2. Replace the server name in files. In a server group, perform this operation on all servers in
the server group.
3. (Windows only) Replace the server name in the Windows Services and Registries. In a
server group, perform this operation on all servers in the server group.
4. Restart your computer. In a server group, restart the computers on which the primary and
secondary servers are running.
Rename utility command and options

The BMC Remedy AR Server Rename command-line utility ( arsrename .bat or arsrename.sh) is
available in the ARSystemInstallationFolder\ARSystem\artools folder. Use the following
command and its options to run the utility:
arsrename
[-u] [-p] [-a]
[-x] [-t] [-timeout]
[-o] [-tokens] [-f] [-fsf] [-fsv] [-ie] [-ief]
The following table describes the arsrename command options, which can be used in any order in
the command.
Option
Description
-u
Name that identifies the user account for the AR System server
-p
Password for the user account

If the user account has no password, use -p "". You can ignore this parameter if the password is empty or blank.
-a
Name of the external authentication string or Windows NT domain

This option is related to the Login window's Authentication field. See Authentication String Alias introduction.
-x
Name of the server to connect to
-t
TCP port number to connect to

If the port number is unknown, use -t 0.
timeout
Time, in seconds, during which the connection must occur, specified in the following format:
-timeout Normal:Long:XLong
The default values for Normal:Long:XLong are 120:400:1800.
Page 536 of 4705
Home
Option
Description
Note: You must specify all three values even if you want to set a single timeout value.
For example, if you want to set the Long timeout value to 600 seconds, use the following command:
-timeout 120:600:1800.
-o
Operation code:
1Scan
2Replace string tokens
3Replace string tokens in files
4Replace string tokens in Windows registry entries
5Run the Atrium Integration Engine (aiexfer.exe) utility
-tokens
List of string tokens in comma-separated value format
-f
File path of the CSV file that contains the list of forms and fields for token replacement (required if your operation code
is 3)
While performing a scan operation, use the -f parameter to generate the output CSV file. While performing a
replacement operation, use the -f parameter to pass the input CSV file.
-fsf
Whether to use fast scan

Use this option with operation code 1.
Valid values:
0Off (default)
1On
-fsv
Number of entries to scan

By default, 10,000 entries are scanned.
Valid value: Any positive integer
-ie
Whether to use the inclusion-exclusion list of forms in the scan

Valid values:
0Do not use inclusion-exclusion list
1Forms specified in the list are scanned along with other forms
2Only the forms specified in the list are scanned
-ief
Path of the inclusion-exclusion list

If the path is not specified or if the value of the -ie option is 1 or 2, the default text file available in the
ARSystemInstallationFolder\ARSystem\artools\etc\arsrename folder is used.
Scanning the database for the server name

Use the Rename utility to scan for the AR System server name or a token string in the database (
Regular forms, character and diary fields). For example, in a multitenant environment, you can use
the utility to scan the database forms and fields for occurrences of the onbmc-s string in the AR
System server name on the myARServer computer. At the command prompt , type the following
command:
arsrename -x myARServer -u Demo -o 1 -p <password> -t <port> -tokens "onbmc-s" -f "c:\

data\Output.csv" -timeout 120:600:1800
Page 537 of 4705
Home
The output of the scan operation is a CSV file ( output.csv) that displays the results of the scan as
a table consisting of the information shown in the following figure and described in the subsequent
table:
Output of the scan operation

Column
Name
Description
Form name
Name of the regular form in which the AR System server name is found
Field ID
ID of the character field in which the AR System server name is found
Is Partial (Y/
N)?
Flag that indicates whether the field contains a partial or a complete string of the server name:
YPartial string
NWhole string
Merge (Y/N)?
Flag that indicates whether the scanned server name is to be replaced or not; this value is referred to during the
replace operation
YStandard field
NCustom field; not replaced during replace operation
If you want even the custom fields to be replaced, you must enter Y in the column for the custom field whose
server name value you want to replace.
Special (Y/N)
?
Flag that indicates special handling required during the replace operation
Tip
You can use the output generated by the scan operation directly as input for the replace
operation, which replaces the server name in database.
Examples
Use the following command to perform a fast scan for 5,000 entries:
Page 538 of 4705
Home
Arsrename -x myARServer -u Demo -o 1 -f c:\data\output.csv -fsf 1 fsv 5000 tokens onbmc-s
Use the following command to scan only the forms listed the inclusion-exclusion list (a text
file) available at the specified path:
arsrename -x myARServer -u Demo -o 1 -f c:\data\output.csv -ie 2 -ief

C:\<ARSystemInstallationFolder>arsystem\artools\src\
inclusion-exclusion-list.txt -tokens onbmc-s
Format of the inclusion-exclusion list

You can control the forms that are scanned by creating an inclusion-exclusion text file that contains
the list of forms that you want to include in or exclude from the scan and the qualification that you
want to set for the scan.
The following sample code shows the format of the inclusion-exclusion list:
#--Inclusion list
#----the following qualification is for fetching outgoing messages that are sent
i,AR System Email Messages,'18092'=1 and '18099'=1
#----The following qualification scans only those SRDs which are not closed.
i,SRM:Request,'7'!=9000
#--Exclusion list
e,AR System Server Group Operation Ranking
e,AR System Service Failover Ranking
e,AR System Service Failover Whiteboard
e,ServerStatistics
The following table describes the formats used in this file:

Format
Description
Specifies a comment line
Specifies the inclusion list
Specifies the exclusion list
Exclusions from the scan operation

The scan operation ignores the following forms and fields during scanning:
Archive forms
Audit forms
Reserved fields on any regular forms
Page 539 of 4705
Home
Core fields with field IDs ranging from 1 to 99 (except field ID 8)

Distributed Server Option (DSO) fields with field IDs ranging from 300 to 322
Dynamic groups with IDs ranging from 60000 to 60999
Special fields
112 (Access control)
179 (GUID)
160 (Locale)
Server Statistics form
AR System API Statistics form
AR System Service Statistics form
AR System Service Statistics Configuration form
AR System Version Control: Object Modification Log form
AR System Version Control: Object Reservation Label form
AP:Detail form
AP:Question-Comment-Info form
Application Pending form
AR System Email Error Logs form
AR System Email Error Messages form
AR System Email Messages form
BPCU-Logs form
Replacing the server name in the database

Use the Rename utility to replace the AR System server name in the database. The replace
operation takes a CSV file as an input and either completely or partially replaces the server names,
depending upon the values specified in the input CSV file. The input.csv file is available in the
AR_SERVER_HOME\artools\etc\arsrename folder.
Notes
The input.csv file contains the information required to replace the server names in
a tabular format with the same columns as the output.csv file.
Use the input.csv file if you have not done any customizations to get the server
name in any base field, overlay, or custom field.
Warning
Do not replace the server name in the following forms:
AR System Server Group Operation Ranking
Page 540 of 4705
Home
AR System Service Failover Ranking

AR System Service Failover Whiteboard
In the input.csv file, delete the rows that contain these form names.
The replace operation replaces only those forms or fields that have a Merge flag set to Y in the
input.csv file. To handle special cases, specify Y in the Special (Y/N?) column of the input.csv
file.
As an example, use the following command to replace the onbmc-s string with tenant1-onbmc-s:
arsrename -x myARServer -u Demo -o 2 -tokens "onbmc-s=tenant1-onbmc-s" -f "C:\Program

Files\BMC Software\ARSystem\artools\etc\arsrename\input.csv" -timeout 120:600:1800
Replacing the server name in files, services, and registry entries

Use the utility to replace the current server name in the following files of the BMC installed products
, services, and registry entries:
Component
Server
Files in which to replace the server name
AR_SERVER_HOME\ARSystemInstalledConfiguration.xml
AR_SERVER_HOME\conf\ar.cfg
AR_SERVER_HOME\conf\armonitor.cfg
AR_SERVER_HOME\AREmail\EmailDaemon.properties
AR_SERVER_HOME\flashboards\server.conf
AR_SERVER_HOME\pluginsvr\pluginsvr_config.xml
AR_SERVER_HOME\pluginsvr\fts\primary\pluginsvr_config.xml
AR_SERVER_HOME\pluginsvr\fts\secondary\pluginsvr_config.xml
AR_SERVER_HOME\diserver\.kettle\arservers.xml
BMC Atrium Core

ATRIUMCORE_HOME\AtriumCoreInstalledConfiguration.xml
ATRIUMCORE_HOME\cmdb\plugins\ne\pluginsvr_config.xml
ATRIUMCORE_HOME\cmdb\plugins\shared\pluginsvr_config.xml
ATRIUMCORE_HOME\cmdb\reswift\conf\REConf.properties
BMC Remedy IT Service

Management
BMC_REMEDY_ITSM_SUITE_HOME\BMCRemedyITSMSuiteInstalledConfiguration.xml
BMC Remedy Service

Level Management
BMC_SLM_HOME\SLMInstalledConfiguration.xml
BMC Remedy Service

Request Management
BMC_SRM_HOME\BMCServiceRequestManagementInstalledConfiguration.xml
BMC Remedy Knowledge

Management
BMC_RKM_HOME\BmcRkmInstalledConfiguration.xml
BMC Remedy IT Process

Designer
BMC_ITSM_PROCESS_DESIGNER_HOME\ProcessDesignerInstalledConfiguration.xml
Page 541 of 4705
Home
Component
Files in which to replace the server name
BMC_ITSM_PROCESS_DESIGNER_HOME\Server\\ARID.xml
Other files on Windows

C:\Windows\System32\drivers\etc\hosts
C:\Program Files\Common Files\AR System\Licenses\ server_HostName
If the name of the folder contains the server name, the folder name is replaced. In the
preceding example, the folder name server_HostName gets replaced.
Services
BMC Remedy Action Request System Server server_HostName
BMC Remedy Email Engine - server_HostName 1
BMC Remedy Flashboards Server - server_HostName
Registry entries
HKEY_LOCAL_MACHINE\SOFTWARE\Remedy\ARServer\server_HostName
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Remedy\server_HostName
Examples
Use the following command to replace a server name that contains the onbmc-s string
with tenant1-onbmc-s in AR System and other files:
arsrename -x onbmc-s -o 3 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p "" -t 0
Use the following command to replace a server name that contains the onbmc-s string
with tenant1-onbmc-s in the Windows services and registry entries:
arsrename -x tenant1-onbmc-s -o 4 -tokens "onbmc-s=tenant1-onbmc-s" -u Demo -p

"" -t 0
Notes
The Rename utility changes the server name in the configuration files, property
files, and XML files. The utility does not change the data in the archive ( .arx) files.
Before you run the command to replace server names in the files, ensure that the
following environment variables are defined:
ATRIUMCORE_HOME = D:\BMCSoftware\BMCAtriumCore
BMC_AR_SYSTEM_HOME = D:\BMCSoftware\BMCARSystem
BMC_REMEDY_ITSM_SUITE_HOME = D:\BMCSoftware\BMCITSM
Page 542 of 4705
Home
BMC_SERVICE_REQUEST_MANAGEMENT_HOME = D:\BMCSoftware\
BMCSRM
BMC_SLM_HOME = D:\BMCSoftware\BMCSLM
BMC_RKM_HOME = D:\BMCSoftware\BMCRKM
If any of these environment variables is not defined, the server name in the files is not
replaced.
Repairing server name references in BMC Atrium Integration Engine

The BMC Atrium Integration Engine uses the aiexfer.exe utility to repair server name references in
Integration Engine forms and services.
Note
Shut down the BMC Atrium Integration Engine before running the Server Rename utility.
Using the operation code 5 available in the AR Server Rename utility, you can call the aiexfer.exe
utility to repair server name references. The server name passed to this command is the newly
renamed server.
Use the following command:
arsrename -o 5 -x <newARServerName> -u <user> -p <password> -t <port>
For example:
arsrename -o 5 -x newARServer -u Demo -p "" -t 0

A server group consists of two or more servers that share the same database and are designated
as part of a server group. Server groups are designed to provide failover operations for crucial
operations. They can also provide scalability and load balancing.
AR System servers in a server group
Page 543 of 4705
Home
To ensure high availability of BMC Remedy AR System operations, you can set up a server group
to provide failover protection by assigning rankings to servers in the group for specific BMC
Remedy AR System operations. Servers in a server group can provide failover protection for the
following functions:
Administrative operations
Archiving
Assignment Engine
BMC Atrium CMDB
BMC Remedy Distributed Server Option (DSO)
BMC SLM Collector (a component of BMC Service Level Management)
Business Rules Engine (a component of BMC Service Level Management)
Escalations
Full Text Indexing
Reconciliation Engine
A server group can also provide ease of administration because it has only one database to
manage and back up. In addition, AR System servers that belong to a server group share all
licenses except BMC Remedy AR System server licenses. One server in the group is designated
as the administrative server. When you change workflow and applications on this server, the
changes are automatically propagated to other servers in the group.
You can also configure specific servers in the group to handle reporting, reconciliation, and other
tasks that can impact performance, freeing up the remaining servers in the group to handle user
traffic.
A server group can provide load balancing for heavy user traffic. You can use a hardware load
balancer with a server group to direct user traffic to some or all servers in the group. See
Configuring a hardware load balancer with BMC Remedy AR System .
Server group functionality is not supported for multiple servers on one computer, and servers
earlier than release 6.0 are not compatible with server groups.
Page 544 of 4705
Home
Note
You can set up two or more AR System servers to share the same database without
making them members of a server group. In this case, failover protection is not available,
but you can manually configure the servers to provide load balancing and other scaling
operations. See Sharing a database without using a server group .
The following topics provide detailed information about how to configure server groups:
Configuring the server group check interval
Setting failover rankings for servers and operations
Configuring the server group signaling option
Configuring full text search for a server group
Bypassing the load balancer to work on a specific server
Using data archiving with server groups
Configuring logging for server groups
Removing a server from a server group or remove an unused server name
Sharing a database without using a server group
Configuring the server group check interval

The Check Interval setting determines how often each server in the group identifies itself to other
servers in the group, as well as how often it checks to see whether other servers are still alive. The
Check Interval works together with the Delinquent Threshold to determine the total time from a
server failure to when the next ranked server takes over an operation. See Delinquent threshold.
Checking server group status and reporting status generates a certain amount of database traffic,
so you should tune this setting to balance the time to failover against the frequency of posting the
check and query to the database.
To set the Check Interval

1. Open the AR System Administration: Server Information form.
Setting the check interval on the Advanced tab
3.
Page 545 of 4705
Home
3. In the Check Interval field, enter how often you want the server to identify itself and check
the status of other servers in the group.
Values are:
Default 60 seconds
Minimum 30 seconds
Maximum None
If you change this value after a server group is running, you must restart all the AR
System servers.
The information shared between servers in the group includes:
The current server's own status
Whether any server is delinquent
The parameters needed for sending signals
Information about operational responsibilities
For more information, see Setting failover rankings for servers and operations .
4. Click OK.
5. Restart each server in the server group.

The AR System Server Group Operation Ranking form contains entries that define the failover
ranking for servers that handle certain operations in the server group, and the delinquent threshold
that helps determine when another server takes over an operation. This form is automatically
created when you specify the first server as a member of the server group and restart the server.
When the form is created, it is populated with default entries and the first server added to the server
group is assigned the primary ranking for all operations. The remaining server group members
have null (empty ranking) entries, serving as placeholders. Entries for operations that require a
license (for example, DSO) are not pre-populated unless a valid license is detected. You can add
these operations at any time.
Note
Remove the default entries for operations that do not run in your environment.
AR System Server Group Operation Ranking form

Page 546 of 4705
Home
Operation rankings
The fields named Operation, Server, and Rank work together to define which server is the primary
server for the operation, which server takes over if the primary server fails, and so on.
Guidelines to set operation rankings for the server group

Use the following guidelines to determine how to set operation rankings for the server group:
The servers for any one operation are ranked lowest to highest. A value of 1 indicates the
server chosen first to perform the operation. The next highest value indicates the server that
takes over the operation if the first server fails, and so on.
Ranking numbers do not need to be consecutive.
If a value is null, the server ignores the entry.
If an operation has no server designated with a valid rank, it is not run on any of the servers
in the group.
Avoid assigning two servers the same ranking for the same operation. (For ease of
configuration, the form enables you to do this temporarily.)
Operations can be spread freely across different servers, with the exception of operations
involving BMC Remedy Approval Server, BMC Atrium CMDB, and the BMC Service Level
Management engine (labeled Business Rules Engine in the form). These operations must
reside on the same server as the administration operation; therefore, the operations must
have the same ranking as the administration operation so that they move as a unit.
If you are implementing full text search (FTS), an additional restriction for multi-platform
server groups exists. The Administration and Full Text Indexing operations must be
restricted to server group nodes that can have a compatible directory structure for the
Search Server configuration files.
To establish operation rankings in the server group

1. In a browser, log on as a user with Administrator privileges to any server in the group.
2. Open the AR System Server Group Operation Ranking form in search mode.
http://<midTierServer>:<portNumber>/arsys/forms/
<ARSystemServer>/AR+System+Server+Group+Operation+Ranking/
3. Perform an unqualified search to see the entries in the form.
4. Modify entries as required to construct a fail-over hierarchy for ownership of operations.
5. Save the AR System Server Group Operation Ranking form.
6. Restart all the AR System servers in the group.
Delinquent threshold
The Delinquent Threshold field determines the number of times the specified server can miss
reporting its status before the next server in the ranking takes responsibility for the operation. This
setting works together with the Check Interval to determine the total time to failover for any
operation.
Page 547 of 4705
Home
Configuring the server group signaling option

When object definition changes are made on the administrative server in a server group, other
members of the group can be notified either by a database posting or by a signal:
Notification
Description
By default, handles these changes
Reduces server activity when object definition changes are

communicated between servers and reduces the number of cache
Server definition changes such as

changes to forms, active links, filters, and
reloads when a series of changes is made. A delay occurs before

other members of the server group pick up the changes.
escalations and user group changes.
Other servers are notified of changes immediately. No delay occurs in

resynchronization or updating definitions.
All other changes, such as Alert

registration and DSO activity.
type
Database
posting
Signaling
Note
You can configure the server to
use signaling for all changes,
including server object changes.
See Configuring the server group
signaling option.
Server group signaling introduction

Servers in a server group use the arsignald daemon to notify other members of the group about
signaled changes. This daemon (arsignald.exe on Windows and arsignald on UNIX) is a
persistent process started by the AR System server at server start up. It maintains a pipe to the
associated AR System server and handles all signals to the other members of the server group.
Therefore, signaling between members of a server group requires only one additional server
process per server.
Note
In previous releases, server group signaling was performed by the arsignal program,
which caused a separate process to be spawned and then closed down for every change.
This could significantly impact resources on the host computer. The arsignal program is
still available for use by AR System workflow, but is no longer used for server group
signaling.
Using signals for all changes in server groups

The Server-Group-Signal-Option server configuration file option tells the server whether to use
arsignald for all signals instead of using a combination of signaling and database posting. If this
option is set to true (T), all server object changes are communicated by arsignald. Use this option
to avoid any delay in communicating server object changes to other servers in the server group.
Page 548 of 4705
Home
To use signals for all changes in server groups, add the following line to the ar.conf (ar.cfg) file of
each server in the server group: Server-Group-Signal-Option: T
If this option is set to false ( F) or is not included, server group signals are accomplished by the
default method described in this section.
See also Server-Group-Signal-Option.
Note
Form, workflow, and escalation time changes can significantly increase the workload on a
production server. In a server group environment, that effect is magnified when other
servers are notified of the changes and they recache definitions from the database.
Consider this when planning changes of this type.
Disabling automatic signaling in server groups

Signals triggered by certain object definition changes on the administrative server can cause
recaches on target servers that significantly increase memory use temporarily. This increase can
adversely affect the response time of the target servers. To change object definitions on the
administrative server without impairing the performance of target servers, you can disable
automatic signaling from arsignald and the database for changes to the following data:
Archive definitions
Escalation scheduling
Form definitions
Group information from the database
Workflow definitions
Signals triggered by changes to user, licensing, and computed group information are not disabled.
Later, when memory use is low, you can manually send the signals to the target servers by using
the arsignal program.
To disable automatic signaling for the specified changes, add the following line to the ar.conf (
ar.cfg) file of each server in the server group: Disable-ARSignals: T
If this option is set to false ( F) or is not included (the default), automatic signaling remains in effect
for all object definition changes.
See also Disable-ARSignals.
Page 549 of 4705
Home

Use the following information to understand how full text search (FTS) works and how it is
configured in a server group environment.
Overview of how FTS works in a server group
Configuring FTS for a server group
Overview of how FTS works in a server group

FTS within BMC Remedy Action Request (AR) System is made up of the following primary
components:
FTS code that manages the FTS functionality
FTS plug-in a Java plug-in, which is the core index engine
Index
As events occur within AR System that cause data to be indexed, the AR System server sends that
data, along with appropriate instructions, to the FTS plug-in, which then adds, deletes, or updates
data within the index. Other events could include a request to search the index. AR System server
sends the search request to the FTS plug-in, which performs the search and returns the results to
AR System server. The AR System server then deals with the data accordingly.
When you configure a server group for FTS, ensure that the following conditions are met:
Only the primary FTS server is designated as the indexing server.
In FTS high-availability architecture, more than one server in the group can be designated as
the indexing server.
The primary FTS server is the single AR System server that also has the FTS collection
and conf directories located on a local disk.
The primary FTS server hosts all instances of the FTS plug-ins.
You can designate a server as the primary FTS server by ranking it in the AR System Server Group
Operation Ranking form. For more information, see Setting failover rankings for servers and
operations.
FTS uses one plug-in as the writer (primary) and another plug-in as the reader (secondary). The
reader and writer plug-ins are installed on the FTS indexing server. In a server group, only one
writer instance must be running on the designated FTS indexing server. The FTS writer (primary)
serves as the reader and writer for the FTS indexing server, as well as a writer for all servers.
Only the designated primary FTS server has a ranking entry in the AR System Server Group
Operation Ranking form. The writer (primary) is connected to the FTS indexing server. The reader (
secondary) serves as the reader for all the other servers in the group, so you must configure all
other servers to connect to the reader instance running on the FTS indexing server. The reader
instance runs on a separate port on the FTS indexing server.
Page 550 of 4705
Home
The events that cause data to be written to the index result in data being put into the AR System
database as a queue of items to index. Only a primary FTS indexing server processes index
requests from this queue. However, any instance of AR System server can send a search request
to its corresponding FTS plug-in. This ensures index integrity. To further ensure integrity of the
system, the FTS plug-in design is such that any launched instance defaults to a read-only state
until the primary FTS indexing server specifically initializes the primary plug-in instance for writing.
For more information, see FTS plug-in configuration.The FTS indexing server communicates with
the writer plug-in for all search and indexing requests. There is no search fail-over for the writer
plug-in running on the FTS indexing server.
Note
The secondary reader plug-in serves the search requests from other servers and does not
serve as a backup to the primary writer plug-in.

If you use FTS in a server group, only one server in the group can index data at a time.
In FTS high-availability architecture, more than one server in the group can index data.
Each primary FTS indexing server has its own virtual queue of data to index. When AR System
queues data for indexing in parallel to AR Database changes in data, it queues separately for each
primary FTS Indexing server as designated by the Server Group Ranking form for FTS.
In a server group, the server that owns the full text indexing operation processes all pending
indexing tasks regardless of their server of origin. (The other servers have read-only access to the
index files.)
FTS is configured after all servers in the group have been installed and configured to run within a
server group. It is recommended that the FTS collection directory and the FTS configuration
directory be located on the same computer.
To set up FTS in a server group

1. Rank the FTS servers in the AR System Server Group Operation Ranking form. For more
information, see Setting failover rankings for servers and operations .
Note
You should use the FTS indexing server, which is ranked 1 in the AR System
Server Group Operation Ranking form, for searching and the other FTS indexing
server, which is ranked 2, as the failover server.
Page 551 of 4705
Home
> General > FTS Configuration.
3. Complete the form as per FTS Configuration form in the AR System Administration Console .

The BMC Remedy Distributed Server Option (DSO) is used to build large-scale, distributed
environments that behave like a single virtual system. DSO enables an organization to share
common information among geographically distributed servers and to keep that information
consistent. DSO enables you to transfer requests between servers and to keep copies of a request
synchronized across multiple servers, even if those servers are geographically dispersed.
In a BMC Remedy AR System environment with load balancing or multiple servers, a DSO server
process runs on each server, but only one process actively distributes data. The configuration
needed to support DSO fail-over is limited to modification of the distributed mappings to indicate
that any server in the server group can act as the source server.
To configure DSO for load balancing, you must configure multiple servers to use a single database
(in addition to configuring the hardware load balancer). To do this, a server group is used. In a
server group, you can use DSO to provide automatic fail-over capability for transfer operations
typically restricted to one server. You do this by creating a distributed mapping and then specifying
that transfers can be initiated from any server in the group. See Creating distributed mappings.
For example, as illustrated in the following figure, you can transfer copies of a request to other
servers and ensure that any changes made to the copies are also made to the original request. The
way that you define the processes for transferring information is similar to the way that you define
business processes for an application. First, managers at each site must agree on what information
to transfer from one application to another, what conditions drive transfers, and which sites control
the ability to update a record. An administrator at each site then uses DSO to implement these
decisions.
Distributed AR System servers in a server group using DSO
Page 552 of 4705
Home
To configure DSO for a server group
Note
To configure DSO in a server group environment, you must specify a server group name.
Log on to the primary server, and perform the following steps:
1. In a browser or BMC Remedy User, open AR System Administration Console,
and click System > General > Server Information.
2. On the Advanced tab, enter the server group name in the Server Group Name
field.
3. Click OK to apply the changes.
1. In BMC Remedy Developer Studio, double-click Distributed Mappings in the AR System

Navigator object tree.
2.
Page 553 of 4705
Home
2. On the Basic panel of each distributed mapping, select the Allow Any Server in Server
Group check box.
This setting indicates to the servers in the group that regardless of the source (From) server
name specified in the mapping, any server in the group is qualified to be the source server.
In the event of a fail-over where the distributed operation moves from one server to another,
the data continues to be processed.
Related topics
DSO for load balancing
Enabling DSO on an AR System server

If the port number (RMIPort) for email administration in BMC Remedy Email Engine is different
from the default (1100), set the corresponding option in the BMC Remedy AR System server ar.cfg
(ar.conf) file to the same port number.
For a single email engine configuration, the syntax is: Server-Group-Email-Admin-Port:
2020
If multiple email engines are configured for the server, each engine must have a unique RMIPort.
For a multiple email engine configuration, use semicolons to separate the RMIPort numbers:
Server-Group-Email-Admin-Port: 2020;2030;2040
This enables the server to communicate email administration information to BMC Remedy Email
Engine during server group processing. When multiple port numbers are specified, the server
sends the same information to each port number.

BMC Remedy AR System servers that belong to a server group provide automatic fail-over for its
member servers for some operations, such as escalations. Multiple BMC Remedy AR System
servers and their associated BMC Remedy Flashboards servers function as one server. Only one
BMC Remedy Flashboards server is active at a given time, while the other BMC Remedy
Flashboards servers in the server group act as backup servers.
When a computer failure or BMC Remedy AR System failure occurs, the active BMC Remedy
Flashboards server on that computer also shuts down. In this case, an associated BMC Remedy
AR System server detects the shutdown and activates a backup BMC Remedy Flashboards server
in the same group. When the computer becomes active, the BMC Remedy AR System server
reactivates the first BMC Remedy Flashboards server and deactivates the backup server.
However, when a BMC Remedy Flashboards server fails on a host on which an BMC Remedy AR
System server is still functioning correctly, the BMC Remedy AR System server cannot detect the
failure and cannot activate the backup server.
Page 554 of 4705
Home
To monitor flashboards servers for server failure

1. Use the following command: java -jar FlashboardAgent.jar ping -h <
serverHostName>
This command returns a 0 to standard out when the server is functioning correctly, and
returns a -1 to standard out if the server fails.
2. To make sure that the server restarts again, run the server.bat (Windows) or server.sh (
UNIX) commands.
Note
If a BMC Remedy Flashboards server and an BMC Remedy AR System server are
part of the same group, they must be installed on the same computer.
Setting the port number for a flashboards server in a server group

If the port number (RMIRegistryPort) for flashboards administration in the flashboards server is
changed from the default (1099), set the BMC Remedy AR System ar.cfg (ar.conf) file to the same
port number.
The syntax is as follows: Server-Group-Flashboards-Admin-Port: 2021.
This enables the server to communicate flashboards administration information to the flashboards
server during server group processing.
Bypassing the load balancer to work on a specific server

To change object definitions and workflow on the administrative server in a load-balanced
environment, you must bypass the load balancer to connect to the administrative server with BMC
Remedy Developer Studio. The same consideration applies when you must make configuration
changes on a specific server in the group in a browser.
To do this, you can connect to the server by using the unique server name rather than the load
balancer name (which is the same as the common server name alias for the group).
To ensure that the server recognizes references to itself as the current server while designing
workflow and applications, add the IP Name setting to the configuration file. This setting indicates
to the server that any of a given set of server names is recognized as the current server. You might
need to designate a short name and a long name for each server as shown in the following
example:
IP-Name: serverA
IP-Name: serverA.remedy.com
Page 555 of 4705
Home
If BMC Remedy Developer Studio used either of these server names to log in, that server is
recognized as the current server in workflow.
Using data archiving with server groups

By default, the data archiving feature is enabled on an AR System server. To disable archiving for
all forms on a server, select the Disable Archive option on the Configuration tab of the AR
System Administration: Server Information form.
For a server group, you can disable archiving on all the servers except one if you want archiving to
take place on only one server. To do this, configure the server group in the AR System Server
Group Operation Ranking form to make sure that only one server performs the archiving operation.
Configuring logging for server groups

Information tracked in the server group log file includes the starting and stopping of operations, the
evaluation of other servers, and the timing of each event. The arsignald log file tracks the startup
and shutdown of the arsignald daemon and all signals sent between servers in the group.
To turn on the server group and arsignald log files

1. Open the AR System Administration: Server Information form, and click the Log Files tab.
2. Select the logging to use:
For server group logging, select the Server Group Log check box.
For arsignald logging, select the ARSIGNALD Log check box.
3. Enter a path for each log file if you do not want to use the default paths.
4. Click OK.
To log server group activity in the Server Events form

1. Open the AR System Administration: Server Information form, and click the Server Events
tab.
2. Select the Server Group Actions check box.
3. Click OK.
Note
You cannot log arsignald activity in the Server Events form.
Page 556 of 4705
Home
Removing a server from a server group or remove an unused

server name
To remove a server from a server group
1. Open the AR System Administration: Server Information form, and click the Configuration
tab.
2. Clear the Server Group Member check box.
3. Restart the server.
To remove an unused server name

1. Open the AR System Server Group Operation Ranking form, and remove all the entries for
the server name.
2. Restart one of the servers in the server group.
The server that you restarted removes all the server group references for a server that does not
have any ranking entries.
Sharing a database without using a server group

The recommended way to share a database is to create a server group. Alternatively, you can
configure two or more AR System servers to share the same database without making them
members of a server group. In this case, automatic failover protection is unavailable, and when you
change object definitions, you must manually refresh the cache on other servers in the group (for
example, by restarting them).
This approach can be sufficient for managing performance. For example, you can use a shared
database in an environment where the user traffic all goes to one AR System server. In this
scenario, you can use another server on the same database to handle tasks such as reporting or
reconciliation, which can have a performance impact on the AR System server.
When you share a database without using a server group, you must designate one server as the
administrative server by disabling administrative functions on the other servers sharing the
database. Also note that specific services can only be running on one system at a time, and in
some cases, additional configuration is required to manage them (that is, escalations need to be
disabled on all but one server and the assignment engine should only run on one server).
To share a database between AR System servers without using a server group, perform the
following installation and configuration steps:
During installation
Select the Overwrite or Upgrade option for the first server installed.
Page 557 of 4705
Home
Select the Server Group option when installing subsequent servers that share the same
database.
Specify the same database information for all servers that share the database.
Note
Choosing Server Group during AR System installation does not configure the
servers as members of a server group. It merely indicates to the installer that the
server shares the database with an existing AR System server, with or without
server group membership.
After installation
Determine which server is the administrative server, where you manage and modify forms,
workflow, and applications with BMC Remedy Developer Studio.
Isolate BMC Remedy Developer Studio access, escalations, and archiving to the
administrative server.
To turn off Developer Studio access, escalations, and archiving on the

non-administrative servers (without server groups)
1. In a browser, log on to each of the non-administrative servers as a user who is a member of
the Administrator group.
2. Click AR System Administration Console > System > General > Server Information .
3. Click the Configuration tab, and select the following check boxes:
Disable Admin Operations
Disable Escalations
Disable Archiving
Configuring java plug-in servers

You can use the AR System Administration:Plugin Server Config form to display information about
the Java plug-in servers. As an administrator, you can access this form from the BMC Remedy AR
System Administration Console.
Note
The AR System Administration:Plugin Server Config form is for Java plug-in servers only.
You cannot use this form to configure native plug-in servers.
Page 558 of 4705
Home
The following table lists the common fields on the AR System Administration:Plugin Server Config
form:
Field name
Description
Plugin Server Instance
Select a plug-in server instance from the list of available plug-in server
instances .
Plugin Server Instance

Path
Enter the path where the selected plug-in server instance is running.
Plugin Set
Select a plug-in set from the list.
Reference
Creating Java plug-in

sets
This property enables you to load multiple plug-ins that share a common
parent class loader.
Note: The Plugin Set Configuration tab is visible only if you select a value
for this field.
Plugin Server Host
Enter the host name of the computer where the selected plug-in server
instance is running.
The following table lists the tabs in the AR System Administration:Plugin Server Config form. The
information provided in each tab is described in the sections that follow.
Tab
Information
Reference
Global Plugin Server

Configurations
Enables you to configure the default plugin server settings
Setting global plug-in

server options
Plugin Server
Configuration
Enables you to create and configure the plug-in server settings
Setting plug-in server

options
Note: These settings override the settings defined in the Global Plugin
Server Configurations tab.
Plugin Configuration
Enables you to view, create, modify, and delete plug-ins and their
configurations
Working with Java

plug-ins
Plugin Set Configuration
Enables you to view, create, modify, and delete plug-in sets and their
configurations
Working with Java

plug-in sets
Note: This tab is visible only after you add a plug-in set.
Note
If you modify the Java plug-in server configuration data, you must restart the Java plug-in
server for the changes to take effect.
Page 559 of 4705
Home
Related topics
Troubleshooting issues with plug-in servers
Creating Java plug-in sets

> General > Plugin Server Configuration.
2. On the AR System Administration:Plugin Server Config form, click the plus sign to open the
Create Plugin Set form.
3. Enter the values for the following fields, and click Create:
Field name
Description
Plugin Instance
This field is populated with the value from the Plugin Server Instance field.
Plugin Set
Enter the name of the plug-in set.
Related topics
Setting global plug-in server options

Use the Global Plugin Server Configurations tab to create global settings for the plug-in servers.
These settings apply when the plug-in server options in Setting plug-in server options are not
specified.
2. In the AR System Administration:Plugin Server Config form, click the Global Plugin Server
Configurations tab.
3. Edit the options listed in the following table as needed.
Area name
Field name
Description
General
Configurations
Register
With
PortMapper
Specifies whether you want the Java plug-in to register with the portmapper
Valid values:
true
false (default)
Threads
Configurations
Max Threads
The maximum number of threads allowed in the thread pool. This is for worker threads
of plug-in servers.
Default: 10
Global default: 30
Page 560 of 4705
Home
Area name
Field name
Description
Number Of
Core
Threads
Specifies the total number of core worker threads that the Java plug-in server
initializes to process various RPC requests
Default: 5
Global default: 30
Number Of
Selector
Threads
Specifies the total number of selector threads that the Java plug-in server uses to
dispatch RPC requests to the core worker thread task queue
Default: 2
Global default: 5
Encryption
Encryption
Determines whether the plug-in server allows or requires encrypted communication
Configurations
Policy
with the AR System server

Valid values:
0 - Allowed but not required
1 - Required
2 - Not allowed (default)
Data
Encryption
Algorithm
Determines the network data encryption algorithm that the plug-in server uses to
communicate with its clients
Valid values:
1 - RSA low encryption, modulus 512 bits (default)
2 - RSA medium encryption, modulus 1024 bits (requires BMC Remedy
Encryption Performance Security)
3 - RSA high encryption, modulus 2048 bits (requires BMC Remedy Encryption
Premium Security)
Note: If the value of the Encryption Policy option is set to 2, this option is ignored.
Data Key
Expiry
Specifies the expiration time for the network data encryption key
Default: 2700 (seconds)
Public Key
Algorithm
Specifies the publickey-privatekey encryption algorithm that the plug-in server uses to
Valid values:
6 - RSA high encryption, modulus 2048 bits (requires BMC Remedy Encryption
Premium Security)
Public Key
Expiry
Specifies the expiration time for public key

Default: 86400 (seconds).
Other
Configurations
Work Queue
Monitor Log
Interval
Specifies the interval at which the core worker thread task queue monitor checks
whether the tasks in the queue exceed the threshold set for the Work Queue Task
Threshold option
Valid value: Any positive integer (milliseconds)
Default: 0
Specifies the maximum time that the excess idle threads will wait for a new task
before terminating
Page 561 of 4705
Home
Area name
Field name
Description
Excess Core
Threads Idle
Keep Alive
Time
Reload
Delay
Specifies the interval between the time that you add a plug-in configuration and the
Default: 0 (unlimited time)
time that the system dynamically loads and initiates the plug-in
During this interval, you can modify the new plug-in configuration if necessary without
restarting the plug-in server. After the system dynamically loads and initiates the
plug-in, any changes you make to the plug-in configuration require a plug-in server
restart.
Default: 30000 ms
Work Queue
Task
Threshold
Specifies the threshold for the core worker thread task queue. When the tasks in the
queue exceed this number, a message is logged in the arjavaplugin.log file.
Default: 5
Note: If the value of the Work Queue Monitor Log Interval option is set to 0, this
threshold is ignored.
Native
Configurations
Enable
Native
Bridge
Routes the AREAVerifyLogin calls to the Native Plugin Server through a bridge
Valid values:
true
false (default)
4. To save the changes, click Apply, or click Reset to restore the default values.
Related topics
Setting plug-in server options

Use the Plugin Server Configuration tab to create settings for the plug-in server instance. The
settings on this tab supersede the global plug-in server settings.
> General > Plugin Server Information.
2. In the AR System Administration:Plugin Server Config form, click the Plugin Server
Configuration tab.
3. Edit the options listed in the following table, as needed:
Area name
Field name
Description
General
Plugin Port
Specifies the TCP port number where the Java plug-in server runs
You enter this port when you install the AR System server, which sets the value of
Configurations
the Server-Plugin-Alias property in the ar.cfg or ar.conf file.

Note: If you have a single plug-in server instance, you can enter this value in the
Plug-in Server list on the Connection Settings tab of the AR System
Administration:Server Information form.
Page 562 of 4705
Home
Area name
Field name
Description
Valid values: Unused port numbers from 1024 to 64000
Default: 9999
Register With
PortMapper
Specifies whether you want the Java plug-in to register with the portmapper
Valid values:
True
False (default)
Masking
(Optional) Enables plug-in developers to implement the
Implementation
com.bmc.arsys.pluginsvr.ISignalMasking interface to enable a plug-in server to

use custom signals
Note: This option is for internal use only.
Example:
com.bmc.arsys.plugins.signal.SignalMaskForSpecificPlugins
Encryption
Configurations
Encryption
policy
Determines whether the plug-in server allows or requires encrypted communication

with the AR System server
Valid values:
0 - Allowed but not required
1 - Required
2 - Not allowed (default)
Data
Encryption
Algorithm
Determines the network data encryption algorithm that the plug-in server uses to
Valid values:
3 - RSA high encryption, modulus 2048 bits (requires BMC Remedy
Encryption Premium Security)
Note: If the value of Encryption Policy is set to 2, this option is ignored.
Data Key
Expiry
Specifies the expiration time for the network data encryption key
Valid value is any positive integer. The default is 2700 (in seconds).
Public Key
Algorithm
Specifies the publickey-privatekey encryption algorithm that the plug-in server uses
to communicate with its clients
Valid values:
6 - RSA high encryption, modulus 2048 bits (requires BMC Remedy
Encryption Premium Security)
Public Key
Expiry
Specifies the expiration time for public key

Default: 86400 (seconds)
Threads
Configurations
Max Threads
The maximum number of worker threads allowed in the thread pool of plug-in
servers
Default: 10
Global default: 30
Page 563 of 4705
Home
Area name
Field name
Description
Number Of
Core Threads
Specifies the total number of core worker threads that the Java plug-in server
initializes to process various RPC requests
Default: 5
Number Of
Selector
Threads
Specifies the total number of selector threads that the Java plug-in server uses to
dispatch RPC requests to the core worker thread task queue
Default: 2
Other
Configurations
Work Queue
Monitor Log
Interval
Specifies the interval at which the core worker thread task queue monitor checks
whether the tasks in the queue exceed the threshold set for Work Queue Task
Threshold
Default: 0
Excess Core
Threads Idle
Keep Alive
Time
Reload Delay
Specifies the maximum time that the excess idle threads waits for a new task
before terminating
Default: 0 (unlimited time)
Specifies the interval between adding a plug-in configuration and the system
dynamically loading and initiating the plug-in
During this interval, you can modify the new plug-in configuration if necessary
without restarting the plug-in server. After the system dynamically loads and
initiates the plug-in, any changes that you make to the plug-in configuration require
a plug-in server restart.
Default: 30000 ms
Work Queue
Task
Threshold
Specifies the threshold for the core worker thread task queue
When the tasks in the queue exceed this number, a message is logged in the
arjavaplugin.log file.
Default: 5
Note: If the value of Work Queue Monitor Log Interval(mSec) is set to 0, this
threshold is ignored.
Native
Configurations
Enable Native
Bridge
Routes the AREAVerifyLogin calls to the Native Plugin Server through a bridge
Valid values:
True
False (default)
4. To save the changes, click Apply, or click Reset to restore the default values.
5. (Optional) To copy the global settings for the selected plug-in server, click Copy Global.
Related topics
Page 564 of 4705
Home
Working with Java plug-ins

Use the Plugin Configuration tab to create, view, or modify plug-ins and their configuration
settings.
Note
When you create a new plug-in, it is loaded dynamically. You do not need to restart the
AR System server.
To create a Java plug-in

2. On the AR System Administration:Plugin Server Config form, open the Plugin
Configuration tab, and click Create to open the Create New Plugin form.
3. Enter values for the following fields, and click OK:
Field name
Description
Plugin Name
Enter the name of the plug-in.
Plugin Class
Enter the name of the Java class that will implement the plug-in.
Name
Value: Any valid class name from the JAR file
Plugin File
Enter the name of the file that the plug-in server loads to access the plug-in implementation.
Name
Note: This file is located in the plug-in server class path.
Value: The absolute file name of the JAR file that contains the class that contains the plug-in implementation
and all the dependent JAR files
AR Server
Enter the AR System server name where the Server-Plugin-Alias entry will be created.
Create Server
Plugin Alias
Select the check box to create the Server-Plugin-Alias entry in the AR System Configuration Component
Entry in
ARServer
Server-Plugin-Alias entry in the AR System Configuration Component Setting form.
Path Elements
Click the plus sign and enter the location of a dependent JAR file or the path to a dependent native library.
Each plug-in element can contain zero or more pathelement elements.
User Defined
Elements
(Optional) Click the plus sign and enter the user-defined configuration elements:
Setting form. Note: For the AR System server to communicate with the Java plug-in, you must create the
Setting Name Name of the user defined element.

The syntax for this element is:
pluginName.userDefined.settingName
Note: pluginName is automatically populated based on the value entered in the Plugin Name field.
Setting Value Value for the element.
Note:
Page 565 of 4705
Home
Field name
Description
You must define values for both Setting Name and Setting Value.
If you add two values for the same Setting Name, only the first value is applicable.
To view a Java plug-in

2. On the AR System Administration:Plugin Server Config Form form, open the Plugin
Configuration tab.
Field name
Description
Plugins
Displays the list of available plug-ins
Plugin Class
Displays the name of the Java class in the JAR file that implements the plug-in
Name
Plugin File
Name
Enter the name of the file that the plug-in server loads to access the plug-in implementation.
Note: This file is located in the plug-in server class path.
Value: The absolute file name of the JAR file that contains the class that contains the plug-in
implementation and all the dependent jar files.
Path Elements
Displays the location of the dependent JAR file or the path of the dependent native library
User Defined
Elements
(Optional) Displays the user-defined configuration elements for the selected plug-in
To modify a Java plug-in

2. On the AR System Administration: Plugin Server Config form, open the Plugin
Configuration tab.
3. In the Plugins list, select the plug-in that you want to modify.
4. Click Modify to open the Modify Existing Plugin form.
5. Modify the data as needed, and click OK.
To delete a Java plug-in

2. On the AR System Administration:Plugin Server Config Form form, open the Plugin
Configuration tab.
3. In the Plugins list, select the plug-in that you want to delete, and click Delete.
4. In the confirmation box, click Confirm.
Page 566 of 4705
Home
Note
You must restart the Java plug-in server for these changes to take effect.
Related topics
Working with Java plug-in sets

Use the Plugin Set Configuration tab to add, view, or modify plug-in sets and their configuration
settings.
Note
The Plugin Set Configuration tab is visible only if you select a value for the Plugin Set
field.
To add Java plug-in set configurations

2. On the AR System Administration:Plugin Server Config form, open the Plugin Set
Configuration tab, and click Create to open the Create\Modify Plugin Set Configuration
form.
3. Enter the values for the following fields, and click Create:
Field name
Description
Key Prefix
Enter the key prefix by using the following format:

pluginSetName.pathelement.type
pluginSetName must match the name in Creating Java plug-in sets.

Key
Type location or path.
Value
If you entered location in the Key field, enter the complete path to the JAR file.
For example: D:\BMCSoftware\BMCARSystem\pluginsvr\rle\lib\aspectjrt.jar
If you entered path in the Key field, enter the path of the folder that contains the JAR file.
For example: D:\BMCSoftware\BMCARSystem\pluginsvr\chg
Note
Page 567 of 4705
Home
There is no validation for the values you enter in the Key and Value fields. The plugin
server validates this internally. If these values are incorrect, they are not saved in the
pluginsvr_config.xml file. There is no error message logged in the arjavaplugin.log or
arplugin.log files either.
To view Java plug-in set configurations

Configuration tab.
The Plugin Set Path Elements area displays the list of available plug-in sets with their
values.
To modify Java plug-in set configurations

Configuration tab.
3. In the Plugin Set Path Elements list, select the plug-in set that you want to modify.
4. Click Modify to open the Create\Modify Plugin Set Configuration form.
5. Modify the data as needed, and click Update.
To delete Java plug-in set configurations

2. On the AR System Administration:Plugin Server Config Form form, open the Plugin Set
Configuration tab.
3. In the Plugin Set Path Elements list, select the plug-in set that you want to delete, and click
Delete.
4. In the confirmation box, click Confirm.
Related topics
BMC Remedy AR System cache management

The following topics provide detailed information about BMC Remedy AR System cache
management:
Page 568 of 4705
Home
Configuring the server cache

Guidelines for resolving cache memory issues
Setting the distributed mapping cache refresh interval
Actions that trigger cache events
Actions in ITSM 7.0.00 applications that trigger caching
Configuring the server cache

The following topics provide information about configuring the server cache:
Configuring a server's cache mode
Configuring cache load options
Configuring the AR System server to maximize memory use
Configuring a server's cache mode

You can set the following cache modes for your server operation:
Production cache mode (Default) Use this mode when operations performed by
application users should not be delayed by administrative operations or when a server has a
large number of active application users. In this mode, administrative operations cause the
server to create an administrative copy of its cache so that other users can continue using
the shared cache while administrative operations are performed.
Note
In this mode, the Definition Change Check Interval value is GREATER than 0 and the
Sync Cache feature can be used to sync any change from AR server. For details about
these Mid Tier configuration options, see Configuring the Cache Settings page.
Development cache mode In this mode, administrative operations do not cause a copy of
the cache to be made; instead, they lock other users out of the shared cache and wait for
users accessing that cache to complete their operations before performing changes.
Escalation and Archive threads must also complete their operations before Admin thread
changes can be completed. Therefore, potentially long running tasks -such as escalations,
BMC Atrium Integration Engine jobs, and queries - are incompatible with Admin thread
changes in this mode and can lead to long delays.
Note
Page 569 of 4705
Home
In this mode the Definition Change Check Interval value is 0, and the Sync Cache
feature cannot be used. For details about these Mid Tier configuration options, see
Configuring the Cache Settings page.
Access to the shared cache is restored when the administrative operation is completed. No time is
spent copying the cache, so operations have a smaller memory footprint and are performed faster
than in production mode.
In this mode, application-level changes are not automatically updated in the mid tier cache because
such updates are performed by ARValidateFormCache. For example, if you change an
application's primary form and then reload the page, the old primary form is redisplayed. To display
the new primary form on reload, you must first click the Flush Cache button in the Mid Tier
Configuration Tool (see Configuring the Cache Settings page).
Warning
Development mode is intended for servers whose main purpose is application

development. It is unsuitable for servers with many application users in a
production environment because user operations are blocked when administrative
operations, such as form and workflow changes, occur. This is especially
noticeable when many structures are changed, such as when an application is
imported. This often gives the false impression that the server is hung.
An additional scenario that can lead to a circular dependency is when an escalation
has begun to execute and an administrative operation comes into the server. The
administrative operation waits for the escalation to finish and will block all other
calls that come in so that it will be the first to execute after the waiting period is
over. The possibility for a circular dependency arises if the escalation triggers filter
workflow with its updates, and that workflow makes calls back into the server (like a
filter API plug-in might do). If the escalation causes any callback API calls to be
submitted they will be blocked behind the administrative operation that is already
waiting for the escalation to finish. Since the escalation cannot finish in a timely
manner because it is blocked by the callback API, the escalation will be slowed
considerably as it waits for the callback API to timeout. If the escalation works on
several entries this callback API scenario can play out over and over again until the
escalation has processed all the qualifying records. Eventually, the administrative
operation will be free to execute when the escalation finishes and all calls blocked
behind it will execute. However, those calls will have most likely timed out on the
client by that time.
Page 570 of 4705
Home
To set the cache mode

Server Information.
2. In the AR System Administration: Server Information form, click the Configuration tab.
3. Select or clear the Development Cache Mode check box.
When the check box is active, Development Cache Mode is enabled. When the check box is
inactive (clear), Production Cache Mode is enabled.
4. Click Apply to save your changes.
Note
The change takes effect as soon as you save it. You do not need to restart the
server.
Configuring cache load options

You can use the following options to optimize the time that it takes an AR System server to load
information into the cache and to manage how the server uses memory:
Setting the Preload Tables Configuration option
Caching display properties
Setting the Preload Tables Configuration option

The AR System server loads the cache from the database at the following times:
(All servers) At server startup
(Non-administrative servers in server groups) At runtime whenever the administrative server
in a server group signals that it made a change to the cache
The Preload Tables option allows the server to make better use of system resources, such as
multiple CPUs and network bandwidth, when loading the cache during server initialization and in
server group operations. Using the Preload Tables option, can greatly reduce server startup time
and the time required for cache reloads in a server group, but it requires that larger amounts of
memory are available to the AR System server. This option preloads metadata from database
tables into the server cache. The metadata includes field definitions and display properties.
Page 571 of 4705
Home
Setting preload threads and preload segments

When the Preload Tables Configuration option is off, a single thread loads information directly
from the database into the cache.
When the Preload Tables Configuration option is on, the server uses multiple threads running in
parallel (preload threads) to load data in segments from database tables into memory.
Each preload segment represents one or more schemas (forms). For example, if you have 3,000
schemas and you configure 300 preload segments, each segment represents 10 schemas. In that
case, a preload thread reading a segment of the field definitions table would process field
definitions for 10 schemas.
Because all forms do not have the same amount of data, configuring multiple preload segments for
each preload thread enables threads to balance their load effectively. For example, if you configure
only one segment per thread and some threads finish before others, the finished threads have no
more work to do. But if you configure multiple segments per thread, as a thread finishes loading
one segment, it can begin loading another.
Each thread uses a separate connection to the database. Any thread can load any segment. When
a thread finishes loading a segment, it begins loading another segment. When all segments have
been loaded, the thread terminates.
After the segments are loaded, the server populates the cache by reading the information from
memory instead of directly from the database.
You can configure the server to use preload threads at either of these times:
Only at server startup
Whenever the server loads its cache from the database
To configure preload threads, use the Preload Tables Configuration option on the Advanced tab
of the Server Information form.
The Preload Tables Configuration option is on by default for 64-bit UNIX or Linux servers. It has
the following default settings:
Preload Tables at Init Only No
Number of Preload Threads 20
Number of Preload Segments 300
To turn this option off, set Number of Preload Threads to 0.
This option is off by default for Windows servers.
Page 572 of 4705
Home
Note
If you configured the Preload Tables Configuration option before applying patch 001,
the patch installation does not change your settings.
Determining the optimum preload settings

Using preload threads can greatly reduce server startup time, but it temporarily increases memory
consumption.
If you use preload threads, start with the following settings:
Ten preload threads
One preload segment for every three schemas (forms) on the server
To determine the optimum settings in your environment, vary the number of preload threads and
segments to find the configuration that produces the fastest cache load time. Adjusting the number
of preload segments balances the load between the preload threads.
Such testing also helps identify the amount of preload memory required in addition to cache
memory.
Note
Initial testing of this feature at BMC Software indicates that a Unicode server with the full
ITSM suite and all language packs installed consumes about 500 MB more memory at
initial cache load when it uses preload threads than when it does not use preload threads.
When determining whether to use preload threads and how to configure them, consider the
following factors:
The amount of memory available to the AR System server at startup and at runtime.
BMC recommends that servers with 64-bit address spaces and plenty of memory be
configured to use preload threads anytime the cache is loaded from the database (
Preload Tables At Init Only = No).
BMC recommends that servers with limited memory, such as Windows servers with
32-bit address spaces, be configured to use preload threads only when the cache is
initially loaded from the database (Preload Tables At Init Only = Yes).
In the case of extremely limited memory, configure the server not to use preload
threads.
Page 573 of 4705
Home
Whether the server is part of a server group. Non-administrative servers in a server group
load the cache from the database whenever server object changes occur. These servers
derive the most benefit from using preload threads for all cache loads.
The number of database connections available. Each preload thread uses one connection to
the database.
Caching display properties

Display properties include the background images used in forms and the display properties of each
form field. Server display properties are display properties for forms and fields used in server
workflow only. The Display Property Caching option enables you to control how the server
caches display properties. This feature can be used alone or in conjunction with preload threads.
From release 7.5.00 or later, this option no longer distinguishes between form backgrounds and
field display properties. Instead, it provides these settings:
Cache all display properties (Default) Server response time is faster when a client
opens a form for the first time, but the memory space required for the server cache is larger.
Cache only server display properties Memory usage for the cache is smaller, but when
a client opens a form for the first time, response time is slower. This delay occurs because
the server must load the display properties from the database at that time.
To specify how display properties are cached, use the Display Property Caching option on the
Configuration tab of the Server Information form.
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.
Configuring the AR System server to maximize memory use

To maximize memory use in your environment, implement the following AR System server
configuration recommendations:
Limit large queries.
Do not allow users to perform unqualified searches.
To remove all unqualified searches, review existing workflow and modify it as necessary.
Set the following AR System server configuration options appropriately:
Memory use configuration options
Page 574 of 4705
Home
Option
Description
Delay-Recache-Time
For details about this setting, see Delay-Recache-Time.
Cache-Mode
For details about this setting, see Cache-Mode.
Max-Entries-Per-Query
For details about this setting, see Max-Entries-Per-Query .
Cache-Display-Properties
For details about this setting, see Cache-Display-Properties .
Disable-ARSignals
For details about this setting, see Disable-ARSignals.
Note
For more information about configuring cache properties to maximize memory utilization,
see Guidelines for resolving cache memory issues .
Guidelines for resolving cache memory issues

This section discusses how to prevent the following BMC Remedy AR System server processes
from reaching its maximum size in memory, which can cause the process to terminate or to stop
responding:
arserverd (UNIX)
arserver.exe (Windows)
The following topics provide detailed guidelines for resolving cache memory issues:
Improving the AR System server startup time
Avoid making administrative changes during peak hours
Configuring the AR System server to control memory use
BMC Remedy AR System caching
Checking the BMC Remedy AR System log files for long-running operations
For more information on resolving cache memory issues, see the blog Memory leak shared on
BMC Communities.
Improving the AR System server startup time

BMC improved the startup time of the BMC Remedy AR System server as follows:
For Release 7.5.00 and 7.1.00 patch 007, data is now stored in the field_dispprop table so
that it can be read from and written to more efficiently. For more information, see The field
table in the AR System data dictionary .
Tip
Page 575 of 4705
Home
This change allows field display properties of 4000 bytes or less, which previously were
stored as a character large object (clob), to be stored as a varchar in the propShort
column on Oracle, Microsoft SQL, and IBM DB2 databases. For details about converting
fields stored previously as clob objects, to varchar objects, see "knowledge base article ID
20015708".
For Release 7.5.00 and later, the BMC Remedy AR System server can use multiple threads
running in parallel (preload threads) to load information from the database tables into
memory. The server then populates the cache by reading the information from memory
instead of directly from the database. For more information, see Setting the Preload Tables
Configuration option.
If you use an earlier version of BMC Remedy AR System, consider upgrading to one of these
versions.
Avoid making administrative changes during peak hours

Do not make administrative changes (see Actions that trigger cache events) during periods of peak
usage.
This ban includes actions in ITSM applications that can cause an admin copy cache or a client
cache load (see Actions in ITSM 7.0.00 applications that trigger caching ).
Identify a time period when administrative changes can be performed, and ensure that all
developers and application administrators understand the importance of making administration
changes during this period only.
Configuring the AR System server to control memory use

Implement the following BMC Remedy AR System server configuration recommendations:
Limit large queries.
Do not allow users to perform unqualified searches. To remove all unqualified searches,
review existing workflow and modify the workflow as necessary.
Set the BMC Remedy AR System server configuration options appropriately ( see
Configuring the AR System server to maximize memory use ).
BMC Remedy AR System caching

To improve performance, the BMC Remedy AR System server caches all forms and their related
objects into memory during startup. This enables users to access objects more quickly than they
could if BMC Remedy AR System had to get the definitions from the database each time objects
were needed. The caching also reduces memory usage.
After start-up, be aware that certain actions can cause the following caches to occur:
Page 576 of 4705
Home
Client cache loads

Server cache loads
In-memory admin cache copy
For details about activities that can trigger a re-cache, see Actions that trigger cache events.
Warning
These cache loads can add multiple copies of the cache to memory. If the cache grows
too large, the BMC Remedy AR System server memory can quickly be depleted, which
can cause the server to stop working. To prevent this, follow the guidelines listed in BMC
Remedy Mid Tier recommendations.
Client cache loads

A client cache load occurs when the client detects that the local cached copy of an BMC Remedy
AR System object is older than the copy cached by the server. For example, if anything associated
with a form view changes or if group permissions change, a new copy of the affected object is
cached to the client.
Client cache loads can cause a severe performance problem if all the BMC Remedy AR System
server's clients perform caching tasks at about the same time such as, at the start of the business
day. Simultaneously processing multiple client cache load requests limits the BMC Remedy AR
System server's ability to support normal client activity.
Server cache loads

A server cache load from the database occurs when the BMC Remedy AR System server re-reads
all the data dictionary information from the database to update the server's internal cache. (The
internal cache is the server's in-memory cache of information from the database.) Loading the
cache from the database requires more memory than copying the cache because additional buffer
space is needed to hold records from the database.
Server cache loads from the database occur primarily at BMC Remedy AR System server startup,
but several actions can trigger them after startup (see Actions that trigger cache events).
To determine the amount of memory that will be temporarily required for any server cache load
from the database, check the size of arserverd (UNIX) or arserver.exe (Windows) in the host
computer's process list at the following time:
Immediately after the BMC Remedy AR System server process starts up The startup time
of the BMC Remedy AR System server process varies and is affected by the amount of
workflow and the number of forms, menus, fields in forms, and so on in the database.
Page 577 of 4705
Home
But before any user actions that require more memory occur At runtime, user actions
such as queries cause the server process to request more memory. Therefore, the size of
the process is no longer based only on objects cached from the database.
The memory impact of a server cache load affects performance, especially if the operating
system starts to page. Depleted memory might cause malloc errors. Server cache loads
from the database can cause severe performance problems if paging occurs in a virtual
machine (VM) environment.
In server groups, the non-administrative or secondary servers perform server cache loads
from the database instead of admin cache copy.
In-memory admin cache copy

An in-memory admin cache copy occurs when the BMC Remedy AR System server creates an
administrative copy of the cache for any administrative change. An admin cache copy does not
read the entire data dictionary from the database. Therefore, this type of cache generally does not
use as much additional memory as a server cache load. The amount of memory used during an
admin copy cache typically results in a temporary doubling of memory required for the cache.
You can set the following cache modes for the BMC Remedy AR System server:
Production mode (Default)
Development mode
Production mode ( Default )

Use this mode (Cache-Mode:0) when operations by application users should not be delayed by
administrative operations or when you have a large number of active application users. In this
mode, administrative operations cause the server to create an administrative copy of its cache (
admin cache copy) so that other users can continue using the shared cache while administrative
operations are performed.
Development mode
In this mode (Cache-Mode:1), administrative operations do not cause the server to make a copy of
its cache. Instead, they lock other users out of the shared cache and wait for users who are
currently accessing that cache to complete their operations before performing changes. Escalation
and Archive threads must also complete their operations before Admin thread changes can be
completed. Therefore, potentially long-running tasks, such as escalations, are incompatible with
Admin thread changes in this mode and can cause long delays.
Access to the shared cache is restored when the administrative operation is complete. No time is
spent copying the cache, so operations have a smaller memory footprint and are performed faster
than in production mode.
Page 578 of 4705
Home
Development mode is intended for servers whose main purpose is application development. It is
unsuitable for servers that have a large number of application users in a production environment.
The operations of those users are blocked when forms and workflow are changed, especially when
many structures are changed, such as when an application is imported.
Several customers also use development mode in their quality assurance (QA) and user
acceptance testing (UAT) environments. This is one reason that they do not experience caching
and memory depletion problems in those environments and are surprised when such problems
occur in their production environment.
Checking the BMC Remedy AR System log files for long-running operations
Certain long-running operations, such as escalations, archiving, or API calls, prevent the copy of
the cache that they use from being freed until the operation is finished. Multiple long-running
operations can tie up two or more copies of the cache. Check the BMC Remedy AR System log
files for such activity, and avoid it during peak hours.
Setting the distributed mapping cache refresh interval

To reduce the load on the BMC Remedy AR System database, distributed mapping information is
cached. By default, the cache is refreshed every 30 minutes. You can change the cache refresh
interval in Administration Console or the BMC Remedy AR System configuration file.
To set the distributed cache refresh interval

1. Open the BMC Remedy AR System Administration: Server Information form for the local
3. In the Cache Check Interval field, enter a refresh interval in seconds. The maximum value
is 43200 seconds (12 hours).
DSO-Cache-Check-Interval.
4. Click OK.
The change takes effect immediately. You do not need to restart the BMC Remedy AR
System server.
Actions that trigger cache events

The following topics provide information about the actions that trigger cache events:
Events that trigger cache and re-cache events
Actions that trigger cache or re-cache events
Reducing memory using Display Property Caching
Page 579 of 4705
Home
Events that trigger cache and re-cache events

In production mode, the AR System server caches all forms and associated objects into memory at
system startup. However, some actions and events can trigger a system re-cache.
The following events trigger cache and re-cache events:
Client re-cache A client cache load occurs when the client detects that its local cached
copy of an BMC Remedy AR System object is older than the server's cached copy (for more
information, see Client cache loads).
Server re-cache A server cache load from the database occurs when AR System server
rereads all the data dictionary information from the database to update the server's internal
cache (for more information, see Server cache loads).
Admin Copy Cache The AR System server creates an administrative copy of its cache
for any administrative change (for more information, see In-memory admin cache copy).
Note
For details about mid-tier caching, see Actions that affect mid tier caching .

Action
Client
re-cache
Server
re-cache
Admin copy
cache
Server startup
NO
YES
NO
Add a user
YES
NO
NO
Modify a user
NO
NO
NO
Delete a user
NO
NO
NO
Add a group
YES
YES
YES
Remove a group
YES 3, 9
NO
NO
Remove a group from the Group List in the User form
NO 5
NO
YES
Add a user to a group
YES 3,9
NO
NO
Remove a user from a group
YES 3,9
NO
NO
Add a computed group
YES 3,8
NO
NO
Add a group to a computed group
YES 3,8
YES
NO
Remove a group from a computed group
YES 3,8
YES
NO
Page 580 of 4705
Home
Action
Client
re-cache
Server
re-cache
Admin copy
cache
Add a user to a group that is part of a computed group
YES 3,8
NO
YES
Remove a user from a group that is part of a computed group
YES 3,8
NO
NO
arsignal -a
NO
NO
NO
arsignal -b
NO
YES
NO
arsignal -c
NO
NO
NO
arsignal -e
NO
NO
YES
arsignal -g
NO 4
YES
YES
arsignal -l
NO
NO
NO
arsignal -m
NO
NO
YES
arsignal -r
NO
YES
NO
arsignal -u
NO
NO
NO
arreload
NO 1,4
YES
YES
Create, modify, or delete an application
NO
NO
YES
Create, modify, or delete an active link
YES 2
NO
YES
Create, modify, or delete an active link guide
NO
NO
YES
Create, modify, or delete an entry in the Group form (not every field must be
affected)
NO
NO
YES 6
Create, modify, or delete an entry in the Role Mapping form (not necessarily
NO
NO
YES 6
Create, modify, or delete an escalation
NO
NO
YES
Create, modify, or delete a filter
NO
NO
YES
Create, modify, or delete a filter guide
NO
NO
YES
Create, modify, or delete a form
YES 7
NO
YES
Create, modify, or delete a menu
NO 3
NO 3
YES
Create, modify, or delete a packing list
NO
NO
YES
Create, modify, or delete a view
NO
NO
YES
Create, modify, or delete a web service
NO
NO
YES
every field)
1. A re-cache will occur in this case if one of the above changes that cause a re-cache were made before running the
arsignal command.
2. The user must have appropriate permissions to the active link.
3. If you attach the menu to the form, that will cause the client to re-cache the form definitions if the user opens that
form.
4. In this case, a server cache load from the database occurs if the arsignal command is run after an administrative
change takes place.
Page 581 of 4705
Home
5. Clients are unaware of group changes and load their cache only if an object is changed. If a group change makes an
object unavailable to the client, users cannot see the object on the BMC Remedy AR System server anymore.
6. Creation, modification, or deletion of entries in this form by workflow (not users) cause an admin copy cache. For
example, changes to the People form in an ITSM application that trigger a change in the underlying Group form cause
an admin copy cache.
7. The form must be open.
8. For all group users.
9. For the user.
Reducing memory using Display Property Caching

You can use the Display Property Caching feature to resolve 32-bit BMC Remedy AR System
server memory constraints, and to reduce server startup time by configuring how the server caches
display properties.
In the Server Configuration tab, set the Display Property Caching field to Cache only server
display properties. This reduces memory use and allows for a run-time re-cache if needed. This
feature can be used alone or in conjunction with preload threads.
For more information, see Configuration tab fields, Display Property Caching.
Note
The Cache only server display properties setting might impact performance when
display properties are requested, but the impact is not significant.

The following topics provide information about configuring the BMC Remedy Mid Tier cache:
About Mid Tier caching
About browser cache
BMC Remedy Mid Tier recommendations
Actions that affect mid tier caching
About Mid Tier caching

The first time a form, view, or form and view combination is requested via BMC Remedy Mid Tier,
performance can be impacted by the intensive processing necessary to obtain the form, field, active
link, and associated information from BMC Remedy AR System server. This can be time
consuming when there are large forms with many fields and many associated active links. It is also
important that memory is not consumed for forms that are not accessed.
Also refer to the mid tier caching recommendations.
Page 582 of 4705
Home
To minimize the usability impact of this performance hit, the Mid Tier Configuration Tool includes
the following configuration options:
Flush cache Removes all items from the mid tier cache. When the objects are requested,
the most up-to-date versions are retrieved from the BMC Remedy AR System server. For
details about the Flush Cache feature, see Flush Cache.
Sync cache Clears only objects that have changed on the server after the last cache
clear event. In this case the mid-tier contacts BMC Remedy AR System server and
compares the last-changed-timestamp on elements and synchronizes any changes. For
details about this feature, see Using the sync cache option.
Note
-- The Sync cache option is not available for 7.1.0 and prior releases.
-- When you restart BMC Remedy Mid-Tier (or Tomcat), it starts building views and
performing sync cache operations to ensure that the cache contents are up-to-date.
Loading those views in the cache takes time if there are a lot of AR System server
views in the viewstats.dat statistics file, which subsequently delays the sync cache
operation. During this period, if mid tier gets any request, it sends the older version
of the requested data.
As an administrator, you can check the sync status on the Cache Settings page to
verify whether the sync was completed successfully.
Definition Change Check Interval This mid tier cache setting is configured to set an
interval (in seconds) at which information in the cache is updated. The default value is 3600
seconds. For details about the Definition Change Check Interval setting, see Cache
settings.
Mid tier caching recommendations

Whom does this information benefit?
If you are using the caching recommendations developed on the prior design of mid tier's caching
infrastructure you may be restricted in realizing the benefits of the new design. Use the information
provided here if you are a user of:
version 7.5.00 patch 004 of AR System Mid-Tier
version 7.5.00 of AR Server any patch level or higher
version 7.1.0 of AR System - except new Sync Cache feature
Page 583 of 4705
Home
Recommended caching setup and procedures

Disable Mid-Tier Prefetch Prefetch has always been a brute force approach to loading
forms into memory based on a somewhat arbitrary list of forms configured in the
prefetchConfig.xml file by the system administrator. Forms and other cache objects end up
in memory, but are not actually ever used by end users wasting valuable memory space. To
disable Prefetch, log on to the Mid-Tier Configuration tool, on the Cache Settings page,
remove the contents of the prefetchConfig.xml file so only these elements remain and save
changes:
<?xml version="1.0" encoding="UTF-8"?>

<midtier-prefetch-config xmlns="http://www.bmc.com/remedy/midtier/midtier">
</midtier-prefetch-config>
On the Cache Settings page, ensure that the Perform Check check box is selected. This
activates another new 7.5.00 patch 004 feature called Sync Cache. Sync Cache eliminates
the need for administrators to flush the entire Mid-Tier cache after a form, active link, menu,
etc. definition change on the AR System server. Mid-Tier now automatically synchronizes its
cache for just the changed objects. It performs this check at the interval selected in the
Definition Change Check Interval field. Or, an administrator can press the new Sync
Cache button to have the changes synchronized immediately. The Sync Cache operation,
whether done automatically via Perform Check interval or by pressing the Sync Cache
button for the AR System server, synchronizes any of the following objects whose last
changed timestamp is newer on the AR System server than in the current mid tier cache:
Forms, Active Links, Containers (such as Guides, Applications, Web services, etc.), and
Menus (Character menus). Sync Cache completely removes and rebuilds the following
cache items since the performance hit is minimal: Group data, Role data, and Image objects.
On the ARServer Settings page in the Mid Tier Configuration tool, enable the new feature,
Preload, by selecting the check box next to the server name. Preload will, on a restart of mid
tier, load all Active Links and Menus to the disk cache and any form which is user facing,
that is, any form which has an Active Link associated with it.
Select the Enable Cache Persistence check box.
Save changes to the Cache Settings.
Shutdown the JSP engine. Remove the contents of mid tier's /cache and /cachetemp
directories and start the JSP engine.
Allow Preload to complete processing.
Page 584 of 4705
Home
Allow end users access to the system. BMC recommends allowing at least 1-2 days of
normal end user usage of the system. This type of activity is desired because mid tier
updates a statistics file of what forms and views the users are accessing. This statistics file,
viewstats.dat, tracks which forms/view combinations are being accessed, which group
combinations are accessing, and how many hits each has.
Note
The viewstats.dat statistics file is not related to the cache (ehcache) statistics (see
About the cache table). The viewstats.dat file is based on user activity and is not
dependent on any configuration.
After 1-2 days of usage, disable Preload using the Mid Tier Configuration tool, by
deselecting the check box next to the AR System server name on the ARServer Settings
page.
Stop the JSP engine.
Start the JSP engine. With Prefetch and Preload disabled, the mid tier, upon startup, use its
statistics file to quickly load up into memory from the disk cache, only forms which users
have been accessing. This allows for the most efficient use of mid tier's in memory cache
and the best form access performance for end users. It should also allow customers to only
have to pay the performance hit of pre-caching forms very rarely in a 7.5.00 mid tier patch
004 or the 7.5.00 AR System server environment.
About browser cache

If content is cached on the browser the first time that it is loaded, the browser does not have to
request that content again. This helps to improve performance as well as the network load.
When a browser sends a request to the mid tier server, the response might contain a
Cache-Control header. The browser uses this Cache-Control header to identify whether the content
should be cached and when this cached content expires. The browser uses the cached content
until it expires, after which it sends a new request to the mid tier server. If the response does not
contain the Cache-Control header, the browser sends a new request each time.
After browser cache is enabled, if the content on the mid tier server changes, the browser does not
detect the change because it uses the content from its cache.
The following topics provide information about working with browser cache:
How does browser cache work?
Updating browser cache
Page 585 of 4705
Home
How does browser cache work?

When the browser sends a request to the mid tier server, the server controls the response that
goes back to the browser. Depending on the type of request, the mid tier server determines
whether to send a Cache-Control header in the response.
Types of requests
The mid tier server controls browser cache based on the following types of requests:
Dynamic These requests fetch dynamic data, such as records, from the BMC Remedy
AR System database, and thus are not cached on the browser.
Example
/arsys/Backchannel/*
Resources These requests handle static data, such as static Javascript files ( .js) or style
sheets (.css), and thus can be cached.
Note
When a new BMC Remedy Mid Tier patch or hotfix is applied, the content of these
files might change.
You can adjust the Cache-Control expiry time for these requests in the config.properties
file. See Modifying the cache expiry settings .
Example
/arsys/resources/*
Form HTML / Javascript These requests fetch the HTML and active link .js files for a
requested BMC Remedy AR System form or schema.
Note
The content of these requests can change when changes are made to form
definitions or workflows.
Page 586 of 4705
Home
You can adjust the Cache-Control expiry time for these requests in the config.properties
file. See Modifying the cache expiry settings .
Example
/arsys/forms/*
Modifying the cache expiry settings

As an administrator, you can adjust the cache expiry settings from the config.properties file
located at /midTierInstallDir/WEB-INF/classes/. The browser uses these settings to determine
how long the content is cached.
Resources The default setting for this request type is 86400 seconds (1 day). To change
the cache expiry settings for this request type, modify the following entry:
arsystem.resource_expiry_interval=86400
Form HTML / Javascript The default setting for this request type is 3600 seconds (1
hour). To change the cache expiry settings for this request type, modify the following entry:
arsystem.formhtmljs_expiry_interval=3600
Updating browser cache

When a BMC Remedy AR System service pack, patch, or hotfix is applied to the BMC Remedy Mid
Tier binaries, or when changes are made to the BMC Remedy AR System definition files, you must
manually flush the browser cache.
Notes
You need not manually flush the browser cache whenever there is a change in
forms and other metadata in the AR System server. The changed forms are
automatically fetched from the mid tier and are reloaded in your browser.
If you have a server group setup with a load balancer, the browser cache
approximately takes 10 minutes to update and reflect the changes. You must sync
the cache after the shared database is updated with the changes.
Whenever there are changes in the AR System server, to keep the mid tier cache
up-to-date, you must still do a sync cache or flush cache.
In a Mid Tier cluster environment, to maintain consistency across all users, make
sure that the sync cache or flush cache operation is successfully completed
across all mid tiers.
Page 587 of 4705
Home
If the browser cache is not up-to-date, you might get some JavaScript errors. For information about
these errors and the importance of updating the browser cache, see Knowledge Base article ID
KA310492.
To flush the cache, you need to delete the temporary internet files.
Note
You do not need to delete the cookies, form data, saved passwords, or browsing history.
For a list of compatible web browsers, see Compatibility matrix in the BMC Remedy ITSM
Each browser vendor uses different options to delete the temporary internet files. As a user, you
must be aware of these options so that you do not delete the cookies that store other important
information, such as saved passwords.
To delete the temporary internet files

Microsoft Internet Explorer 8 or 9 Browse to Tools > Internet Options > Browsing
History > Delete > Delete Browsing History, clear all options except Temporary Internet
Files, and click Delete.
Mozilla Firefox Browse to Tools > Options > Advanced > Network, and click Clear
Now.
Apple Safari Browse to Edit > Empty Cache, and click Empty.
BMC Remedy Mid Tier recommendations

To maximize the performance and usability of BMC Remedy Mid Tier, the following configuration
practices are recommended:
Disabling BMC Remedy Mid Tier prefetch
Activating Perform Check
Activating Pre-Load
Enabling Cache Persistence
Clearing the cache and restarting the server
Using mid tier with third-party load balancers
Disabling BMC Remedy Mid Tier prefetch

Prefetch loads forms into memory based on a somewhat arbitrary list of forms configured in the
prefetchConfig.xml file by the system administrator. Forms and other cache objects end up in
memory that might not ever be accessed by end users. This can waste valuable memory space.
Use the following steps to disable Prefetch.
Page 588 of 4705
Home
1. In Mid Tier Configuration Tool, click Cache Settings.

2. Scroll down to the Prefetch Configuration text box.
3. Remove the contents of the prefetchConfig.xml file.
4. Add the following content:

5. Click Save Changes.
Activating Perform Check

Sync Cache eliminates the need for administrators to flush the entire mid-tier cache after a form,
active link, menu, or other definition change on BMC Remedy AR System server. When this feature
is activated, the mid tier cache is automatically synchronized with the changed objects. The check
is performed at the interval selected in the Definition Change Check Interval field.
1. In Mid Tier Configuration Tool, click Cache Settings.
2. On the Cache Settings page, make sure that the Perform Check check box is selected.
This activates Sync Cache.
3. Use the Definition Change Check Intervaltext box to configure the time (in seconds)
interval for the sync to activate.
Note
An administrator can press the new Sync Cache button to have the changes
synchronized immediately.
The Sync Cache operation synchronizes any of the following objects, if the changed
timestamp on BMC Remedy AR System server is more recent than the cached item in the
mid-tier cache:
Forms
Active links
Containers (guides, applications, web services)
Menus (character menus)
Page 589 of 4705
Home
Because the performance hit is minimal, Sync Cache completely removes and rebuilds the
following cache items:
Group data
Role data
Image objects
Note
The Sync Cache option is not available in pre 7.5, patch 004 versions.
Activating Pre-Load
When the Pre-Load option is activated, the following items are loaded when the server is started (
or restarted):
Active links and menus in the AR System server, and all user facing forms (any form with an
associated active link)
All forms specified in the prefetchConfig.xml, if Prefetch is not disabled. It is not necessary
to keep Prefetch settings when Preload is being done, as most of the forms specific in
Prefetch will already be cached by the Preload process.
All usage history data
Note
The preload process starts after a 10 second delay.
1. Open the Mid Tier Configuration Tool and click AR Server.

2. Select the server to edit, and click Edit (If you are adding a server, click Add Server).
3. Select the Pre-Load check box next to the server name.
Page 590 of 4705
Home
3.
4. Click Save AR Server (or Add Server if adding a new server).
Enabling Cache Persistence

You can enable faster retrieval of forms when the server is restarted by activating the Enable
Cache Persistence option.
1. In the Mid Tier Configuration Tool, click Cache Settings.
2. Select the Enable Cache Persistence check box.
3. Click Save Changes.
Clearing the cache and restarting the server

Use the followings steps to clear the cache and restart the server after implementing the setting
changes in 66057.
1. Shutdown the JSP engine.
2. Remove the contents of the following mid tier directories:
cache
cachetemp
3. Start the JSP engine.
4. Allow Pre-Load to complete processing.
5.
Page 591 of 4705
Home
5. Allow end users access to the system.

Before moving to the next step, it is recommend to allow one to two days of normal system
usage. Patch 004 provides functionality to update the statistics file ( viewstats.dat) with the
following information about forms and views access requests.
6. After 1-2 days of usage, disable Pre-Load in mid-tier configuration tool by clearing the check
box next to the AR server name on the AR Server Settings page.
7. Stop the JSP engine.
8. Start the JSP engine.
With Prefetch and Pre-Load disabled mid-tier will on startup use it's statistics file to quickly
load up into memory from the disk cache only forms which users have really been accessing
. This will allow for the most efficient use of mid-tier's in memory cache and the best form
access performance for end users.
Using the mid tier with third-party load balancers

Remember the following tips when load balancing:
To have multiple instances of a mid-tier web application work correctly in a load-balanced
environment, configure the load balancer so that the mid-tier instance of the user's first
HTTP servlet request is routed to the server that maintains affinity (stickiness) the
connection for the life of a session. "Session affinity" in this context refers to how requests
from the same client (in a cluster of servers) are always routed back to the same server,
eliminating the need to replicate session data such as HttpSession.
On the JSP/Servlet engine, enable cookie-based session tracking (the default), as opposed
to tracking by URL re-writing, which the mid tier does not support.
The mid tier does not support failover. Failover to a backup mid tier invalidates the user's
HTTP session on the failed mid tier. (Failover is not transparent to the user. They would see
a 9201 "Session timeout or invalid" error in their browsers and would need to log in again.)
Note
While BMC Remedy AR System supports the use of load balancers, BMC does not test or
recommend a specific third-party load balancer. BMC supports BMC Remedy AR System
within the environment, but not the configuration or debugging of a load balancer itself
beyond generic interaction expectations of BMC Remedy AR System with any load
balancer.
Actions that affect mid tier caching

The following actions will affect an object cache or re-cache in the event of a flush, cache, sync
cache or Definition change:
Add a user
Page 592 of 4705
Home
Modify a user
Delete a user
Add a group
Remove a group
Remove a group from the Group List in the User form
Add a user to a group
Remove a user from a group
Add a computed group
Add a group to a computed group
Remove a group from a computed group
Add a user to a group that is part of a computed group
Remove a user from a group that is part of a computed group
Create, modify, or delete an application
Create, modify, or delete an active link
Create, modify, or delete an active link guide
Create, modify, or delete an entry in the Group form (not every field must be affected)
Create, modify, or delete an entry in the Role Mapping form (not necessarily every field)
Create, modify, or delete a form
Create, modify, or delete a menu
Create, modify, or delete a packing list
Create, modify, or delete a view
Create, modify, or delete a web service
Actions in ITSM 7.0.00 applications that trigger caching

In large BMC Remedy AR System applications such as those in the BMC Remedy IT Service
Management Suite (BMC Remedy ITSM Suite), some actions performed through the BMC Remedy
AR System Administration Console might trigger a client cache load or an admin copy cache. The
following table lists ITSM actions that can trigger a client re-cache or an admin copy cache event.
Action
Client cache
Admin copy
load
cache
Creating, modifying, or deleting a non-support user
NO
NO
Creating, modifying, or deleting an organization
NO
NO
Creating, modifying, or deleting a company
NO
YES 1
Creating, modifying, or deleting an association between a company and one of these

items:
NO
NO
Approval mapping
Cause
Operational category
Product category
Site
Status reason
Page 593 of 4705
Home
Action
Client cache
load
Admin copy
cache
Creating, modifying, or deleting a resolution category
NO
NO
Adding a company to a support user's access restriction list
NO
NO
Deleting a company from a support user's access restriction list
NO
NO
Adding a support group to a support user's profile
NO 2
NO
Deleting a support group from a support user's profile
NO
NO
Adding an application permission to a support user's profile
NO
NO
Deleting an application permission from a support user's profile
NO
NO
Creating a service target
NO
YES
Deleting a service target
NO
YES
Adding or removing attributes in the BMC Atrium CMDB
YES 3
YES
1. Removes the group record associated with the company.

2. Support groups are not used as permission groups in structures. This action does not trigger a client cache load.
3. The form must be open.

The following topics provide detailed information about how to present application data and how to
interact with the user by using the BMC Remedy Mid Tier:
Configuring BMC Remedy Mid Tier as a shared service
Onboarding a new tenant
Offboarding a tenant
Configuring the mid tier through a firewall
Configuring mid tier memory
Accessing the Mid Tier Configuration Tool
Configuring the Change Password page
Configuring the Overview page
Configuring the General Settings page
Setting pagination properties
Configuring the AR Server Settings page
Configuring the Cache Settings page
Configuring the Report Settings page
Configuring the Web Service Settings page
Configuring the Connection Settings page
Configuring a mid tier to launch a browser in a different mid tier
Settings in the config.properties file
Setting up a cluster with multiple tenants
Page 594 of 4705
Home
Configuring BMC Remedy Mid Tier as a shared service

This topic provides the configuration steps for BMC Remedy Mid Tier as a shared service so that
the multitenant mid tier can serve requests from multiple customers.
Note
Before you perform the configuration steps for BMC Remedy Mid Tier as a shared service
:
Set up the enterprise centralized configuration server or servers.
Create a BMC Remedy Mid Tier cluster.
Install tenants or upgrade the platform components for the existing tenants.
To configure the mid tier as a shared service

Step
Action
Additional information
Add the first tenant
Onboard a new tenant on a BMC Remedy Mid Tier in the cluster. Configure the ECCS and provide
to the cluster by
onboarding a new
the Cluster Identifier, add the tenant AR server and edit the tenant specific properties for the BMC
Remedy Mid Tier . For all other BMC Remedy Mid Tiers in the cluster, only configure the ECCS and
tenant on a BMC
Remedy Mid Tier
provide the Cluster Identifier that is the same as for the first BMC Remedy Mid Tier. The Cluster
Identifier for the cluster should be unique.
Create a good
cache and back up
the Mid Tier cache
A copy of the cache is used to restore the cache if it gets corrupted.
(Optional)
Perform this step if you have installed BMC Atrium Single Sign-On as a High Availability (HA) cluster
environment for multitenancy support.
Configure BMC
Atrium Single
Sign-On for tenant
Configure BMC
Service
Management
Process Model for
a tenant
Perform the BMC Service Management Process Model (SMPM) configuration procedures.
Configuring the
load balancer
Configure the load balancer to ensure that the user requests for the new tenant are diverted to this
cluster. Test the cluster and provide access to the new tenant.
Add the remaining

tenants
Add the remaining tenants to the cluster one by one by following steps 4 through 8.
(Optional) Add (n+

1)th BMC Remedy
Mid Tier to the
cluster
If required, add an extra BMC Remedy Mid Tier to the cluster.
Page 595 of 4705
Home
Step
Action
Additional information
(Optional)
Offboarding a
tenant on a BMC
Remedy Mid Tier
cluster
If a tenant needs to be moved from a cluster or is unsubscribed from the environment, offboard the
tenant.
(Optional) Set up
Openfire chat
server
If required, configure the tenant server to work with the chat server.
Related topics
Guidelines for BMC Remedy deployment architect
Glossary

To ensure seamless failover and fast response time in the BMC Remedy environment, the
deployment architect performs the following actions:
Lays down the deployment strategy and provides instructions to the BMC Remedy
administrator to implement the deployment strategy. See the following figure for a sample
deployment strategy.
Note
This diagram is only representative and does not indicate the actual number of
tenants or mid tiers in any cluster.
Page 596 of 4705
Home
Decides how many clusters to create to support the existing Remedy customers based on
the benchmarking done for the RoD environment
Decides which mid tiers to include in the cluster based on the following guidelines:
Each computer hosting a mid tier must have the same hardware capacity (for
example, four CPUs at 2.0 GHz with 8 GB RAM and a 120-GB hard disk drive.
Each computer must have only one Tomcat instance and only one mid tier installed
within Tomcat.
If there are different subdomains or isolated networks, all computers in a cluster must
be a part of the same subdomain or isolated network to ensure optimal performance.
Decides which tenants must be added to the same mid tier in a cluster based on the
following guidelines:
The total number of concurrent users across all tenants added to a given mid tier
cluster must be less than or equal to 2,500.
For a symmetric configuration with three backups, a single mid tier instance does not
scale beyond 800 concurrent users. Remember these numbers while adding a tenant
to a given mid tier.
To take full advantage of cache objects comparison and sharing, all tenants in a
single mid tier must have the same number of languages. For example, if all tenants
in a mid tier have views only in English in all BMC Remedy IT Service Management
and BMC Service Request Management forms, maximum sharing of cache objects
across the tenants is achieved.
Combine all the tenants that have the same version. For example, add all tenants that
have BMC Remedy AR System 7604 SP2 to a single mid tier cluster.
Combine all tenants that have minimum customizations.
Page 597 of 4705
Home
Decides the rules for the load balancer that are in line with the deployment strategy. For
example, sticky session should always be used, but routing the requests to the appropriate
clusters or mid tier must be based on which tenant is supported by which mid tier. Such rules
must be defined when a decision on the final cluster and tenant deployment is made.
Defines the necessary rule changes for the n+1 scenario (that is, while temporarily adding a
mid tier to or removing one from a cluster)
Identifies which mid tiers to add to a cluster
Assigns a unique cluster ID for each mid tier added to a cluster
Designates an AR System server as the Centralized Configuration Server (CCS)
Decides whether a dedicated cluster is required for a large Tier-1 tenant. Typically, tenants
should not be used across clusters. A large tenant (Tier-1) can use a dedicated cluster for
service.
Related topics
About Cluster ID
Tomcat cluster architecture
Configuring a cluster
Centralized configuration for the mid tier
f5 load balancer sample configuration
Guidelines for the BMC Remedy Administrator

As a BMC Remedy Administrator, follow these guidelines to ensure smooth functioning and
maintenance of the Remedy OnDemand environment:
Install and upgrade BMC Remedy Mid Tier to the latest version.
Install BMC Atrium Single Sign-On.
Based on the deployment strategy, configure a Tomcat cluster.
Install and configure Centralized Configuration server. For information, see Centralized
configuration and Centralized configuration for mid tier.
Decide on and adhere to a naming convention for cluster IDs.
Onboard a tenant.
Add a tenant.
Configure tenant-specific properties.
Preload the cache.
Configure a load balancer.
Shut down the mid tier and back up the good copy of the cache. For information, see
Backing up mid tier cache.
Keep the setup ready to deploy an additional mid tier to the cluster on the fly. For information
, see Adding an extra mid tier to a cluster .
Enable the tenant console from the web.xml file. For information, see Enabling and
disabling multi-tenancy support.
Page 598 of 4705
Home
Add a realm for the tenant to access the Tenant Console. For information, see Adding or
deleting realms for multi-tenancy support.
Add users to the BMCSaaSAdmin group for providing tenant administrator privileges. For
information, see Managing the Tenant Console.
Tomcat cluster architecture

For the Tomcat cluster, you configure two nodes as part of one cluster. Deploy each node on a
separate virtual machine and install one mid tier on each node. Use the symmetric configuration in
which both mid tiers use the same AR System server, both use preloaded cache, and both have
the exact copies of the cache after preload. Configure the load balancer to send requests of any
client to any of the mid tiers and ensure that the sticky session behavior is set to ON.
For more information about configuring a Tomcat cluster, see Configuring a cluster.
When a user logs on to a node, in-memory session replication happens in real time.
The following diagram shows that Request 1 with Session X and Request 2 with Session Y are
handled by the load balancer. Assume that Request 1 is served by Node 1 and Request 2 is served
by Node 2. Even so, both nodes will have information about both the sessions, that is, Session X
and Session Y are part of session replication. Either node can pick up the other session seamlessly
if the other node crashes. A user does not have to log on again even if the serving node is down.
This session is picked up immediately by the second node.
Related topic
Page 599 of 4705
Home
Ensure seamless failover by configuring the mid tier on an Apache Tomcat cluster. To add the mid
tier in a Tomcat cluster, install mid tiers on different virtual computers and configure the cluster with
the following procedure.
1. Stop Tomcat.
2. Open the arsys.xml file located in the TomcatInstallationFolder\conf\Catalina\localhost
folder in a text editor, and replace the <Manager> tag with the following XML:
<Manager className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false"
notifyListenersOnReplication="true" />
3. Open the server.xml file located in the TomcatInstallationFolder\conf folder in a text editor
and make the following changes:
Locate the <Engine> tag and add the jvmRoute attribute.
Use Node1 for the first node, Node2 for the second, and so on.
<Engine name="Catalina" defaultHost="localhost" jvmRoute="Node1
">
Copy the <Cluster> tag information from the attached file and paste it after the <
Engine> tag in your server.xml file. You can download the sample server.xml file.
<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="8">
<Manager className="org.apache.catalina.ha.session.DeltaManager"
notifyListenersOnReplication="true"/>
<Channel className="org.apache.catalina.tribes.group.GroupChannel">
<Membership className="org.apache.catalina.tribes.
membership.McastService"
address="<ipAddress>"
port="45570"
frequency="500"
dropTime="3000"/>
<Receiver className="org.apache.catalina.tribes.transport.
nio.NioReceiver"
address="auto"
port="4000"
autoBind="100"
selectorTimeout="5000"
maxThreads="6"/>
<Sender className="org.apache.catalina.tribes.transport.
ReplicationTransmitter">
<Transport className="org.apache.catalina.tribes.transport.
nio.PooledParallelSender"/>
</Sender>
<Interceptor className="org.apache.catalina.tribes.group.
Page 600 of 4705
Home
interceptors.TcpFailureDetector"/>
<Interceptor className="org.apache.catalina.tribes.group.
interceptors.MessageDispatch15Interceptor"/>
</Channel>
<Valve className="org.apache.catalina.ha.tcp.ReplicationValve"
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*
\.txt|.*\.jsp|.*\.swf|.*BackChannel/*|.*./resources/.*|.*./sharedresources/
.*|.*./plugins/.*|.*./pluginsignal/.*|.*./imagepool/.*"
statistics="false" />
<Valve className="org.apache.catalina.ha.session.JvmRouteBinderValve"/>
<Deployer className="org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>
<ClusterListener className="org.apache.catalina.ha.session.
JvmRouteSessionIDBinderListener"/>
<ClusterListener className="org.apache.catalina.ha.session.
ClusterSessionListener"/>
</Cluster>
Note
The default value for the <ipAddress> variable is 228.0.0.4. This IP
address and port number defines a unique cluster. However, for each
member of a cluster, ensure that they have the same multicast IP address
and port number.
4. Enter the multicast IP address of the host on which you want the session replication to take
place in the Address value instead of auto. For example, in the <Receiver> tag, modify
address="auto" to address="172.x.x.x". For more information, see FAQ about
cluster configuration.
5. (Optional) To increase the cluster logging, change the log level to FINE for the following file
handlers in the logging.properties file located in the TomcatInstallationFolder/conf folder:
5cluster.org.apache.juli.FileHandler and 6cluster.org.apache.juli.FileHandler.
5cluster.org.apache.juli.FileHandler.level = INFO
5cluster.org.apache.juli.FileHandler.directory = ${catalina.base}/logs
5cluster.org.apache.juli.FileHandler.prefix = cluster.
6cluster.org.apache.juli.FileHandler.prefix = ha.
org.apache.catalina.tribes.MESSAGES.level = INFO
org.apache.catalina.tribes.MESSAGES.handlers =
5cluster.org.apache.juli.FileHandler
Page 601 of 4705
Home
org.apache.catalina.tribes.level = INFO
org.apache.catalina.tribes.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.ha.level = INFO
org.apache.catalina.ha.handlers = 6cluster.org.apache.juli.FileHandler
6. Restart Tomcat.
7. Verify whether the node is added to the cluster:
a. Open the ha.date.log file located at /opt/apache/tomcat7.0/logs for Linux and <C:\
Program Files\Apache Software Foundation\Tomcat7.0\logs> for Windows.
b. Search for memberAdded entry. If you have added four mid tiers to the cluster, you
should see three memberAdded entries and their IP addresses in the file for the other
three members. Ensure that the IP address does not represent a localhost.
Note
To add an extra mid tier to the cluster , perform the same configurations on the extra (n+1)
mid tier.
To access the mid tier configuration URL, BMC recommends that you use the HTTP URL in the
following format:
http://mtMachineName:8080/arsys/shared/config/config.jsp
Recommendations
BMC recommends that to improve application scalability, increase the File Descriptor limit in mid
tiers running in a cluster. If you have a cluster of two mid tiers with 12 tenants, which is serving
3600 users, set the File Descriptor limit to 35,000 .
Note
Average load per tenant is considered as 300 users.
To set the File Descriptor limit, perform the following steps:

Edit the /etc/security/limits.conf file and add the following:
root soft nofile 35000
Edit the /etc/bashrc file and set the unlimit value as follows:
if [ "$EUID" = "0" ]; then

ulimit -n 35000
Page 602 of 4705
Home
fi
Edit the /etc/sysctl.conf file and increase the File Descriptor limit for the system as follows:
fs.file-max = 210000
Note
Ensure that you set the system-wide limit of File Descriptors to approximately 6 times of
the per process limit set in the limits.conf file.
Refer to the following table for guidance on deciding the File Descriptor limit:
S
No
Component
Variable
Description
Tomcat
connections
maxThreads setting in Tomcat HTTP

Connector
maxThreads defines the maximum connections used

by Tomcat when
BIO Connector is used.
Tomcat NIO
Receivers
Default setting is 6
NIO Receivers for Session Replications.
Tomcat and Mid

Tier Class
Loaders
Estimate is 1200
Class loader for JAR files loaded by Tomcat. This

includes JARs in Mid Tier distribution, configured
Third-party JARs, and DVF plug-ins.
Mid Tier
properties files
1 + 1 * Number of Tenants
1 for global configuration and 1 per tenant
Mid Tier Cache

files
27 x 2 = 54
27 categories x 2 files per category. Data files are

always open.
Index files are read into Memory at startup and closed
and later written to
during Mid Tier shutdown.
Mid Tier Cache

lock file
Single file for Cache lock status
Java API RPC

connections to
AR Server
arsystem.pooling_max_connections_per_server
from Mid Tier Configuration * Number of
Tenants
Configured by
arsystem.pooling_max_connections_per_server
setting
in Mid Tier Configuration
Java API JMS

Connections for
CCS
1 + 1 * Number of Tenants
1 for ECCS and 1 per Tenant
Attachments and
Reports
Estimate is 20% * Maximum Concurrent Users

on the Mid-Tier Node
Attachment files and report files created by MT on

Disk
10
SSO Agent Files
A single Configuration file is used by the SSO Agent

which is queried from the SSO Server
11
Page 603 of 4705
Home
S
No
12
Component
Variable
Description
SSO Agent
Connections to
SSO Server
maxThreads setting in Tomcat HTTP

Connector
SSO Agent opens a URLConnection to SSO Server

when it logs in a
User or validates SSO Token with SSO Server
Safety Factor
25% * Sum of (#1 to #11)
Total
Sum of #1 to #12 rounded up to nearest 5000 on 6th

higher side
Related topics
FAQs about cluster configuration
Enabling logging
FAQ about cluster configuration

This topic provides answers to frequently asked questions about Tomcat cluster configuration.
How do I configure a Tomcat cluster if I have multiple network interfaces?
You have the following options:
Edit the server.xml file located in the TomcatInstallationFolder\conf folder and in the
Receiver tag, for the address value, instead of auto, enter the IP address of the network
interface card to which you want the session replication to take place.
For example, if you have two network interface cards, eth1 with 10.x.x.x as the IP address and eth2
with 172.x.x.x as the IP address, and if you want the session replication to happen on eth2, you
must set the address value to 172.x.x.x.
Original address value in the Receiver tag:
<Receiver className="org.apache.catalina.tribes.transport.nio.NioReceiver"
address="auto"
port="4000"
autoBind="100"
maxThreads="6"/>
New address value in the Receiver tag:
Page 604 of 4705
Home
address="172.x.x.x"
port="4000"
autoBind="100"
maxThreads="6"/>
For information about clustering and session replication, see the Apache Tomcat documentation at
http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html .
Disable the network interface that you do not intend to use. For example, if you want to
disable eth1, use any one of the following commands at the command prompt:
ifconfig eth1 down
ifdown eth1
Note
Verify your etc/hosts file. Remove any bad entries that are present.
I see the IP address of the local host against the memberAdded entry in the cluster log. What do I
do?
Edit the server.xml file located in the TomcatInstallationFolder\conf folder and in the
Receiver tag, for the address value, instead of auto, enter the IP address of the host to
which you want the session replication to take place.
Original address value in the Receiver tag:
address="auto"
port="4000"
autoBind="100"
maxThreads="6"/>
New address value in the Receiver tag:
address="172.x.x.x"
port="4000"
autoBind="100"
maxThreads="6"/>
Page 605 of 4705
Home
For information about clustering and session replication, see the Apache Tomcat documentation at
http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html .
Adding an extra mid tier to a cluster

When an increase in demand requires extra capacity in a cluster, you can add an extra mid tier to
the cluster. The newly added mid tier must seamlessly start serving requests and share the load
along with other mid tiers in the cluster. Suppose that you have four mid tiers and eight AR System
servers operating in a cluster, serving requests from 2,400 users. If you find that each mid tier is
serving more than 75 percent of its capacity and you expect the load to further increase, you can
add a fifth mid tier and distribute the load equally among all the mid tiers.
Note
This procedure also applies when a mid tier in a cluster goes down and the BMC Remedy
AR System administrator brings it up.
Before you begin

To add the extra (n+1) mid tier
Before you begin

Plan your deployment strategy. For example, you might have to decide whether to deploy n+
1 or n+2 mid tiers to the cluster.
Ensure that you have a separate computer. If you are deploying n+2 mid tiers, ensure that
you have two computers available.
Ensure that the computers have the same configuration as that of other mid tiers in the
cluster in terms of memory, CPU usage, disk space, and so on.
Ensure that the computers have the same cluster configuration.
Notes
Ensure that the extra mid tier is already set up in the cluster but is not running, and
that you have deleted the midTierInstallationDirectory/cache folder before
starting the mid tier.
To avoid the extra time required to copy the cache folder, ensure that you already have a "
good copy" of the preloaded cache in the n+1 mid tier (for example, in the /opt/
Preload_Cache folder). Ensure that you store the good copy of the cache on a local drive
and not on a shared drive, which can delay copying the cache folder.
Add the cache directory path to the arsystem.ehcache.midTierBackupCacheDir
property in the config.properties file of the n+1 mid tier. For example:
Page 606 of 4705
Home
arsystem.ehcache.midTierBackupCacheDir = /opt/Preload_Cache
Note
If you are using a Centralized Configuration Server (CCS), ensure that this property
(Cache Backup Directory) is set correctly from the Cache Settings page from any of
the mid tiers in the cluster. Ensure the availability of the good copy of the cache in
this folder on all mid tiers. For more information, see Backing up the mid tier cache.
If you are using Centralized Configuration Server, copy the ccs.properties file in the
midTierInstallationDirectory/WEB-INF/classes folder from other mid tier.
To add the extra (n+1) mid tier

1. Start the n+1 mid tier:
a. Start the mid tier to connect to the CCS server by using ccs.properties and refresh
the local copy of config.properties. This action also copies the cache backup from
the backup directory and starts using it automatically.
b. After the n+1 mid tier is started, verify the cache folder located in the
midTierInstallationDirectory/cache folder of the n+1 mid tier. The size of this cache
folder must be same as the good cache copy stored in the /opt/Preload_Cache
folder.
2. Ensure that the n+1 mid tier is added as a node to the appropriate f5 load balancer pool.
Otherwise, f5 does not balance the load across the n+1 mid tier.
3. Verify whether the newly added mid tier is serving requests by:
Looking at the status of the relevant node in f5 load balancer
Reviewing the number of views generated in the Cache Advanced page of the newly
added mid tier (For example: http://localhost:portnumber/arsys/shared/config/
config_cache_adv.jsp)
The newly added mid tier can now handle all requests seamlessly without causing delays and
performance issues.
Centralized configuration for the mid tier

Centralized configuration refers to storing of configuration form data at a common location that can
be accessed by other computers. Centralized configuration simplifies the management of
configuration data and sharing of configuration settings across servers. For more information, see
Centralized configuration.
You must configure an AR System server to act as a Centralized Configuration Server (CCS). The
Centralized Configuration Server is an AR System server that does not have any applications or
any end user interactions. Centralized Configuration Server needs limited resources in terms of
CPU and RAM.
Page 607 of 4705
Home
The Centralized Configuration Server ensures consistency by communicating changes to the global
properties across all the mid tiers in a cluster. If a configuration server is defined while adding a
tenant, that tenant configuration server maintains a copy of the tenant-specific settings. When a
tenant-specific property is modified on one mid tier, the Tenant Configuration Server automatically
sends the notification to other mid tiers that have the same tenant added, so that these
configuration changes are also synchronized by each mid tier in the same cluster.
Suppose that you have 10 mid tiers in a cluster. Before centralized configuration, each tenant was
managed independently. To change a configuration setting, you had to make the same change for
each tenant in the cluster.
Figure 1 - Centralized Configuration
With centralized configuration, because all settings are stored in forms, you can change the
settings for multiple tenants in a cluster at one time. Centralized configuration enables you to share
configuration settings across all tenants in a cluster.
Figure 2: Change notification
Note
If you are using a version of AR System server earlier than 20.14.01 and cannot set
Centralized Configuration Server and Tenant Configuration Server, you must manually
update the global and tenant-specific settings for all the mid tiers in the cluster. Use the
Page 608 of 4705
Home
Mid Tier Configuration Tool to update the settings. If you do not have access to the Mid
Tier Configuration Tool, edit the config.properties and tenants/config_tenantName.
properties files.
To set Centralized Configuration Server properties

1. Open the BMC Remedy Mid Tier Configuration Tool from the URL: http://hostname:port/
arsys/shared/config/config.jsp.
2. Click Central Config Settings.
3. In the Central Config Settings page, enter the following information:
a. In Server Name, enter the name of the AR System server that is the designated as
the Centralized Configuration Server in the cluster.
b. In Cluster ID, enter the unique cluster ID of the cluster to which the mid tier belongs.
c. Enter the administrator password.
d. (Optional) Enter the port number and RPC number.
4. Click Save.
Note
You can configure an AR System server as a Centralized Configuration Server or a
Tenant Configuration Server only if the AR System server version supports
centralized configuration and has the configuration-related system forms and
notification capability.
5. Click Publish to create or update global properties from the config.properties file to
Centralized Configuration Server.
Note
After you publish, properties that are deleted from the config.properties file are
not deleted from the Centralized Configuration Server. However, deleted properties
are reflected in the current mid tier memory immediately and are restored when the
mid tier is restarted. Click Restore to restore global settings from the Centralized
Configuration Server to the config.properties file. Exercise caution when deleting
any property directly from the Centralized Configuration Server forms.
6. Click Restore to update the global settings from Centralized Configuration Server to the
Note
Page 609 of 4705
Home
The properties that are not available for editing through the Centralized Configuration
Settings page must be edited directly in the config.properties file.
A ccs.properties file is added to the midTierInstallationDirectory\WEB-INF\classes folder and

contains the following information:
arsystem.cluster.idA cluster identifier. All mid tier instances in the same cluster share the
cluster identifier.
arsystem.ccs.passwordThe encrypted mid tier service password for the Centralized
Configuration Server
arsystem.ccs.hostThe name of the Centralized Configuration Server
arsystem.ccs.portThe port number of the Centralized Configuration Server
The mid tier uses the ccs.properties file for connecting to the Centralized Configuration Server on
startup and for updating its configuration files for global settings ( config.properties) and
tenant-specific settings (config.tenantName.properties).
Note
If you have configured a valid Centralized Configuration Server or Tenant Configuration
Server, refrain from making any changes directly to the properties files. These changes
might be overwritten during the next mid tier restart. Make all necessary changes in the
AR System Configuration Component Setting form on the Centralized Configuration
Server or Tenant Configuration Server, using the appropriate cluster ID or tenant name.
The changes will take effect in all concerned mid tier instances and corresponding
properties files by means of a periodic notification (typically after 30 seconds). However,
changes to some of the properties, such as Ehcache settings and number of threads,
require the mid tier to be restarted. For more information, see Centralized configuration.
Configuring the mid tier for multitenancy

To configure the mid tier for multitenancy, first add tenants to the mid tier and then configure the
tenant-specific properties. The following topics are provided:
To add a tenant
To edit tenant-specific properties
To delete a tenant
Mapping a tenant to multiple AR System servers
Configuring global settings for all tenants
Identifying whether the mid tier is in multitenant mode
Page 610 of 4705
Home
To add a tenant
1. Open the BMC Remedy Mid Tier Configuration Tool from the URL http://hostname:
portnumber/arsys/shared/config/config.jsp
2. Click the Tenant Settings link.
3. On the Tenant Settings page, click Add Tenant.
4. In the Add New Tenant page, enter the following information.

a. In the Tenant Name field, enter the name of the tenant (for example, Tenant1).
b. In the Virtual Host Name field, enter the virtual name of the host (for example,
Tenant1.bmc.com).
Note
You must map this virtual host name with the pool name in the f5 load
balancer. For more information, see f5 rules.
c. In the Web Reports Base URL field, enter the base URL (for example, https://
Tenant1.onbmc.com:8080/).
d. (Optional) From the Tenant Configuration Server list, select an AR System server
as your configuration server.
This list is populated based on the AR System servers that are added to the mid tier.
For more information, see Adding or deleting a server.
e. (Optional) Click Browse to specify the location of the config.properties file.
By default, the existing config.properties file is located in the
midTierInstallationDirectory\WEB-INF\classes folder.
f. (Optional) Clear the Also add to tenant's server list check box.
The configuration server is not added as a server to the tenant. By default, this check
box is selected.
5. Click Save.
Page 611 of 4705
Home
Note
Ensure that the virtual host is accessible to the users by making appropriate changes in
DNS or load balancer settings.
The tenant is added to the mid tier. Each tenant that is added to the mid tier has a corresponding
tenant-specific property file. For example, if you add a tenant named Tenant1, a properties file
called config.Tenant1.properties is added to the midTierInstallationDirectory\WEB-INF\classes
\tenants\ folder.
Note
If you add a tenant with the name of a tenant that was deleted or offboarded from any mid
tier previously, a warning message is displayed. When you delete a tenant, the tenant is
deleted but the tenant configuration is not deleted from the Centralized Configuration
forms. For more information, see Centralized configuration for the mid tier .
To edit tenant-specific properties

1. On the Tenant Settings page, select a tenant that you want to edit and click Edit.
2. On the Edit Tenant page, edit the tenant-specific properties that you want to change for this
tenant.
3. Click Save Tenant.
Page 612 of 4705
Home
To delete a tenant
1. Open the BMC Remedy Mid Tier Configuration Tool from the http://hostname:portnumber/
arsys/shared/config/config.jsp URL.
2. Click the Tenant Settings link.
3. From the Tenant Settings page, select the check boxes in the Delete/Edit column for one or
more tenants.
4. Click Delete.
Note
Use caution when deleting a tenant. Ensure that the users who are logged on using the
tenant's virtual URL stop accessing the mid tier; otherwise they might see unexpected
behavior.
Mapping a tenant to multiple AR System servers

You can add multiple AR System servers to a tenant; however, only one AR System server will be
the primary server used for authenticating, setting preferences, the home page, and the data
visualization module. For more information, see Adding or deleting a server.
Note
A single AR System server cannot be mapped to more than one tenant.
Configuring global settings for all tenants

You can configure global configuration settings for tenants such as the cache settings, report
settings, and log settings. For more information, see Configuring Mid Tier.
Identifying whether the mid tier is in multitenant mode

When you access mid tier using the virtual host name, the mid tier is in the multitenant mode. For
example, if your URL starts with http://Tenant1.onbmc.com/arsys/forms/ , you are using a mid tier
that is in multitenant mode. If your URL starts with http://hostName/arsys/forms/, you are
accessing a mid tier that is not in the multitenant mode.
For a mid tier to be accessed in multitenant mode, ensure that at least one tenant with a virtual host
name is added to the mid tier.
Note
Page 613 of 4705
Home
The Mid Tier Configuration Tool is accessed only by the BMC Remedy AR System
administrator using the actual mid tier host name rather than the virtual host name.
Enabling logging
To debug issues with session replication or to verify whether failover is taking place in the Tomcat
cluster, you must edit the logging.properties file located in the TomcatInstallationFolder/conf
directory.
Note
The logging.properties file is available as an attachment to this topic.
Edit the attached logging.properties file to add new file handlers and set the debug log level to
Info. For example, create two new file handlers: 5cluster.org.apache.juli.FileHandler and
6cluster.org.apache.juli.FileHandler, as shown in the following code. Add the code to the
logging.properties file.
5cluster.org.apache.juli.FileHandler.prefix = cluster.
6cluster.org.apache.juli.FileHandler.prefix = ha.
org.apache.catalina.tribes.MESSAGES.level = INFO
org.apache.catalina.tribes.MESSAGES.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.tribes.level = INFO
org.apache.catalina.tribes.handlers = 5cluster.org.apache.juli.FileHandler
org.apache.catalina.ha.level = INFO
org.apache.catalina.ha.handlers = 6cluster.org.apache.juli.FileHandler
Note
When you install Tomcat through the latest version of BMC Remedy AR System, the
cluster log settings are already added by the installer. However, you can change the log
level whenever required.
Page 614 of 4705
Home
Glossary
load balancer
A transparent network device that distributes the traffic from multiple tenants to several tenant AR
System servers, preventing BMC Remedy AR System servers from becoming overloaded.
Distributing workload among several BMC Remedy AR System servers leads to performance
benefits and cost savings.
Mid Tier cluster

A group of Tomcat servers with the mid tier application running on them. The cluster acts as a
single system and provides high-availability, failover, and load balancing capabilities.
multitenancy
Refers to the ability of a single instance of an application running on a server to serve multiple
customers. Customers, in this case, are called the tenants. In the multitenant environment, each
tenant is given the provision to customize the application according to their requirements.
server group
Multiple servers that are connected to each other and operate together; they share the work load
and also balance the load. One server in the server group is usually designated as the primary
server, which performs administrative activities and others are designated as secondary servers.
shared service
The consolidation of business operations that are used by multiple parts of the same organization.
tenant
A customer subscribing to the services provided in the SAAS model.
About Cluster ID
A cluster ID is a unique identification given to a cluster operating in the RoD environmen t. All mid
tiers within a cluster share a unique cluster ID. When you configure the Centralized Configuration
Server settings for each mid tier, ensure that the mid tiers within a cluster are configured with the
same cluster ID. Having a cluster identified by a unique cluster ID is essential because Centralized
Configuration Server can notify changes to the global properties across all the mid tiers within a
cluster. For more information about configuring the cluster ID for each mid tier, see Centralized
configuration for the mid tier.
You must decide a unique cluster ID for each cluster. For example, for Cluster1, you can add
Cluster1 as the cluster ID, for Cluster2, add Cluster2, and so on.
The following diagram illustrates the use of a cluster ID.
Page 615 of 4705
Home
Related topics
Configuring SMPM for a tenant

To configure BMC Service Management Process Model (SMPM) for a tenant, perform the following
steps:
1. Log on to the tenant.
2. Navigate to the Integration Configuration form.
3. Open the SYS:Integration Management form or perform the following steps:
Select Application Flyout > Administrator Console > Application Administrator
Console.
On the Application Administration Console page, select Custom Configuration
tab.
Navigate to Foundation > Advanced Option > System Configuration Settings >
Integration Management and click Open.
4. Perform a search to list all the records (for example: Integration Application = %).
5.
Page 616 of 4705
Home
5. For the following records, update the entry with the following details and then save each
entry.
Host = /
Port = (Empty)
Status = Enabled

This topic explains how to onboard a new tenant in your existing multitenant mid tier setup.
Before you begin
To onboard a tenant on the first mid tier in the cluster
To onboard a tenant on the other mid tiers in the cluster
Related topics
Before you begin

Ensure that you have n mid tiers that are:
Set up as a Tomcat cluster (see Configuring a cluster)
Page 617 of 4705
Home
Configured for SSO (see Configuring BMC Atrium SSO with mid tier deployed as a shared
service)
To onboard a tenant on the first mid tier in the cluster

1. Log on to BMC Remedy Mid Tier Configuration Tool:
If the mid tier is installed on the local computer using the default context path, enter
http://localHost/arsys/shared/config/config.jsp in your browser.
If the mid tier is not installed on the local computer, open a browser and enter the
URL in the following format:
http://hostName:portNumber/contextPath/shared/config/config.jsp
hostName is the name of the host computer for the mid tier.
portNumber is an optional port number; it is required if the web server is not
using the default port (port 80).
contextPath is the path to the location of the mid tier in the Oracle JSP engine (
arsys, by default).
2. When the Login page appears, enter the logon password for the Mid Tier Configuration Tool.
If you have not changed the password from the default, enter arsystem.
3. Click the Tenant Onboarding link.
4. (Optional) In the Centralized Configuration Server Settings page, shown in the following
figure, configure the Centralized Configuration Server settings.
For more information, see Centralized configuration for the mid tier .
5. Click the Next step button or the Tenant AR Server tab.

The AR Server Settings page opens, as shown in the following figure:
Page 618 of 4705
Home
6. Add and configure an AR System server:

Ensure that the Pre-load check box is selected. If you do not select this check box,
the Preload button will not be available on the Cache Settings page.
Ensure that you enter the tenant virtual host name (for example, http://Tenant1.
onbmc.com/contextPath) in the Default Web Path and Email Notification Web Path
fields in the Advanced tab of the Server Information form. The values of these fields
are used in various BMC Remedy IT Service Management workflows; therefore, you
must enter the tenant-based URL in these fields so that customers receive the correct
URL. For information about the Default Web Path and Email Notification Web Path
fields, see Setting advanced security options using the Server Information form .
7. Click the Next step button or the Tenant Creation tab .
The Tenant Settings page opens, as shown in the following figure:
8. Add a new tenant with a name such as tenant1.

Ensure that the tenant name does not contain any special character.
9. (Optional) Select a tenant and click the Next Step button or the Tenant Configuration tab.
10. In the Edit Tenant page, make changes to tenant-specific properties.
11. Click the Preload New Tenant tab.
The Cache Settings page opens.
12. Click Preload for the tenant AR System server.
(The Preload button is not available if you did not select the Pre-load check box in the AR
Server Settings page in step 6.)
You will see that initially the status of the preload is shown as Not Running.
Page 619 of 4705
Home
Recommendation
BMC recommends that you perform preload when your system has a lesser load
and that you use the round-robin method to preload servers one at a time.
13. After the preload is completed, configure your load balancer to start sending requests to this
tenant using the virtual host name.
For example, the virtual host name of the tenant1 tenant can be http://tenant1.onbmc.com.
14. Verify whether the tenant is successfully added by logging on to the BMC Remedy IT
Service Management application, using the virtual host name of that tenant.
To onboard a tenant on the other mid tiers in the cluster

Perform the appropriate action:
If the Centralized Configuration Server is not configured, perform all the steps in To onboard
a tenant on the first mid tier in the cluster .
If the Centralized Configuration Server is configured, review all the steps in To onboard a
tenant on the first mid tier in the cluster and make changes, if required.
However, you must explicitly preload the tenant AR System server. For information, see
Setting up a cluster with multiple tenants .
Related topics
Setting up BMC Remedy Smart Reporting as a cluster and onboard tenant

To set up BMC Remedy Smart Reporting as a cluster (Tomcat only) perform the following steps:
Note
Before you configure the cluster, ensure that all the severs in cluster are in same time
zone and are in sync.
1. Perform one of the following:

If you are using a template, edit the JDBC URL in the /opt/bmc/ARReporting/
appserver/webapps/ROOT/WEB-INF/web.xml file to the reporting database host
name.
<init-param>
Page 620 of 4705
Home
<param-name>JDBCUrl<param-name><param-value>jdbc:jtds:sqlserver://clm-aus002889:1433/SmartReporting;instance=/windows</param-value>
</init-param>
Or
Install the BMC Remedy Smart Reporting on a node and copy the files to the
secondary servers.
2. On the web.xml file located at <SmartReportingInstallDir>/appserver/webapps/ROOT/
WEB-INF update the following:
a. Update and add the following:


<servlet>
<servlet-name>ClusterManagement</servlet-name>
<servlet-class>com.hof.mi.servlet.ClusterManagement</servlet-class>
<init-param>
<param-name>ClusterType</param-name>
<param-value>DYNAMIC</param-value>
</init-param>
<init-param>
<param-name>SerialiseWebserviceSessions</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>CheckSumRows</param-name>
</init-param>
<init-param>
<param-name>EncryptSessionId</param-name>
</init-param>
<init-param>
<param-name>EncryptSessionData</param-name>
</init-param>
<init-param>
<param-name>AutoTaskDelegation</param-name>
</init-param>
<load-on-startup>11</load-on-startup>
</servlet>
b. On the MIStartup Servlet block, update the following:
<init-param>
<param-name>DisableTaskScheduler</param-name>
<param-value>TRUE</param-value> </init-param>
c.
Page 621 of 4705
Home
c. Comment the following :
<servlet>
>
<servlet-name>SystemTaskManager</servlet-name>
<servlet-class>com.hof.servlet.SystemTaskManager</servlet-class
<load-on-startup>8</load-on-startup> </servlet>
d. Add <distributable/> tag
<web-app>
<distributable/>

<listener>
<listenerclass>com.hof.servlet.SysSessionListener</listener-class>
</listener>
3. Open the Tomcat sever.xml file and make the following changes:
a. Change the <Engine> tag <Engine name="Catalina" defaultHost="localhost" > to <
Engine name="Catalina" defaultHost="localhost" jvmRoute="node01">. Use Node1
for the first node, Node2 for the second, and so on.
b. Copy the following <Cluster> tag information and paste it after the <Engine> tag in
your server.xml file.
<Engine name="Catalina" defaultHost="localhost" jvmRoute="Node1">

<Cluster className="org.apache.catalina.ha.tcp.SimpleTcpCluster"
channelSendOptions="8">
<Manager className="
org.apache.catalina.ha.session.DeltaManager"
notifyListenersOnReplication="true"/>
<Channel className="
org.apache.catalina.tribes.group.GroupChannel">
<Membership className="
org.apache.catalina.tribes.membership.McastService"
address="<IpAddress>"
port="45570"
frequency="500"
dropTime="3000"/>
<Receiver className="
org.apache.catalina.tribes.transport.nio.NioReceiver"
address="<localIP>"
port="4000"
autoBind="100"
maxThreads="6"/>
<Sender className="
org.apache.catalina.tribes.transport.ReplicationTransmitter">
<Transport className="
org.apache.catalina.tribes.transport.nio.PooledParallelSender"/>
</Sender>
Page 622 of 4705
Home
<Interceptor className="
org.apache.catalina.tribes.group.interceptors.TcpFailureDetector"/>
<Interceptor className="
org.apache.catalina.tribes.group.interceptors.MessageDispatch15Interceptor"
/>
</Channel>
<Valve className="
org.apache.catalina.ha.tcp.ReplicationValve"
filter=".*\.gif|.*\.js|.*\.jpeg|.*\.jpg|.*\.png|.*\.htm|.*\.html|.*\.css|.*
\.txt|.*\.jsp|.*\.swf|.*BackChannel/*|.*./resources/.*|.*./sharedresources/
.*|.*./plugins/.*|.*./imagepool/.*" statistics="false" />
<Valve className="
org.apache.catalina.ha.session.JvmRouteBinderValve"/>
<Deployer className="
org.apache.catalina.ha.deploy.FarmWarDeployer"
tempDir="/tmp/war-temp/"
deployDir="/tmp/war-deploy/"
watchDir="/tmp/war-listen/"
watchEnabled="false"/>
<ClusterListener className="
org.apache.catalina.ha.session.JvmRouteSessionIDBinderListener"/>
<ClusterListener className="
org.apache.catalina.ha.session.ClusterSessionListener"/>
</Cluster>
Note
The default value for the <ipAddress> variable is 228.0.0.4. This IP
address and port number defines a unique cluster. However, for each
member of a cluster, ensure that they have the same multicast IP address
and port number.
4. Enter the multicast IP address of the host (on which you want the session replication to take
place) in the Address value instead of <localIP>.
5. Make the following changes to the <ReportingInstallDir>/appserver/conf/Catalina/
localhost /ROOT.xml file:
a. Delete the following:
<Manager className="org.apache.catalina.session.PersistentManager" debug="0

"
distributable="false" saveOnRestart="false">
<Store className="
org.apache.catalina.session.FileStore" />
</Manager>
b. Add the following:
Page 623 of 4705
b.
Home
<ReportingInstallDir>/appserver/conf/Catalina/localhost directory:<Manager
className="org.apache.catalina.ha.session.DeltaManager"
expireSessionsOnShutdown="false" notifyListenersOnReplication="true" />
When the cluster is set up, onboard the tenant. See Onboarding a new tenant
You can offboard a tenant from the multi-tenant mid tier setup for the following reasons:
A customer is unsubscribed from the environment
A tenant must be moved from one cluster to another
To offboard a tenant, you must first delete the tenant, then delete the tenant AR System server, and
then clean up the AR System server cache. Cleaning up the cache ensures that the resources are
made available for other tenants and that there is no contention of resources.
Before you begin

Delete a realm from BMC Atrium Single Sign-On (SSO).
Disable multitenancy support from BMC Atrium Single Sign-On (SSO).
To offboard a tenant
1. Log on to the Mid Tier Configuration Tool.
2. Click the Tenant Offboarding link.
The Tenant Settings page opens.
3. Select the tenant that you want to delete.
4. Click Delete.
5. Click the Next step button or the Tenant AR Server tab.
6. On the AR Server Settings page, select the server that you want to delete.
Tip
Page 624 of 4705
Home
Ensure that the tenant name and the tenant AR System server name are similar so
that you can easily identify which tenant was mapped to the AR System server.
This procedure assumes that the administrator remembers which tenant is mapped
to the tenant AR System server. - this is TBD
7. Click Delete.
8. Click the Next step button or the Cache Cleanup tab.
.
9. On the AR Server Cache Cleanup page, in the Action column, click Cleanup Cache for the
server whose cache you want to clean up.
Recommendation
Because cache cleanup is a resource-intensive operation, BMC recommends that
you perform it during off-peak hours. It can take hours to finish, especially when the
mid tier is serving multiple AR System servers.
10. After the cache cleanup is completed, click Remove From List to remove the AR System
server.
Notes
The Remove From List button appears only when the cache cleanup status is
Completed.
If multiple mid tiers are in the cluster, you must perform cache cleanup on each mid
tier.
Page 625 of 4705
Home
If you are removing the last server from the mid tier, you must flush the cache
instead of clicking the Remove From List button.
You cannot clean up the cache unless you delete the AR System server.
You cannot delete the AR System server unless you delete the tenant that is
mapped to the server.
The cleanup process might result in any one of the following states:
Not started
Starting
Running
Completed
Failed
Related topic

The following figure illustrates the typical connections required to connect web clients to a BMC
Remedy AR System server through the BMC Remedy Mid Tier:
Transmitting through a firewall
The following topics provide detailed information about internal and external firewalls:
Configuring the external firewall
Configuring the internal firewall
Note
Page 626 of 4705
Home
Firewall configurations vary from manufacturer to manufacturer. Ask the network and
security professionals at your company for more information. For information on the
cookies used by BMC Remedy Mid Tier, see Cookies used by BMC Remedy Mid Tier .
Configuring the external firewall

As shown in the Transmitting through a firewall figure, the web client connects to the BMC Remedy
Mid Tier server through a standard HTTP connection. If the web server (on the BMC Remedy Mid
Tier server) is configured on a certain port - the default for most web servers is 80 - then you would
need to open that port for HTTP on this firewall. The web client request would then use this port in
its requesting URL. For example, if your web server is configured on port 8080, you would use the
following example URL request: http://<webServer>:8080/arsys/home.
The firewall would need port 8080 open for HTTP. No mid-tier-specific configurations are needed
for this connection through the external firewall.
Configuring the internal firewall

The BMC Remedy Mid Tier server connects to the BMC Remedy AR System server using a TCP
connection. If there is a firewall between the BMC Remedy Mid Tier and the AR System server, you
must allow traffic through the firewall on the TCP port on which AR System listens.
To enable these connections through the firewall, you must configure the AR System server and
the BMC Remedy Mid Tier to communicate on the proper ports, as described in the following steps:
1. In the Ports and Queues tab of the AR System Administration: Server Information form, set
the BMC Remedy AR System server to use a specific TCP port. Because you are
configuring the mid tier to use a specific port, registering the server with portmapper is
optional.
For more information about the AR System Administration: Server Information form, see
2. Ask your network administrator to open the port on which the BMC Remedy AR System
server is listening on the internal firewall for TCP.
For more information about assigning a specific port number in the Server TCP/IP Port field
on the Ports and Queues tab, see Setting ports and RPC numbers.
3. In the Mid Tier Configuration Tool, select AR Server Settings, and then set the Port# field
to the BMC Remedy AR System configuration.
These settings allow the mid tier to connect to the BMC Remedy AR System server, using the port
specified.
Configuring mid tier memory

This topic describes the following memory-related issues for the BMC Remedy Mid Tier.
Allocating enough memory for your application and the mid tier
Page 627 of 4705
Home
Monitoring mid-tier memory use and performance in real time
Allocating enough memory for your application and the mid tier
If there is not enough memory allocated to your application server to run your BMC Remedy AR
System application on the BMC Remedy Mid Tier, the application server will produce
out-of-memory exceptions. (You can see this in the application server log file.)
To avoid out-of-memory exceptions

1. Shut down your application server.
2. Allocate enough memory to the application server.
3. Restart the application server.
4. If the Enable Cache Persistence check box is selected in the BMC Remedy Mid Tier
Configuration Tool, flush the cache.
For more information, see Configuring the Cache Settings page.
Monitoring mid-tier memory use and performance in real time

To monitor mid-tier memory use and performance in real time through a web server, such as
Tomcat, perform the following procedure. By default, real-time mid-tier monitoring is disabled.
To monitor mid-tier memory use and performance in real time in Tomcat

1. Add the following parameters to the Java Virtual Machine (JVM) started by the mid-tier
JavaServer Pages (JSP) or servlet engine.
To monitor the mid tier on the mid-tier host:
At the At the command-line prompt, set the JAVA_OPTS environment variable as
follows, and then start Tomcat:
set JAVA_OPTS=Dcom.sun.management.jmxremote
Alternatively, add that parameter to the JAVA_OPTS entry in the TomcatInstallDir/bin
/catalina.bat file, and then restart Tomcat.

To monitor the mid tier remotely:
At the command-line prompt, set the JAVA_OPTS environment variable as follows,
and then start Tomcat:
set JAVA_OPTS=Dcom.sun.management.jmxremote.authenticate
=false
-Dcom.sun.management.jmxremote.port=portNumber
Page 628 of 4705
Home
portNumber is the port number to connect to your JMX Remote Method Invocation (
RMI) connector. Specify an unused port number.
Alternatively, add those parameters to the JAVA_OPTS entry in the TomcatInstallDir/
bin/catalina.bat file, and then restart Tomcat.
2. To enable real-time monitoring, select the Enable Mid Tier Performance MBean check box
on the General Settings page In the BMC Remedy Mid Tier Configuration Tool. See
Configuring the General Settings page.
Note
You can also monitor mid-tier memory use and performance by analyzing the entries in
the armidtier.log file. For more information, see BMC Remedy Mid Tier logging.
Accessing the Mid Tier Configuration Tool

You can access the Mid Tier Configuration Tool in any of the following ways:
Open a browser and enter the following URL:
http://<hostName>:<portNumber>/<contextPath>/shared/config/config.jsp
hostName is the name of the host computer for the mid tier.
portNumber is an optional port number; it is required if the web server is not using the
default port (port 80).
contextPath is the path to the location of the mid tier in the Oracle JSP engine ( arsys
by default).
If the mid tier is installed on the local computer using the default context path, enter the
following URL in your browser: http://<localhost>/arsys/shared/config/config.jsp
For this the URL to work, localhost must be correctly entered in the hosts file.
On a Windows computer where the mid tier is installed on the local computer, select Start >
Programs > BMC Software > AR System > BMC Remedy Mid Tier > Configure
ARSYSTEM on Localhost.
To log on to the Mid Tier Configuration Tool

1. When the Login page appears, enter the login password for the Mid Tier Configuration Tool.
If you have not changed the password from the default, enter arsystem.
2. Click Login.
After you log on, the Mid Tier Configuration Tool Overview page appears. It displays the current
settings for your installation. Use the navigation pane at the left to select configuration tasks.
The following topics provide detailed information about working with the Mid Tier Configuration Tool
:
Page 629 of 4705
Home
Using the Mid Tier Configuration Tool with a load balancer

Setting MIME types
Using the Mid Tier Configuration Tool with a load balancer

If you are using the Mid Tier Configuration Tool with a load balancer, you must use the web server's
real IP address, not a virtual IP address, to open the Mid Tier Configuration Tool. Explicitly
configure each mid tier instance directly, not through the load balancer's virtual IP. The Mid Tier
Configuration Tool will not function as expected if you use a virtual server to open it.
Each web server must have its own mid tier. You must configure each mid tier individually, and you
must configure each mid tier identically.
Note
BMC recommends configuring the load balancer without using a "sticky bit" (session
affinity) to allow sessions from any BMC Remedy Mid Tier server to be distributed to any
BMC Remedy AR System server on the fly. For more information, see Configuring the
Connection Settings page.
A persistent session allows login content to be maintained. Session migration between JSP engine
instances is not supported.
Setting MIME types

If you have an application that requires mapping to another application to view it, you can set
multipurpose internet mail extensions (MIME) types in the JSP engine configuration, typically by
using the graphical user interface. You can also set MIME types manually by adding them to the
web.xml file.
Configuring the Change Password page

You can change the password used to access the Mid Tier Configuration Tool. The password must
contain more than 5 and must not exceed 20 characters; do not include double-byte characters.
Mid Tier Configuration Tool Change Password page
Page 630 of 4705
Home
To verify that the new configuration password is in effect, log out of the Mid Tier Configuration Tool
and log on again.
Configuring the Overview page

This section describes the settings that you can specify and update by using the Mid Tier
Configuration Tool. To access the pages for these settings, click the appropriate links in the
navigation pane.
The following topics provide detailed information about the parameters for the Mid Tier system
information and the current configuration settings:
Mid Tier system information parameters
Current Configuration parameters
The Overview page displays information about BMC Remedy Mid Tier system settings.
Mid Tier Configuration Tool - Overview page
Mid Tier system information parameters

The following table lists the parameters in the BMC Remedy Mid Tier system information section.
Overview settings - BMC Remedy Mid Tier system information
Setting
Value
Mid Tier
Version
The version of the BMC Remedy Mid Tier that is installed.
Installation
Directory
The directory path being used for your BMC Remedy Mid Tier installation.
Web
Server
Information
The product name of the web server being used with this installation of the BMC Remedy Mid Tier (for example,
Microsoft IIS) and the product name of the Java servlet engine being used with this installation of BMC Remedy
Mid Tier (for example, Apache Tomcat).
Note
Page 631 of 4705
Home
Setting
Value
In some web configurations, only the servlet engine details are shown.
Operating
System
Name
The operating system used on your computer (for example, Oracle Solaris 10 or Windows 2003 Server).
Java
Version
The version of the Java Software Development Kit (SDK) that is installed on your computer (for example, 1.5.0).
Current Configuration parameters

The following table lists the parameters in the current configuration settings section.
Overview settings - Current Configuration settings
Setting
Value
AR Server(s)
The AR System servers currently used with the BMC Remedy Mid Tier.
Preference Server
(s)
The servers currently designated as preference servers. You can add or delete servers from the General
Data Visualization
Module Server(s)
The AR System server that contains the data visualization module.
Homepage Server
The AR System server for the BMC Remedy Mid Tier on which the home page resides.
Log Directory
The directory path in which session-related information, such as logs and temporary files, is stored.
Definition Change
Check Interval (
Seconds)
The interval (in seconds) at which information in the cache is updated. The default value is 86400 seconds.
Session Timeout (
Minutes)
The number of minutes after which a session expires. When the system has exceeded this amount without
any activity, the user must log on again. The default value is 90 minutes. You can change this value on the
Settings page. See Setting user preferences.
You can change this value on the Cache Settings page.
General Settings page.
Configuring the General Settings page

To access the General Settings page, click the General Settings link in the navigation pane. Use
this page to update configuration settings, such as session timeout intervals, preference servers,
Home page server, and reporting information. A bold label with an asterisk indicates a required field
.
Mid Tier Configuration Tool - General Settings page
Page 632 of 4705
Home
General Settings parameters

The following table lists the parameters on the General Settings page.
Setting
Description
Session
Timeout (
Minutes)*
The number of minutes after which the current session will expire. When the system has exceeded this amount
without any activity, you must log on again. A session timeout clock in the status bar appears in the web
browser of each user session. The clock shows how much time is left before an HTTP session will time out. If a
user is logged in and performs any activity in an application on the BMC Remedy Mid Tier, the clock's timer
starts over. The session timeout clock has an update granularity of 1 minute. At each 60-second interval, the
Oracle JavaScript controlling the session timeout clock is executed to update the clock with the amount of time
available before the HTTP session times out. For example, if 1 minute and 32 seconds remains, the display
time will read 2 minutes.
If the form is viewed in a Firefox browser and the form includes a view, flashboard, or data
visualization field, the session timeout clock might not appear.
If a user is entering data in a form, that data might be lost if the session times out before the user submits the
data. To prevent possible data loss after a timeout, the user should leave the data visible in the form and use
the same login ID to open a new instance of the browser window. In the new browser, the user should then
navigate to the form, copy the data, and paste it into the new form. If users experience frequent timeouts,
increase the session timeout interval. The default value is 90 minutes; there is no upper or lower limit. The entry
in the Session Timeout in Minutes field of the AR System User Preference form ( Web tab) will override this
setting for a specific user.
License
Release
Timeout ([30 300] Seconds)
*
The number of seconds before BMC Remedy Mid Tier releases an AR System user license associated with a
user if that user does not log out of BMC Remedy Mid Tier properly. To log out properly, the user must close the
last browser window associated with the current HTTP session or navigate away from BMC Remedy Mid Tier.
The default delay is 60 seconds. BMC Remedy Mid Tier initiates a delay timer when the user closes the last
browser window associated with the established HTTP session. When the delay timer expires, the user's
license is released, and the HTTP session terminated. If the user navigates back to the mid-tier URL before the
delay time expires, the delay timer is cancelled, and the current HTTP session is resumed.
Preference
Servers
The name of the AR System server designated as a preference server. You can specify more than one server if
you need multiple preference servers to support different departments or business units. If you enter more than
one preference server, the system searches the list until it finds the first preference server that matches the user
name and uses that server as the preference server. To add or update preference servers, enter the name of
each server that you want to designate as a preference server. If you are adding more than one server,
separate each name with a comma (for example, mars, jupiter, saturn). A fully qualified server name is not
valid in this field.
All servers designed as preference servers must be included in the AR System Server list on the AR
Server Settings page. For more information, see Configuring the AR Server Settings page.
Page 633 of 4705
Home
Setting
Description
Data
Visualization
Module
Servers
The name of the BMC Remedy AR System server designated as a data visualization module server. You can
specify more than one server if you need to copy the modules to another server as a backup in case the first
module server goes down. To add or update module servers, enter the name of each server that you want to
designate as a module server. If you are adding more than one server, separate each name with a comma (for
example, mars, jupiter, saturn). A fully qualified server name is not valid in this field.
All servers designed as module servers must be included in the BMC Remedy AR System Server list
on the AR Server Settings page.
For information, see Using Crystal reports with BMC Remedy AR System .
Homepage
The server that contains the home page that you want to open in the browser when the user logs on. The home
Server
page URL is: http://<midTierServer>/<contextPath>/home. The home page server must already in the list of
BMC Remedy AR System servers on the AR Server Settingspage. For information, see Configuring the AR
Server Settings page. BMC Remedy Mid Tier searches this server for the designated or default home page.
This server is used globally if you have not selected a home page server in the AR System User Preference
form. A home page server specified in the AR System User Preferences form takes precedence over the server
set here. The form used for the home page has the following precedence on a specific server:
1. A form designated in the AR System User Preference form.
2. A default home page designated in the AR System Administration: Server Information form.
3. The default home page installed with AR System.
For more information, see Setting the Home Page tab.
Authentication
Server
The server that BMC Remedy Mid Tier uses to authenticate the user. If an authentication server is specified,
BMC Remedy Mid Tier authenticates with the specified server only. The server specified here must already be
in the list of BMC Remedy AR System servers on the AR Server Settings page. For more information, see
Configuring the AR Server Settings page. If an authentication server is not specified, BMC Remedy Mid Tier
behaves as follows:
1. Logs the user in with the preference server, if one is specified.
2. If there is no preference server, logs the user in to the first server listed in the AR Server list.
3. If that login is not successful, logs the user in to the next server on the list. (A guest login is considered a
successful login.)
Prefer
Standard/
Windows
Views
One of the settings evaluated when the system is progressing through the view selection algorithm; it indicates
whether you want a standard view or a web view to be the default for the view type selection. If no view is
selected and the check box is:
Selected - The browser displays the standard view of the form.
Cleared (default) - The browser displays the web view of the form, if one is available. If no web view is
available, the standard view is displayed. For more information, see How a view is selected and
Selecting a form view for the user.
Enable Object
List
Indicates whether you want to enable the AR System Object List that displays all the forms and applications that
BMC Remedy Mid Tier can access. If the check box is:
Selected - The Object List is displayed automatically when the system cannot determine the specific
form to load because an incomplete URL is entered into the browser or an application does not define a
primary form.
Cleared (default) - The AR System Object List is not enabled and is not displayed when the system
cannot determine which form to load.
For more information, see Using the Object List.
Page 634 of 4705
Home
Setting
Description
Enable Skins
Indicates whether skins are enabled for form views. If the check box is:
Selected - Skins are enabled for form views.
Cleared (default) - Skins are not enabled for form views, and are not visible when a form is displayed.
Enable Mid
Tier
Performance
MBean (
requires
restart)
Indicates whether mid tier memory use and performance can be monitored in real time through a Java
Management Extension (JMX) console, such as JConsole. If the check box is:
Selected - Memory use and performance can be monitored using a JMX console.
Cleared (default) - Real-time memory use and performance monitoring is not enabled.
For more information, see Configuring mid tier memory.
Setting pagination properties

If the results of a search returns a large number of records, you can view the results in pages
instead of single large list. You can set the pagination properties in BMC Remedy Developer Studio
and in the BMC Remedy Mid Tier application to ensure that the results are displayed in pages.
Setting pagination properties to view search results
User Scenarios
Setting pagination properties to view search results

To ensure that a pagination is available for the result lists, you can set the following properties in
order of their precedence:
Max Entries Returned If you set this value, the results list display the number of records
equal to this value on one page. The remaining records are displayed in subsequent pages
having number of records equal to this property value. If you have set this value, the Max
Entries Returned By GetList property is not considered for pagination. Set using
Definitions > Basic properties on any form in Developer Studio. For details about how to
set form properties, see Setting basic form properties.
Max Entries Returned By GetList This property limits how many database records are
returned from a search. For the results list, The property value is used for configuring the
maximum number of results returned in one page and distributing the results list into
subsequent pages having same number of records equal to this property value. If you have
set the Max Entries Returned property, this property value is not used for pagination. Set
using General > Server Information. For details about this property, see Setting the general
tab on server information form.
View Level Size of Chunk for Result List This property limits records in results list on
form views. If you set this value on form views, the cSet on any form view using properties.
For details about this property, see Setting form view properties.
Limit Number of Items returned Set using User Preferences > My User Preferences.
For details about this property, see Setting the general tab on user preference form .
Page 635 of 4705
Home
The minimum value of either the View Level Size of Chunk for Result List property or the Limit
Number of Items returned property is provided to the server and this minimum value is compared
with the Max Entries Returned form property. The smaller value is then used to display the form
results list. If you do not provide a value for the Max Entries Returned form property, the Max
Entries Returned By GetList server property is used for comparison.
User Scenarios
Formula
X = Lesser value between "View Level Size of Chunk for Result List" and "Limit Number
of Items returned"
Y = Lesser value between "Max Entries Returned" and X
If "Max Entries Returned" is not provided:
Y = Lesser value between "Max Entries Returned By GetList" and X
Y is the value used for displaying records in the results list.
The following table displays the list of values set for each property and the number of records
displayed in the results list:
Scenarios
Max Entries
Returned
Max Entries
Returned
By GetList
View Level
Size of
Chunk for Result List
(Server property)
(Form View property)
(User Preference
property)
(Form property)
Limit Number
of Items returned
Property value
used for
Pagination
20
50
20
20
50
10
10
20
50
10
50
50
50
10
20
10
20
30
10
1000
Note
If you have not provided value for any of the pagination properties, 1000 is the default
value used for showing results in a results list.
Page 636 of 4705
Home
Configuring the AR Server Settings page

Click the AR Server Settings link in the left navigation pane to open the AR Server Settings page,
where you can add, delete, or modify information about servers that BMC Remedy Mid Tier uses.
Mid Tier Configuration Tool - AR Server Settings page
The following topics provide detailed information about the AR Server Settings page:
AR Server Settings parameters
Adding or deleting a server
Editing server properties
AR Server Settings parameters

The following table lists the settings on the AR Server Settings page.
AR Server settings
Setting
Description
Delete/
Edit
Click in the check box to select a server. To select all servers in the list, click Select All; to clear all selections in the
AR
Server
Name
The name of the AR System server that BMC Remedy Mid Tier is using. The name must be from a server that AR
System recognizes. BMC Remedy Mid Tier must be able to resolve this server name to an IP address. BMC Remedy
Domain
Name
The domain name portion of the fully qualified server name for the AR System server.
Use
Short
Name
Specifies whether the BMC Remedy Mid Tier always uses the short name of the AR System server. For example,
AR
Server
The specified password for an AR System account with administrator privileges. Set the BMC Remedy Mid Tier
Admin
Password
AR
Server
TPC Port
Number
list, click Clear All.
Mid Tier must also be able to reach the server through the defined port or through port 111, if the server is running
over the portmapper.
serverName. This value is set by the Use Short Name check box when adding or editing an AR System server.
Administration Password under the Connection Settings tab in the AR System Administration: Server Information
form. (If a password has been entered for a server, asterisks appear in this column instead of the actual password
characters.) Version 7.0 and later AR System servers require a password.
The port number you previously configured to access the AR System server. If you have not configured a port
number, this field is blank.
Page 637 of 4705
Home
Setting
Description
AR
Server
RPC
The Remote Procedure Call (RPC) protocol number that the server will use. This number can be used for connecting
to a private server. If you have not configured an RPC number, this field is blank.
Pre-Load
Specifies whether preloading of forms to the system's memory is enabled for the server.
Adding or deleting a server

Use the following procedures to add a new server or delete an existing server:
To add a new server
To delete one or more servers
To add a new server

1. In the Mid Tier Configuration Tool, click AR Server Settings.
2. Click Add Server to open the Add New Server page.
3. Enter the server name (required).
If you want to use the subset reserved field (ID 1576) in your workflow and use fully qualified
domain names with relative host names, add all the variations of server names in the Server
Name field, and the IP address, if it is used.
For example:
myserver
myserver.bmc.com
myserver.labs.bmc.com
1.160.11.240
For more information about reserved fields and their use, see Reserved fields.
4. If you want the BMC Remedy Mid Tier to use the short name of the AR System server
instead of the long name (shortName+domainName), even if the domain name is defined,
select the Use Short Name check box. This includes use for $server$ keyword, URL
generation, etc.
If the Use Short Name check box is clear, the BMC Remedy Mid Tier will always use the
long name of the AR System server, even if the domain name of the AR System server is
defined.
5. Enter an administrator password, port number, and RPC number for the new server.
6. If you want to validate the password for the server, select the Validate Password check box
.
If you select the check box and you enter the correct password, the server is added to the
list of servers that BMC Remedy Mid Tier uses. If you enter the wrong password, you cannot
edit the server.
7. To preload forms to the system's memory, select the Pre-Load check box.
8. Click Add Server.
Page 638 of 4705
Home
To delete one or more servers

2. In the Delete/Edit column of the AR Server Settings page, select the check boxes next to
the servers that you want to delete.
To select all servers, click the Select All link.
3. Click Delete.
Note
If a server that you have selected for deletion is being used as a preference server
or a home page server, you must delete it from the General Settings page before
you can delete it from this list. For more information, see Configuring the General
Settings page.
Editing server properties

Use the following procedure to edit server properties.
To edit server properties

2. In the Delete/Edit column of the AR Server Settings page, select the check box next to the
server whose properties that you want to edit.
Note
You cannot edit the server name. To change the name of a server, delete the
server and add it again with the new name. Although the interface appears to allow
it, you cannot edit multiple servers at the same time.
3. Click Edit to open the Edit AR Server page.

4. If you want the BMC Remedy Mid Tier to use the short name of the AR System server
instead of the long name (shortName+domainName), even if the domain name is defined,
select the Use Short Name check box.
If the Use Short Name check box is clear, the BMC Remedy Mid Tier uses the long name,
which includes as a domain name provided by the AR System server. The AR System
server can be configured to use the domain of its host operating system to use a specific
hardcoded domain name.
5. In the Admin Password, Port#, or RPC# fields, make the appropriate changes.
6.
Page 639 of 4705
Home
6. If you want to validate the password for the server, select the Validate Password check box
.
If you select the check box and you enter the correct password, the server is added to the
list of servers that BMC Remedy Mid Tier uses. If you enter the wrong password, you cannot
edit the server.
7. To preload forms to the system's memory, select the Pre-Load check box.
8. To change the interval (in seconds) at which cache information is automatically updated,
enter the new number of seconds in this field. The default value is 86400 seconds. For
Development cache mode, the value must be 0. For Production cache mode, the value must
be greater than 0.
Note
In Development cache mode, application-level changes are not automatically
updated in the BMC Remedy Mid Tier cache. For example, if you change an
application's primary form and then reload the page, the old primary form is
displayed. To display the new primary form on reload, you must click Flush Cache.
For information about Development and Production modes, see Configuring server groups.
9. Select the Perform Check check box if you want the cache to be updated automatically at a
specific time interval on the Definition Change Check Interval field value. You can also
update the cache manually by clicking Sync Cache.
10. To enable and make skins visible for form views, select the Enable Skins check box.
11. Click Save AR Server.
Configuring the Cache Settings page

Click the Cache Settings link in the left navigation pane to open the Cache Settings page. Make
the necessary changes, and click Save Changes. To restore the previous settings, click Restore
Defaults, and then Save Changes.
Mid Tier Configuration Tool - Cache Settings page
Page 640 of 4705
Home
The following sections provide detailed information about configuring the Cache Settings page:
Cache Settings parameters
About the cache table
Using the sync cache option
Setting the Definition Change Check Interval
About the Persistent Cache option
Serializing Java objects to a file
About Tomcat configuration settings
Increasing the shutdown timeout in the Tomcat configuration tool
Increasing the JVM memory allocation and thread stack size
How the prefetch process retrieves forms after Tomcat is started or restarted
Open source cache manager and settings in config.properties file
Cache configuration example for temporary disk persistence enabled
Cache configuration example for maximum elements in memory
About prefetching specified forms
Prefetching processes
Specifying forms to prefetch using the prefetchConfig.xml file
Editing the PrefetchConfig.xml file
Example of settings in prefetchConfig.xml file
User and group permissions for prefetching
Creating a good cache
Backing up the mid tier cache
Using cache with multi-tenant mid tier
Avoiding abrupt shutdown of the mid tier
Page 641 of 4705
Home
Cache Settings parameters

The following table lists the parameters for the Cache Settings page.
Cache settings
Setting
Description
Definition Change
Check Interval (
The interval (in seconds) at which cache information is automatically updated. The default value is 86400
seconds. To change the interval, enter the new number of seconds in this field. For Development cache
mode, the value must be 0. For Production cache mode, the value must be greater than 0. If you do not
Seconds)
want the cache to be updated, clear the Perform Check check box.
In Development cache mode, application-level changes are not automatically updated in the BMC
Remedy Mid Tier cache. For example, if you change an application's primary form and then
reload the page, the old primary form is displayed. To display the new primary form on reload,
you must click Flush Cache.
For information about Development and Production modes, see Configuring server groups.
Perform Check
Indicates whether you want the cache to be updated automatically. You can still update the cache
manually by clicking Flush Cache. If the check box is:
Selected The cache will be updated automatically at the interval that you specify in the
Definition Change Check Interval field.
Cleared The cache will not be updated automatically. If the system is in the process of flushing
the cache when you clear the check box, the current cache flush will continue until that session is
completed.
Synchronized
Definition Change
Check (previously
known as Sync in
cluster)
Indicates whether you want the cache to be synced automatically on a group of mid tiers. If the check box
is:
Selected The cache will be synced periodically and simultaneously across all mid tiers in a group
.
Cleared (default) The cache will be synced automatically at the interval that you specify in the
Definition Change Check Interval field.
Note: This option is available from BMC Remedy AR System 8.1 Service Pack 1 onwards.
For more information about this option, see Knowledge Base article ID KA410680.
Update Flashboard
Definition Interval (
The interval (in seconds) at which the server updates the Flashboards cache information. Set this value to
0 to disable caching. The default value is 0.
Seconds)
Resource Check
Interval (Seconds)
The time limit (in seconds) for which resources (such as images, .css files, and JavaScript files) can be
used. The default value is 86400 seconds. If a user closes a form and opens it again within the specified
expiry time, the image is cached and is not downloaded again. This helps increase the performance of
BMC Remedy Mid Tier.
Enable Cache
Persistence
Specifies whether forms cached in memory are written to files for faster retrieval. If the check box is:
Selected Forms cached in memory are written to files. This option enables faster retrieval of
forms when the server is restarted.
Cleared Forms cached in memory are not written to files.
Page 642 of 4705
Home
Setting
Description
AR System forms can be stored on disk only after Enable Cache Persistence is selected. AR System
forms loaded before the Enable Cache Persistence is selected are not saved to disk. For more
information, see About the Persistent Cache option.
Flush Cache
Removes all items from the caches that BMC Remedy Mid Tier maintains. The next time the mid tier needs
those objects, the most up-to-date versions are retrieved from the AR System server.
Sync Cache
For the selected servers, clears the cache only for the objects that have been changed. For more
information, see Using the sync cache option.
Prefetch
Configuration
A text area where you can update the contents of the prefetchConfig.xml file. You can also edit a copy of
this file directly. It is in the WEB-INF/classes subdirectory. For more information, seeEditing the
PrefetchConfig.xml file.
About the cache table

The cache table (located below the prefetch configuration text box) shows the following
information about different cached objects and how they change:
Object name The type of object in the cache.
Object count The number of objects in the cache.
Hit count The number of times an object is found in the cache.
Miss count The number of times an object is not found in the cache.
Last flush The time that particular type of object was last flushed from the cache and the
reason for the flush.
This table is useful for monitoring your application's performance. If objects are being flushed due
to server definition changes, serious performance degradation can occur.
Note
By default, cache statistics (hit count and miss count) are not displayed even though they
are actually being collected. To enable cache statistics, see #Setting up a mid tier server
to use cache table statistics.
Setting up a mid tier server to use cache table statistics

This section explains how to setup the object cache for a mid tier server so that cache statistics are
enabled.
To setup a mid tier server to use cache table statistics

1. Go to the ARSystemInstallFolder\midtier\WEB-INF\classes folder.
2. Open the config.properties file.
3.
Page 643 of 4705
Home
3. In the config.properties file, set arsystem.ehcache.enableStats to true.

4. Save the config.properties file.
5. Restart Tomcat.
The cache table statistics are now enabled.
To view the contents of the cache, access the following URL:

http://<midTierServer>:<portNumber>/arsys/shared/config/config_cache.jsp
Using the sync cache option

To enable faster previewing of changes to forms and applications in a browser, and to enable users
to see updated information more quickly, you can use the Sync Cache option for the available
servers. Selecting this option for a server clears only those objects that have changed on that
server since the last time the cache was cleared.
Sync cache option
The Sync Cache operation synchronizes any of the following objects, if the changed timestamp on
BMC Remedy AR System Server is more recent than the cached item in the BMC Remedy Mid Tier
cache:
Forms
Active links
Containers (guides, applications, web services)
Menus (character menus)
Sync Cache completely removes and rebuilds the following cache items since the performance hit
is minimal:
Page 644 of 4705
Home
Group data
Role data
Image objects
Note
The Sync Cache feature is not available in pre 7.5, patch 004 versions.
Setting the Definition Change Check Interval

The Definition Change Check Interval value defines the cache mode as follows:
When the Definition Change Check Interval value is set to 0, the system is working in
development cache mode. In this mode, the Sync Cache option should not be used. If a
sync is triggered in this mode, an error is generated and syncing does not occur.
When the Definition Change Check Interval value is set to 1, the system is working in
production cache mode. In this mode, the Sync Cache option can be used to synchronize
the BMC Remedy Mid Tier cache with AR System server.
Note
For more information about configuring cache modes see, Configuring server groups.
About the Persistent Cache option

Since BMC Remedy AR System 7.1.00, forms currently cached in memory can be serialized (
written to) to one or more files, which enables the forms to be retrieved faster.
When a user opens a BMC Remedy AR System on a form for the first time, BMC Remedy Mid Tier
must download the form and its workflow objects. It must then construct a Java object from these
items. This object is used to generate the Dynamic HTML needed to display the form in a browser.
The initial construction of this Java object is time-consuming, but after it is built, BMC Remedy Mid
Tier caches it in memory and accesses it for all users who open the same form from that point on.
Serializing Java objects to a file

BMC Remedy Mid Tier can serialize the constructed Java objects that represent BMC Remedy AR
System forms present in memory and write them to a file when the form is loaded. BMC Remedy
Mid Tier detects the file, reads it, and reconstructs the Java objects serialized in it. This prevents
the system from having to repeat the time-consuming construction process.
You can activate serialization from the cache page of the Mid Tier Configuration Tool by selecting
the Enable Cache Persistence option.
Page 645 of 4705
Home
Note
If the application server hosting BMC Remedy Mid Tier shuts down unexpectedly, BMC
Remedy Mid Tier reloads all forms specified in the prefetch configuration from the AR
System server when the application server is restarted.
About Tomcat configuration settings

Because the time required to serialize forms can vary depending on their size and complexity, you
might need to increase the Tomcat shutdown time and thread stack sizes to enable the efficient
serialization of your forms.
For example, if you are using the version of Tomcat that was bundled with your Windows BMC
Remedy AR System installation, the service might fail to restart if the timeout setting is too low and
you have cached many forms.
Increasing the shutdown timeout in the Tomcat configuration tool

Use the following procedure to increase the shutdown timeout in the Tomcat configuration tool.
Note
You must use the Tomcat configuration tool to configure these settings and restart Tomcat
.
You do not need to adjust the shutdown time when running Tomcat from the command line.
To increase the shutdown timeout in the Tomcat configuration tool

1. Select Start > All Programs > Apache Tomcat > Configure Tomcat.
2. Click the Shutdown tab.
3. In the Timeout field, enter a value that is appropriate for the number of forms you have
cached. The more forms you have cached, the larger this number should be. A value of 60
seconds is recommended. Use a higher value if you will be caching a large number of forms.
4. Click the General tab.
5. Click Start.
6. Click OK.
Increasing the JVM memory allocation and thread stack size

Use one of the following procedures to increase the JVM memory allocation and thread stack size
by using the Tomcat configuration tool or from the command line.
Page 646 of 4705
Home
Note
You must use the Tomcat configuration tool to configure these settings and restart Tomcat
.
To increase the JVM memory allocation and thread stack size in the Tomcat configuration tool
1. Select Start > All Programs > Apache Tomcat > Configure Tomcat.
2. Click the Java tab.
3. Enter the following recommended values:
Initial memory pool 1024 MB
Maximum memory pool 1024 MB
Thread stack size Leave this field empty
4. Click the General tab.
5. Click Start.
6. Click OK.
To increase the JVM memory allocation and thread stack size for Tomcat from the command
line
1. Open the catalina.bat file (TomcatInstallDirectory/bin /catalina.bat).
2. Add the following line:
set JAVA_OPTS=%JAVA_OPTS% -Xms1024m
-Xmx1024m
where:
Xms is the initial (start) memory pool
Xmx is the maximum memory pool
Xss is the thread stack size
How the prefetch process retrieves forms after Tomcat is started or restarted
When Tomcat is started or restarted, the system retrieves specified forms as follows:
The prefetch process retrieves an entry for a form from the prefetchConfig.xml file, and
checks the timestamp on the AR System server.
If the timestamp indicated on the AR System server is identical (that is, if the form has not
been changed on the server), the prefetch process requests the specified form from the
cache manager.
If the timestamp indicated on the AR System server is newer, the prefetch process retrieves
all forms specified in the prefetchConfig.xml file from the AR System server.
Note
Page 647 of 4705
Home
If Tomcat starts when the BMC Remedy AR System server is not running, prefetch does
not occur. To make sure forms are correctly prefetched, verify that the BMC Remedy AR
System server is running before starting or restarting Tomcat.
Open source cache manager and settings in config.properties file

BMC Remedy Mid Tier includes an open-source cache manager, ehcache. The following
properties are available in the config.properties file to enable advanced administrators to
customize the cache behavior.
arsystem.resource_expiry_interval Sets the cache expiry time (in seconds) after which
the browser checks BMC Remedy Mid Tier for updated resources such as images and
JavaScript files. The default value is 3600.
arsystem.ehcache.maxElementsInMemory Sets the maximum number of objects that
will be maintained in the memory cache. If set to 0, the number of objects is unlimited. The
default value is 2147483647.
arsystem.ehcache.eternal Sets whether elements are eternal. If eternal, timeouts are
ignored and the element is never expired. The default value is true.
arsystem.ehcache.timeToIdleSeconds Sets the maximum amount of time between
accesses before an element expires. This setting is used only if the element is not eternal (
arsystem.ehcache.eternal=false). A value of 0 means that an element can idle for infinity.
arsystem.ehcache.timeToLiveSeconds Sets the maximum time between creation time
and when an element expires. This setting is used only if the element is not eternal (
arsystem.ehcache.eternal=false). A value of 0 means that an element can live for infinity.
arsystem.ehcache.overflowToDisk Sets whether the disk store persists to disk between
restarts of the Java Virtual Machine. The default value is true. If the Enable Cache
Persistence option is selected in the Mid Tier Configuration Tool, the value is set to true.
arsystem.ehcache.overflowToDiskTemp Sets whether to cache items to overflow from
memory to disk. The cache items are not preserved between restarts of the Java Virtual
Machine. The default value is false. If set to true when arsystem.ehcache.overflowToDisk
is set to true, duplicate storage of the same cache item on disk might result.
arsystem.ehcache.maxElementsOnDisk Sets the maximum number of objects that will
be maintained in the DiskStore. The default value is 0 (unlimited).
arsystem.ehcache.diskExpiryThreadIntervalSeconds Sets the number of seconds
between runs of the disk expiry thread. The default value is 600.
arsystem.ehcache.memoryStoreEvictionPolicy Sets the memory policy. The policy
would be enforced upon reaching the maxElementsInMemory limit. The default policy is
Least Recently Used (LRU). Other policies include First In First Out (FIFO) and Less
Frequently Used (LFU).
Page 648 of 4705
Home
arsystem.ehcache.referenceMaxElementsInMemory The maximum number of

elements in memory for each cache maintained by BMC Remedy Mid Tier. Because caches
grow at different rates, this value is used as a base value, which is then multiplied by a
cache-specific weight value.
This property is used in conjunction with the
arsystem.ehcache.referenceMaxElementsInMemoryWeight. cacheType to determine the
maximum number of elements in memory allowed for a given cache. After the maximum has
been reached for a given cache, elements are split over to disk using an LRU policy if disk
persistence has been enabled. By changing this value, you can adjust the maximum sizes
for all caches and maintain the appropriate weightings for each cache. If this property is
specified, then arsystem.ehcache.maxElementsInMemory is no longer in effect. If the
property is not specified, then arsystem.ehcache.maxElementsInMemory behaves as
before. There is no specified default value.
The value in each of the following properties is multiplied with the value specified by the
arsystem.ehcache.referenceMaxElementsInMemory property to determine the maximum
number of elements in memory allowed for the specified cache. After the maximum has been
reached, elements are spilled over to disk using the policy specified by the property
arsystem.ecache.memoryStoreEvictionPolicy, if disk persistence has been enabled.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formImages The
maximum elements in memory weight for the AR System form images cache. The default
value is 0.104.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.activeLinks The
maximum elements in memory weight for the AR System active links cache. The default
value is 4.904.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.groups The maximum
elements in memory weight for the AR System groups cache. The default value is 0.025.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.roles The maximum
elements in memory weight for the AR System roles cache. The default value is 0.036.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.js The maximum
elements in memory weight for the JavaScript cache. The default value is 0.195.
arsystem.ehcache.referenceMaxElementsInMemoryWeight. displayedFields The
maximum elements in memory weight for the display fields cache. The default value is 0.157
.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.fieldMaps The maximum
elements in memory weight for the AR System field maps cache. The default value is 0.323.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.sysdata The maximum
elements in memory weight for the system data cache. The default value is 1.202.
arsystem.ehcache.referenceMaxElementsInMemoryWeight. compiledForms The
maximum elements in memory weight for the compiled AR System forms cache. The default
value is 1.14.
Page 649 of 4705
Home
arsystem.ehcache.referenceMaxElementsInMemoryWeight.forms The maximum

elements in memory weight for the AR SystemSystem forms cache. The default value is
0.235.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.html The maximum
elements in memory weight for the HTML cache. The default value is 0.195.
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formFields The
maximum elements in memory weight for the AR System form fields cache. The default
value is 28.577.
arsystem.ehcache.overflowToDiskTemp Whether to allow cache items to overflow from
memory to disk temporarily. The overflow behavior follows the policy specified by the
property arsystem.ehcache.memoryStoreEvictionPolicy. The cache items are not
preserved between Java Virtual Machine (JVM) restarts. This property can be set to true
along with arsystem.ehcache.overflowToDisk being set to true, but might result in
duplicate storage of the same cache item on disk, wasting disk space. This property honors
the values for arsystem.ehcache.maxElementsOnDisk and
arsystem.ehcache.diskcache.maxElementsInMemory. The default value is false.
arsystem.ehcache.midTierCacheTempDir Specifies the directory where overflow
elements from the caches are stored if temporary disk persistence is enabled. This property
is in effect only if arsystem.ehcache.overflowToDiskTemp is set to true. The default value
is midTierRootDirectory/cachetemp.
Cache configuration example for temporary disk persistence enabled

The following example of property values for cache persistence is for temporary disk persistence
enabled (out-of-box configuration).
arsystem.ehcache.overflowToDiskTemp=true
arsystem.ehcache.midTierCacheTempDir=
Setting the above two properties will allow cache elements to spill over to disk temporarily. The
spilled-over cache elements are stored in the directory midTierRootDirectory/cachetemp.
Cache configuration example for maximum elements in memory

The following example of property values for cache persistence is for maximum elements in
memory (out-of-box configuration).
arsystem.ehcache.referenceMaxElementsInMemory=1250
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formImages=0.104
arsystem.ehcache.referenceMaxElementsInMemoryWeight.activeLinks=4.904
arsystem.ehcache.referenceMaxElementsInMemoryWeight.groups=0.025
arsystem.ehcache.referenceMaxElementsInMemoryWeight.roles=0.036
arsystem.ehcache.referenceMaxElementsInMemoryWeight.js=0.195
arsystem.ehcache.referenceMaxElementsInMemoryWeight.displayedFields=0.157
arsystem.ehcache.referenceMaxElementsInMemoryWeight.fieldMaps=0.323
arsystem.ehcache.referenceMaxElementsInMemoryWeight.sysdata=1.202
Page 650 of 4705
Home
arsystem.ehcache.referenceMaxElementsInMemoryWeight.compiledForms=1.14
arsystem.ehcache.referenceMaxElementsInMemoryWeight.forms=0.400
arsystem.ehcache.referenceMaxElementsInMemoryWeight.html=0.195
arsystem.ehcache.referenceMaxElementsInMemoryWeight.formFields=8.577
arsystem.ehcache.referenceMaxElementsInMemoryWeight.actorViews=0.32
arsystem.ehcache.referenceMaxElementsInMemoryWeight.actorViewsMapping=0.32
As noted in the following table, setting these properties specify the maximum number of elements
for each cache:
Maximum number of elements for cache types

Cache type
Calculation
Maximum number of elements
Form images
1250 * 0.104
130
Active links
1250 * 4.094
5118
Groups
1250 * 0.025
31
Roles
1250 * 0.36
450
JavaScript
1250 * 0.195
244
Display fields
1250 * 0.157
196
Field maps
1250 * 0.323
404
System data
1250 * 1.202
1502
Compiled forms
1250 * 1.14
1425
Forms
1250 * 0.400
500
HTML
1250 * 0.195
244
Form fields
1250 * 8.577
10721
Actor views
1250 * 0.32
400
Actor views mapping
1250 * 0.32
400
About prefetching specified forms

In previous versions of BMC Remedy AR System, the ability to gather forms and workflow for
preloading on a server called prefetching required editing a file called prefetchConfig.xml,
which was installed with BMC Remedy Mid Tier. Each of the items to be preloaded had to be added
to the file manually; there was no automated process by which forms and workflow could be
preloaded.
BMC Remedy AR System can now preload active links and menus, and in turn detect and preload
the associated forms. This preloading can be enabled by selecting an option in the General
Settings page of the Mid Tier Configuration Tool.
Page 651 of 4705
Home
In addition, form views are preloaded based on usage statistics gathered by BMC Remedy Mid Tier
.
Administrators can configure BMC Remedy Mid Tier to preload (prefetch) forms into the system's
memory so that forms can be loaded faster when they are opened in a browser. This capability is
especially useful for larger forms that otherwise might take several seconds to load.
Prefetching processes
Prefetching is triggered whenever BMC Remedy Mid Tier is restarted, or when the cache is flushed.
Prefetching includes these processes:
1. Forms with active links and menus are preloaded into the system's memory.
2. If a prefetchConfig.xml file exists (from a previous release of BMC Remedy AR System), all
of the forms and views specified in that file are preloaded.
3. Views are preloaded according to usage statistics gathered by the BMC Remedy Mid Tier
server.
The first prefetching process can be enabled by checking the Enable Preload option from the
General Settings page of the BMC Remedy Mid Tier Configuration Tool.
In this topic:
Specifying multiple threads for prefetching
Specifying multiple threads for prefetching

You can specify the number of prefetch threads in the config.properties file by editing the
arsystem.max_number_of_pretch_threads flag.

You do not need to specify a prefetch for every user in the system. The BMC Remedy Mid Tier
caches certain types of objects, such as compiled forms, HTML, and JavaScript relative to a set of
permission groups. For some sets of groups, access to objects (for example, an active link or a field
) might not be granted and as a result, a compiled form for one user can differ from that for another
user. When using prefetching, you must specify a user who serves as a representative of a unique
set of permissions for which you want to prefetch a form. Any subsequent user with the same set of
permissions who accesses the form can take advantage of prefetching.
For example, suppose you have two groups, Group A and Group B, and two users, User 1 and
User 2. Group A includes both users; Group B includes only User 2. User 1 has a permission set
for Groups A and B; User 2 has a permission set for Group B only.
Even though both users belong to Group B, their unique permission sets differ. BMC Remedy Mid
Tier will have a different set of compiled forms, HTML, and JavaScript for each user.
Page 652 of 4705
Home
Prefetching is made easier if users are assigned a set of permission groups that perform the same
function.
Specifying forms to prefetch using the prefetchConfig.xml file

The prefetchConfig.xml file is not required to prefetch forms or views, but a file from the previous
version of BMC Remedy AR System can be edited to specify forms to prefetch.
The Cache Settings page in the Configuration Tool includes a text box that shows the content of
the prefetchConfig.xml file. By default, this content is commented out. By removing the comment
tags, you can edit the content, using the appropriate XML tags to enter the users, servers, locales,
and forms to which prefetching should apply. Multiple users or forms can be specified.
Each form is prefetched according to the specified user's permissions for that form and its fields.
For example, if you select a form that has 75 fields, and specify a user who has permission to view
only 20 fields on that form, the prefetch process can fetch and cache the form with only the 20
fields for which the use has access.
Editing the PrefetchConfig.xml file

You can also edit the prefetchConfig.xml file directly using any text editor. This file is available in
the web-inf/classes subdirectory.
Any changes you make to the file also appear in the Prefetch text box the next time you open the
Configuration Tool.
Remember the following conditions when working with the prefetchConfig.xml file directly or in the
Mid Tier Configuration Tool:
The prefetchConfig.xml file must be specified as UTF-8. When editing the file, do not alter
the UTF-8 information.
Do not change the name of the prefetchConfig.xml file.
If you flush the cache in the Mid Tier Configuration Tool, any prefetched forms you
previously specified are flushed from the memory cache. The prefetch process is performed
again for these forms the next time the web server is restarted.
If you specified an invalid form name (for example, if a form name is misspelled or a form
does not exist on the specified server), that form will not be prefetched. The mid tier log
notes the names of forms that were not prefetched.
Example of settings in prefetchConfig.xml file

In the following example, the prefetchConfig.xml file instructs the mid tier to prefetch forms Home
Page, Sample:Cities, and Sample:Enrollments from the server jiwu-w2k3 with the user Demo.
Page 653 of 4705
Home
<prefetch-user>
<user-name>Demo</user-name>
<locale>en_US</locale>
<prefetch-server>
<server-name>jiwu-w2k3</server-name>
<prefetch-form>
<form-name>Home Page</form-name>
</prefetch-form>
<prefetch-form>
<form-name>Sample:Cities</form-name>
</prefetch-form>
<prefetch-form>
<form-name>Sample:Enrollments</form-name>
</prefetch-form>
</prefetch-server>
</prefetch-user>
You can also click the XSD file link on the Cache page to display a copy of the XSD file, which
shows the syntax used for the prefetch information.

You do not need to specify a prefetch for every user in the system. The BMC Remedy Mid Tier
caches certain types of objects, such as compiled forms, HTML, and JavaScript relative to a set of
permission groups. For some sets of groups, access to objects (for example, an active link or a field
) might not be granted and as a result, a compiled form for one user can differ from that for another
user. When using prefetching, you must specify a user who serves as a representative of a unique
set of permissions for which you want to prefetch a form. Any subsequent user with the same set of
permissions who accesses the form can take advantage of prefetching.
For example, suppose you have two groups, Group A and Group B, and two users, User 1 and
User 2. Group A includes both users; Group B includes only User 2. User 1 has a permission set
for Groups A and B; User 2 has a permission set for Group B only.
Even though both users belong to Group B, their unique permission sets differ. BMC Remedy Mid
Tier will have a different set of compiled forms, HTML, and JavaScript for each user.
Prefetching is made easier if users are assigned a set of permission groups that perform the same
function.
Creating a good cache

Good cache is used for restoring the cache if the cache gets corrupt.
Note
Page 654 of 4705
Home
Set up a separate BMC Remedy Mid Tier outside BMC Remedy Mid Tier cluster for
creating a good cache.
Share a central location to store the copy of the good cache.
To create a good cache and back up the Mid Tier cache

1. Install and set up BMC Remedy Mid Tier 9.0 on a computer outside of the BMC Remedy Mid
Tier cluster with no tenants added.
2. Update the Cache Backup Directory folder path for the BMC Remedy Mid Tier. For example
/opt/bmc/ARSystem/midtier/backup.cache
a. Open the BMC Remedy Mid Tier Configuration Tool.
b. Click the Cache Settings link to open the Cache Settings page.
c. Update the Cache Backup Directory folder path.
3. (Optional) Perform this step after you have onboarding the first tenant.
a. Stop the BMC Remedy Mid Tier.
b. Copy the backup cache from shared location to backup folder of the BMC Remedy
Mid Tier.
c. Delete all the content from the cache folder.
d. Start the BMC Remedy Mid Tier.
4. Add a new tenant BMC Remedy AR server to the BMC Remedy Mid Tier.
5. Start the preload for the tenant BMC Remedy AR System server.
6. When the preload is complete, stop the BMC Remedy Mid Tier.
7. Back up the cache folder.
See Backing up the Mid Tier cache.
8. Replace the backup cache that is stored at the shared location.
9. Update the backup cache directory folder path for all the BMC Remedy Mid Tiers in the
cluster with the new backup cache directory folder path.
Backing up the mid tier cache

BMC recommends that you back up the mid tier cache in a separate directory. When the Tomcat
server crashes or Windows explicitly stops the Tomcat service, that event causes an abrupt
shutdown of the mid tier. When you restart the mid tier after an abrupt shutdown, the mid tier cache
becomes corrupted or truncated. (A smooth shutdown leaves the mid tier cache intact.) If you have
backed up your cache, you can avoid the time-consuming process of preloading the mid tier cache
when the mid tier restarts. The mid tier restores the cache from the backup location only when the
cache becomes corrupted.
To verify whether the cache is intact
To back up and restore the mid tier cache
Using the cache backup utility
Page 655 of 4705
Home
Using good copy of the cache

Related topics
To verify whether the cache is intact

1. Stop Tomcat.
2. Open the .lck file located in the midTierInstallationDirectory\cache directory.
3. Verify whether the SHUTDOWN_COMPLETED state is available in the file.
4. Restart Tomcat.
The cache is intact only if the SHUTDOWN_COMPLETED state is available.
To back up and restore the mid tier cache

1. Create a directory in any location on the computer where the mid tier is running, and copy
the intact cache to this location.
For example, copy the mid tier cache directory located in the midTierInstallationDirectory\
cache folder to the /opt/cache_backup folder.
Note
Ensure that you retain the timestamps of the data and index files. The backed up
copy is not considered as a good copy if the timestamp does not match.
2. On the Cache Settings page, in the Backup Directory field, enter the path and name of the
directory that you created in the previous step.
3. On the Cache Settings page, click Save Changes.
4. (Linux) Stop Tomcat and use the backup utility to take a back up of the cache.
5. Restart Tomcat and click Sync Cache to sync the cache for the AR System server.
Using the cache backup utility

Instead of manually copying the cache on Linux systems, use the cacheBackup utility to back up a
cache and restore it for further use. The cacheBackup utility ( cacheBackupUtility.sh) is a
command-line utility available in the midTierInstallationDirectory/tools directory.
Notes
This utility is available for Linux only. For Windows, you must manually back up the
cache.
BMC recommends that you use the cache backup utility so that you always get a
good copy of the cache without a timestamp mismatch.
Before running this utility, ensure that the mid tier is not running.
Page 656 of 4705
Home
To use the cache backup utility

1. Navigate to the mid tier root by using the following command:
cd /opt/bmc/ARSystem/midtier/tools
2. Assign execute permission to the cacheBackupUtility.sh file, as follows:
chmod 755 cacheBackupUtility.sh
3. Run the backup script and provide the backup directory name as the parameter.
For example: /cacheBackupUtility.sh /opt/cache_backup/
Using good copy of the cache

1. Ensure that the target mid tier, on which you want to use good copy of the cache, is not
running.
2. Copy the /opt/cache_backup/cache.tar from the first mid tier to the target mid tier and
extract it on the target mid tier. For example, use the following commands to copy and
extract the .tar file:
To copy:
scp /opt/cache_backup/cache.tar root@targetMidTier:/opt/cache_backup
To extract on the target mid tier:
cd /opt/cache_backup
tar -xvf cache.tar
3. Ensure that the path to the backup directory is set to /opt/cache_backup in the
arsystem.ehcache.midTierBackupCacheDir property.
4. Go to the target mid tier and delete the midTierInstallationDirectory/cache directory.
5. Start the mid tier which will automatically start using the good copy of the cache.
Related topics
Using cache with multi-tenant mid tier

With the introduction of multi-tenancy in midtier, there are additional cache categories introduced to
optimize the cache footprint by sharing common metadata across the AR System servers. This
helps improve scalability and performance of mid tier instance while using mid tier in multi-tenant
mode.
Page 657 of 4705
Home
If you are running the mid tier in multi-tenant mode, use the Sync Cache option over the Flush
Cache option to avoid removal of complete cache contents rather than just refreshing changed
objects in the cache. For information on using the sync cache, see Using the sync cache option.
Note
Always use Sync Cache option to get any of your metadata changes reflected in mid tier.
There should be no reason to use the Flush Cache option unless you see cache
corruption (such as EOFException) in the mid tier logs due to an unclean shutdown or
some other system issue. Using Flush cache hinders the mid tier performance as
compared to using Sync cache and the performance-related issues multiply when running
the mid tier in multi-tenant mode.
Avoiding abrupt shutdown of the mid tier

To avoid abrupt shutdown of the mid tier when you are running Tomcat on Microsoft Windows, you
need to do add a Registry setting and perform the following steps:
1. From the Services window, stop the Tomcat service.
2. Open the Windows registry, and navigate to HKEY_LOCAL_MACHINE > System >
CurrentControlSet > Control
3. Create a new DWORD Value.
4. Rename the property as ServicesPipeTimeout.
5. Double-click the property name, enter the value data as 120000 and select base as Decimal
.
6. Click OK.
Configuring the Report Settings page

The Report Settings page appears in the Mid Tier Configuration Tool and the AR Web
ReportViewer Configuration Tool. It enables you to configure report settings for BMC Remedy Mid
Tier and the AR Web ReportViewer. BMC Remedy Mid Tier uses the Reporting Working
Directory option for all report types, but the other settings on this page apply only to Crystal reports
.
The Report Settings page displays different options, depending on your installed configuration:
If the AR Web ReportViewer is installed with the mid tier, additional settings specific to
BusinessObjects Enterprise and Crystal Reports Server appear on the Report Settings
page in the Mid Tier Configuration Tool.
If the AR Web ReportViewer is installed without BMC Remedy Mid Tier, the AR Web
ReportViewer Configuration Tool is also installed. It is a subset of the Mid Tier Configuration
Tool that contains only those settings needed to configure the AR Web ReportViewer.
Page 658 of 4705
Home
This section describes all the possible settings on the Report Settings page. For additional
information about the AR Web ReportViewer and using BMC Remedy Mid Tier with Crystal reports,
see Using Crystal reports with BMC Remedy AR System .
If the AR Web ReportViewer is installed without the mid tier, you can access the AR Web
ReportViewer Configuration Tool from the BMC Software entry in the Windows Programs menu, or
by using the URL to configreport.jsp, for example, http://<ARWebReportViewerHost>/arreports
/shared/config/configreport.jsp.
Report Settings page with AR Web ReportViewer installed (all options)
Report Settings page parameters

The following table lists the parameters for the Report Settings page.
Report settings
Setting
Description
Crystal/BO
Report Engine
How you are deploying your BOXI or Crystal Reports report engine:
No Report Engine Select this if you are not using Crystal reports.
BOXI/Crystal Report Server on this machine This selection appears only when BMC Remedy Mid
Tier is installed on the Crystal reports server.
BOXI/Crystal Report Server on a different machine without a mid tier but with AR Web ReportViewer
installed.
BOXI/Crystal Report Server on a different machine with a mid tier.
Deployment (Mid
Tier
Configuration
Tool only)
Reporting
Working
Directory
The working directory where BMC Remedy Mid Tier deposits report definitions to be picked up by the
relevant report engine (Web, BMC Remedy AR System, or BOXI/Crystal). Enter the complete (absolute) path
BOXI/Crystal
Reports Server
Location (Mid
Tier
Configuration
Tool only)
The URL prefix, including the host name and port number, if any, used to access the mid tier or AR Web
ReportViewer on the BOXI or Crystal Reports server. For example, if the URL for BMC Remedy Mid Tier on
for this directory, for example: ARSystemInstallDir\midtier\reports If this directory is not under the web
server's root document directory, configure your web server with a virtual directory to point to this directory.
the BOXI or Crystal Reports server machine ishttp://<hostName>:8080/arsys/, enter http://<hostName>:

8080
If the context path is not arsys, then include the context path: http://<hostName>/<contextPath>or http://<
hostName>:<portNumber>/<contextPath>
CMS Machine
Name
Host name of the computer where the Crystal Reports Management server resides. Do not include the port
number.
Page 659 of 4705
Home
Setting
Description
CMS Machine
Connection
Details
The Crystal reports product you are using:

BusinessObjects Enterprise
Crystal Reports Server Select one of these products, and then enter the following information:
AR System ODBC Data Source Name The name of the system DSN.
If this field is blank, the default system DSN, AR System ODBC Data Source, is used. This is the
recommended configuration. (The ODBC driver is installed on the Crystal reports server when the mid tier or
AR Web ReportViewer is installed.)
CMS Folder Name (BusinessObjects Enterprise only) The name of the folder where the Crystal
reports are published.
CMS User Name and CMS Password (BusinessObjects Enterprise only) The user name and
password of a user with full administrator rights in the CMS. BMC Remedy Mid Tier uses this user
information to log on to the CMS and publish the reports.
Configuring the Web Service Settings page

The Web Service Settings page enables you to enter a user name and password for
authentication when accessing web services. If the AR System server allows guests, you do not
need to provide an Anonymous User Name or Anonymous Password on the Web Service
Settings page as long as the Username is passed in the AuthenticationInfo header of the web
service call.
If the web service call does not contain an AuthenticationInfo header, you must specify an
Anonymous User Name and Anonymous Password on the Web Service Settings page that is a
Remedy User Name. If the AR System server hosting the web service allows guest users, then the
Anonymous User Name of the Web Service Settings page must have an entry, but it does not
have to be an AR User ID.
For published web services used by AR System, user information such as user name, password,
and domain name are passed to the service through Simple Object Access Protocol (SOAP)
headers. If a user name and password cannot be found in the SOAP headers, the name and
password specified in these fields are used to connect to the server where the needed web service
resides. There is no default value for these fields.
Mid Tier Configuration Tool Web Service Settings page
Page 660 of 4705
Home
For more information, see Using Crystal reports with BMC Remedy AR System .
Configuring the Connection Settings page

Click the Connection Settings link in the left navigation pane to open the Connection Settings
page. It enables you to configure the load balancer between BMC Remedy Mid Tier servers and
the BMC Remedy AR System servers without a "sticky bit."
Note
BMC recommends configuring a load balancer between BMC Remedy Mid Tier servers
and the BMC Remedy AR System servers without using a "sticky bit" (session affinity).
If your system uses a hardware load balancer between BMC Remedy Mid Tier and BMC Remedy
AR System servers, make sure the Enable Lifespan check box is selected on the Connection
Settings page. This configuration allows sessions from any mid tier server to be distributed to any
BMC Remedy AR System server on the fly, and enables the system to rebalance in a timely
manner if a server is added to or removed from the system. This top group of settings facilitates
load rebalancing within a server group.
The settings on the Connection Settings page enable you to limit the number of proxy
connections and specify how long proxy connections can stay open. Whether the Connection
Lifespan or Connection Timeout setting is met first determines the number of current idle
connections, which is displayed in the Idle column in the Connection Pool Status area.
For more information, see Configuring a hardware load balancer with BMC Remedy AR System .
This section describes all the possible settings on the Connection Settings page.
Mid Tier Configuration Tool - Connection Settings page
The following sections provide detailed information about configuring the Connection Settings
page:
Page 661 of 4705
Home
Parameters to support load balancers between BMC Remedy Mid Tier and server group
without a sticky bit
Connection Pool Settings parameters
Connection Pool Status parameters
Parameters to support load balancers between BMC Remedy Mid Tier and server
group without a sticky bit
The following table lists the Connection Settings parameters which support load balancers
between BMC Remedy Mid Tier and server group without using a sticky bit:
Connection settings
Setting
Description
Enable
Lifespan
Specifies whether to enable the rebalancing of connection loads between BMC Remedy Mid Tier group and the
server group. If the check box is:
Selected any connection session open longer than the Connection Lifespan parameter value will be
reopened with a rebalanced load within the server group.
Cleared load balancing will not be enabled.
Connection
The amount of time (in minutes) that a connection will be load balanced after it is created. To prevent any load
Lifespan (
Minutes)
balancing on the connection, keep this parameter at its default value of 0. Whether the Connection Lifespan or
Connection Timeout setting is met first determines the number of current idle connections.
Balance
Now
Sets the Connection Lifespan to 5 minutes, temporarily for a 10 minute period, to quickly rebalance the connection loads
between BMC Remedy Mid Tier group and the server group. If an AR System server is down, the mid tier quickly routes
connections to functional AR System servers. It also starts rebalancing existing not-in-use connections that had the original
Connection Lifespan value. When the 10 minute period concludes, the connections then go back to their configured Connection
Lifespan value.
Connection Pool Settings parameters

The following table lists the Connection Pool Settings parameters:
Connection Pool settings
Setting
Description
Maximum
Connections
per Server
The maximum number of proxy connections that a connection pool can contain per server. If the number of
existing connections for the requested server does not exceed this value, a connection is allocated to that server.
Note
This setting is usually not changed from its default value, because it represents a pool of connections
and not the number of users who can connect to a BMC Remedy AR System server.
Page 662 of 4705
Home
Setting
Description
Connection
Timeout (
Minutes)
The amount of time (in minutes) that the pooled connections exceeding the Idle Connections per Server can be
idle before being terminated. This time limit makes sure that active pools routinely clean up their excess idle
connections. To prevent any idle pooled connections from terminating before the client shuts down, set this
parameter to 0. Whether the Connection Lifespan or Connection Timeout setting is met first determines the
number of current idle connections.
Idle
Connections
per Server
The maximum number of idle connections per server that are not subject to the Connection Timeout. These
connections are always available after they are established. The default value is 5. If the Idle Connections per
Server is set to 0, then the connection pool will be closed when all connections are closed.
Connection Pool Status parameters

The following table lists the Connection Pool Status settings parameters:
Connection Pool Status settings
Setting
Description
Pool Name
The host name and port number for the server hosting the connection pool.
In Use
The number of pooled proxy connections in use.
Idle
The number of established connections that are available in the connection pool.
Max Available
The maximum number of pooled proxy connections for this pool.
High Water Mark
The largest reached pool size.
Last Used
The datetime stamp when the pool was last used.
Created
The datetime stamp when the pool was created.
Configuring a mid tier to launch a browser in a different mid tier

This section describes how to configure a central mid tier to launch a browser on another mid tier.
Perform this procedure only after you have read and understood Multiple browser sessions in a
distributed mid tier environment.
If you use BMC Remedy ITSM Suite applications, see Registering hub and spoke servers.
Note
BMC recommends that you do not configure your central AR System server until you have
prepared a remote AR System server to be configured at the same time.
To configure a mid tier to render content in a different mid tier
Note
Page 663 of 4705
Home
Perform this procedure on the central server for each remote server that you are
configuring.
1. On the central AR System server, add a new server to the AR System Server to Key Map
form for the remote AR System server.
a. In the Server Name field, type the name of the server used for registering the remote
AR System server with the remote mid tier.
Note
If you enter the Fully Qualified Domain Name (FQDN) of the AR System
server, then make sure that the FQDN of the remote AR System server can
be resolved by using the domain name system (DNS) from the central mid
tier server and from the remote mid tier server.
If the FQDN of a remote AR System server is invalid, make sure the Server
Name value for the remote server is valid in the AR System Server to Key
Map form on the central server. Make sure the valid remote Server Name
can be resolved from outside the specific DNS.
b. In the Public Key field, copy the Public Key from the AR System Server to Key Map
form for the remote AR System server.
Make sure to click the expand box of the Public Key field, then copy the Public Key
into the expand box.
c. In the Web Path field, type the mid tier base URL for the remote mid tier.
If there is a load balancer situated between the browser and the remote mid tier, then
type the URL of the load balancer instead of the mid tier base URL.
Note
For improved security, BMC recommends using HTTP over SSL (HTTPS)
on all mid tiers. If a reverse proxy or load balancer is set up with HTTPS
protocol, and the mid tier server is set up with HTTP protocol, then the
transfer of information between these two servers is less secure. The less
secure transfer of information between the two servers is most likely limited
to within the secured intranet zone.
If higher security is needed with encryption at all levels, the mid tier server
can also be set up with HTTPS protocol. However, this might impair
performance to end users due to multiple levels of encryption and decryption
Page 664 of 4705
Home
.
If you configure multiple remote servers on the same reverse proxy, make
sure to configure those servers with name-based virtual hosting and not URI
path-based naming. For example, one central server and two remote
servers on a single reverse proxy would be named hub.eng.remedy.com,
spoke1.eng.remedy.com, and spoke2.eng.remedy.com. For details, see
Sample configuration of a single reverse proxy server .
2. Write a workflow that invokes an Open Window action on the remote AR System server. For
an example workflow, see the Scenario for creating an Open Window action workflow.
Note
You can only process a request in one session at a time. Therefore, click Open in New
Window only once and then process that request. If you log on to the remote server in
another browser window on the remote AR System server, and then close the new
window without logging off, you can receive an error while attempting to process a request
in the original session. This error is caused by concurrent sessions.
Scenario for creating an Open Window action workflow

This section provides a sample workflow for creating an active link on a test button with an Open
Window action.
1. Using SAMPLEDATA source, specify the following:
Sample Server Name as the central AR System server (such as arscentral.bmc.com)
Sample Form as User
Runtime Server Name as $Srv$
Runtime Form Name as $Form$
2. Set up Window Type as Submit.
3. Set up Target location as New.
4. Set the Login Name field (Field ID 101) to User.
5. Save the active link.

BMC Remedy Mid Tier uses cookies to define user sessions, encrypt data, and provide access to
features. The cookies are secure, provided that the secure cookie filter is enabled and the mid tier
is accessed through an HTTPS request. For more information, see General security guidelines.
Page 665 of 4705
Home
Note
All cookies used by the mid tier are required. When configuring the mid tier firewall, if you
do not accept cookies, BMC Remedy Mid Tier might not function correctly.
See the following table for a list of cookies used by BMC Remedy Mid Tier:
Cookie
Description
Lifespan
IP-Restriction GUID A persistent cookie used to track the user so that the
same user cannot log on from multiple computers
Persists for a day
GKW
Global Keywords Used to track the global keywords used by the mid tier
Deleted when the session times

out or the browser is closed
JSESSIONID
JSESSIONID An HTTP-only session cookie created by the application

server containing the encrypted data of the user session

Pop-up Blocker Indicates whether a pop-up blocker is to be shown or not

Session Tracker Used to track the total number of open windows

Window Used to display the name of the window
XXXXXXXXX
FC
Flash Cookie Used to hold the cookie data in a Flash or shared object

GF
Global Fields Used to track the values of global fields when the fields are
used across forms

LT
License Timeout Used to track when the license times out

ST
Session Timeout Used to track when the active session times out

Related topic
Settings in the config.properties file

This topic describes the properties in the config.properties file.
Note
When you modify any property, you must restart BMC Remedy Mid Tier for the changes
to take effect.
Page 666 of 4705
Home
Property name
Description
arsystem.session_timeout
Number of minutes for which the current logon session remains inactive.
When the time exceeds the arsystem.session_timeout value, you must
log on again.
Default value 90 minutes
arsystem.licenserelease_timeout
Number of seconds before BMC Remedy Mid Tier releases an AR System

license for a user, if the user does not log out of mid tier correctly
Note: To log out correctly, the user must close the last browser window
associated with the current HTTP session or navigate away from the mid
tier.
Default value 60 seconds
arsystem.password
Password to log on to the mid tier configuration tool
arsystem.arservers.<serverName>.
Password for an AR System account with administrative privileges. This

password must match the Mid Tier Administration Password on the
admin_password
Connection Settings tab in the AR System Administration: Server

Information form.
arsystem.arservers.<serverName>.domain
Domain name for the AR System server
arsystem.arservers.<serverName>.port
Port number that the user previously configured to access the AR System
server. If you have not configured a port number, leave this field blank.
arsystem.arservers.<serverName>.rpc
Remote Procedure Call (RPC) protocol number that the AR System server
uses. The RPC protocol number is used for connection to a private server.
If you have not configured an RPC number, leave this field blank.
arsystem.arservers.<serverName>.useshort
Indication that the BMC Remedy Mid Tier always uses the short name of an
AR System server
arsystem.arservers.<serverName>.preload
Indication that preloading of the forms has been enabled for this AR System
server
Values are:
true
false (default)
arsystem.preference_servers_list
Name of the AR System server designated as a preference server

If you need multiple preference servers to support different departments or
business units, you can specify multiple server names. When you enter
more than one preference server, the system searches the list until it finds
the first server that matches the user name and uses that server as the
preference server.
To add or update preference servers, enter the name of each server that
you want to designate as a preference server. To add multiple servers,
separate each server name with a comma.
Note: A fully qualified server name is not valid in this field.
arsystem.authentication_server
Page 667 of 4705
Home
Property name
Description
Server that the mid tier uses to authenticate a user. If an authentication
server is specified, the mid tier authenticates with the specified server. The
authentication server must already be in the list of mid tier servers on the
AR Server Settings page.
If an authentication server is not specified, you can perform the following
actions:
1. Log on with the preference server, if one is specified.
2. If there is no preference server, log in to the first server listed in the
AR Server list.
3. If that login is not successful, log in to the next server on the list. (A
guest login is considered a successful login.)
arsystem.arservers_list
List of AR System servers that are added to the selected mid tier on the AR
Server Settings page
arsystem.homepage_server
AR System server that contains the home page that you want to open when
the user logs on
The home page URL: http://midTierServer/contextPath/home
The home page server must be added to the list of mid tier servers in the
The mid tier searches the designated server for the home page. If you have
not selected a home page server in the AR System User Preference form,
the home page server specified in the AR Server Settings page is used
globally . A home page server specified in the AR System User Preferences
form takes precedence over the server set in the AR Server Settings page.
The form used for the home page has the following precedence on a
specific server:
1. A form designated in the AR System User Preference form.
2. The default home form designated in the AR System Administration:
Server Information form.
3. The default home page installed with BMC Remedy AR System.
arsystem.plugin_servers_list
Name of the AR System server designated as a data visualization module

server. You can specify additional servers as backup servers in case the
first module server goes down.
To add or update module servers, enter the name of each server you want
to designate as a module server. If you are adding more than one server,
separate each name with a comma.
Note: A fully qualified server name is not valid in this field.
arsystem.show_waiting_cursor
Indication that the wait cursor should be shown

Values are:
#mode 0 wait cursor off, content-based caching on
#mode 1 wait cursor on, content-based caching off
#mode 2 (default) semi-wait cursor, content-based caching on.
Page 668 of 4705
Home
Property name
Description
#mode 3 wait cursor off, content-based caching off
#mode 4 wait cursor on, content-based caching on
arsystem.log_level
Level of detail for logging information

Values are:
Fine The highest level of detail, including the client's IP address
Info Less detail than Fine, but includes the client's IP address
Warning A moderate level of detail. Warnings plus those errors
included in the Severe level are logged.
Severe (default) The lowest level of detail; only server start time
and error messages are logged
Note: You can see the pre-load start and end timestamp when you set the
log level to Info or Warning. Irrespective of the logging level, mid tier logs
the pre-load start and end time.
arsystem.log_viewer
Method by which you want to view the log files

Values are:
Console The log entries are directed to the stderr (System.err)
of your servlet engine.
File (default) Data is saved to a file in the specified log directory.
arsystem.log_category
Type of information that should be stored in the log file.

Values are:
Reporting Messages related to reporting
Cache Messages related to definitions, such as forms and active
links in the cache
Session Management Messages related to user session
construction and expiration, such as logon, logout, or timeout
Configuration Messages related to the config.properties file,
such as when it is loaded and changed
Flashboards Messages related to Flashboards
Web Services Messages related to web services
Field Messages related to fields
Workflow Messages related to compilation of workflow (primarily
active link actions), such as invalid active links
Performance Messages related to performance, including
duration of operations
Qualifications and Expressions Messages related to parsing
and compilation of expressions, for example, in active links
Servlet Messages related to servlet handling of http requests,
primarily for reporting results of back-channel requests
Internal Internal logging messages
ARServer (API/Filter/Database) Messages related to APIs, filters,
and databases. Selecting the ARServer (API/Filter/Database) option,
overrides the API logging option and all API logging is redirected to
the mid tier log file.
Data Visualization Module Messages related to the data
visualization module
Default value All categories except Flashboards are selected by default.
Page 669 of 4705
Home
Property name
Description
arsystem.log_format
Log output, which is generated using the standard Java 1.5 logging API,
including Simple and XML formatting. Values are:
FastText (default) A basic text file for faster performance, it does
not include stack trace information except in the case of Severe log
messages.
Text A text file containing details such as JAVA class names and
methods.
XML A file in XML format.
arsystem.log_filename
Name of the file with which the log file will be generated
Default value armidtier%g.log
arsystem.log_filepath
Directory in which the log files are stored

To change the log directory, enter the absolute (complete) path for the new
directory.
Note: You cannot change the log file name.
Default value C:\Program Files\BMC Software\ARSystem\midtier\
logs
arsystem.log_filesize
Maximum size (in kilobytes) a file can reach before a backup copy is
automatically made. When the log file reaches this limit, a backup copy is
made with the same file name and an incremental number (for example,
armidtierN.log).
Default value 10240 KB
arsystem.log_backups
Maximum number of backup files that the system will generate when the log
file size exceeds the limit specified in the Maximum Log File Size (
arsystem.log_filesize)
Default value 100 backups
arsystem.log_user
User name for which statements are logged

After you enter the user name and save changes, a new log file is started.
For log messages displayed on the screen, the filter applies only to new
entries. Older entries that existed before the user name was changed will
still be displayed on the screen, up to the limit set in the View Logs setting.
If the field is left blank, all logs related to the current session are stored,
regardless of who is logged in. You can enter only enter one name in this
field.
arsystem.pooling_max_
connections_per_server
Maximum number of connections in the AR System server JavaAPI

connection pooling
Default value 80
arsystem.use_connectionpooling
Indication whether the AR Server connection pooling should be used

Values are:
true (default)
false
Page 670 of 4705
Home
arsystem.cache_update_interval
Interval (in seconds) at which the cache information will be automatically

updated
Note: For Development cache mode, the value must be 0. For Production
cache mode, the value must be greater than 0.
arsystem.cache_update_needed
Indication that the cache is updated automatically. You can still update the
cache manually by clicking the Sync / Flush Cache button.
Values are:
On - (default) The cache is updated automatically at the interval that
you specify in the Definition Change Check Interval field.
Off - The cache is not updated automatically.
arsystem.crt_working_dir
Working directory where the BMC Remedy Mid Tier saves the report
definitions. These report definitions are collected by the relevant report
engine (Web, AR System, or BOXI/Crystal).
Enter the complete (absolute) path for this directory, for example:
ARSystemInstallDir\midtier\reports.
If this directory is not under the web servers root document directory, you
must configure your web server with a virtual directory to point to this
directory.
Default value C:\Program Files\BMC Software\ARSystem1\midtier\
reports
arsystem.crtXI_location
URL prefix, including the host name and port number, if any, that is used to
access the mid tier or AR Web ReportViewer on the BOXI or Crystal
Reports server
For example, if the URL for the BMC Remedy Mid Tier on the BOXI or
Crystal Reports server machine is http:// hostName:8080/arsys/, enter http://
hostName:8080.
If the context path is not arsys, then include the context path: http://
hostName/contextPath or http://hostName:portNumber/contextPath
arsystem.ws_anonymous_user
User name for an anonymous web service user
arsystem.ws_anonymous_pwd
Password for an anonymous web service user
arsystem.browser_version_error
Flag that indicates whether browser version error message is on or off

If you use an unsupported browser, you can use this setting to turn the
error message on or off.
Values are:
On (default)
Off
arsystem.authenticator
Page 671 of 4705
Home
Property name
Description
Fully qualified class name of the login authentication module to be used,
such as DefaultAuthentication or AtriumSSOAuthenticator
Default value com.remedy.arsys.session.DefaultAuthenticator
arsystem.authenticator.sso.enckey
Encryption key, if SSO Authentication is used
ardev.webwriter.comments
Comments that are added to the generated HTML that is cached by the mid
tier to make the workflow debugger output more readable
Values are:
true
false (default)
ardev.webwriter.whitespace
White space that is added to comments in the generated HTML that is

cached by mid tier to make the workflow debugger output more readable
Values are:
true
false (default)
ardev.webwriter.indent
Indentation that is added to comments in the generated HTML that is

cached by mid tier to make workflow debugger output more readable
Values are:
true
false (default)
ardev.jswriter.comments
Comments that are added in the generated JS that is cached by mid tier to
make workflow debugger output more readable
Values are:
true
false (default)
ardev.jswriter.whitespace
White space that is added in the generated JS that is cached by mid tier to
Values are:
true
false (default)
ardev.jswriter.indent
Indentation that is added in the generated JS that is cached by mid tier to

Values are:
true
false (default)
ardev.allow_unconfigured_servers
Indication that server information for an AR System server that is not

configured in mid tier can be retrieved
Page 672 of 4705
Home
Property name
Description
Values are:
true
false (default)
arsystem.js_profile
Indication that the javascript generated from active links should be profiled
and shown in the workflow logs
Values are:
true
false (default)
arsystem.image.spinnerup
Name of the image from resources folder to use as the UP spinner for an
integer field
Default value mt_sprites.gif
arsystem.image.spinnerdown
Name of the image from resources folder to use as the DOWN spinner for
an integer field
arsystem.image.diary
Name of the image from resources folder to use as an icon for a diary field
Default value field_diary_empty.gif
arsystem.image.calendar
Name of the image from resources folder to use as an icon for a calendar
arsystem.image.currency
Name of the image from resources folder to use as an icon for a currency
field
arsystem.image.menu
Name of the image from resources folder to use as an icon for a menu
arsystem.image.text
Name of the image from resources folder to use as an icon for a character
field
arsystem.image.time
Name of the image from resources folder to use as an icon for a time field
arsystem.image.tablechunkleft
Name of the image from resources folder to use as an icon for a left chunk
image in a table field
Default value chunking_sprite.png
arsystem.image.tablechunkdown
Name of the image from resources folder to use as an icon for a down
chunk image in a table field
Default value menu_down.gif
Page 673 of 4705
Home
Property name
Description
arsystem.image.tablechunkright
Name of the image from resources folder to use as an icon for a right chunk
image in a table field
arsystem.image.open
Name of the image from resources folder to use as an icon for a file upload
button
arsystem.image.edit
Name of the image from resources folder to use as an icon for an edit
button
Default value field_edit.gif
arsystem.image.rtf
Name of the image from resources folder to use as an icon for an RTF
button
Default value field_rtf.gif
arsystem.flash.image.spinnerup
Name of the image from resources folder to show UP spinner for an integer
field in flashboards
Default value spinner_up.gif
arsystem.flash.image.spinnerdown
Name of the image from resources folder to show DOWN spinner for an
integer field in flashboards
Default value spinner_down.gif
arsystem.flash.image.diary
Name of the image from resources folder to be shown as an icon for a diary
Default value field_diary_empty.gif
arsystem.flash.image.calendar
Name of the image from resources folder to be shown as an icon for a

calendar in flashboards
Default value field_calender.gif
arsystem.flash.image.currency

currency field in flashboards
Default value field_currency.gif
arsystem.flash.image.menu

menu in flashboards
Default value field_menu.gif
arsystem.flash.image.text

character field in flashboards
Default value field_text.gif
arsystem.flash.image.time
Name of the image from resources folder to be shown as an icon for a time
Default value field_time.gif
Page 674 of 4705
Home
Property name
Description
arsystem.flash.image.tablechunkleft
Name of the image from resources folder to be shown as an icon for left
chunk image in a table field in flashboards
arsystem.flash.image.tablechunkdown
Name of the image from resources folder to be shown as an icon for down
Default value menu_down.gif
arsystem.flash.image.tablechunkright
Name of the image from resources folder to be shown as an icon for right
arsystem.flash.image.open
Name of the image from resources folder to be shown as an icon for file
upload button in flashboards
Default value field_open.gif
arsystem.scale_factor_X
Amount of space to be left for setting margins in table cells

Default value 1
arsystem.scale_factor_Y
Amount of space to be left for setting margins in table cells

Default value 1
arsystem.enableHttpTrace
Flag that enables recording of an http trace by a web server for every
request in mid tier
Values are:
true (default)
false
arsystem.resource_expiry_interval
Time limit (in seconds) for which resources (such as images, . css files, and
JavaScript files) can be used
If you close a form and open it again within the specified expiry time, the
image is cached and is not downloaded again. This helps increase the
performance of mid tier.
arsystem.formhtmljs_expiry_interval
Time limit (in seconds) for which a form's generated html and JS data can
be used
If you close a form and open it again within the specified expiry time, the
html and JS data is cached and is not downloaded again. This helps
increase the performance of mid tier.
arsystem.enableContentCompression
Page 675 of 4705
Home
Property name
Description
Flag that enables content compression for userdata.js and AppList.html.
This property helps improve the performance of mid tier especially when a
large amount of data returned by these files.
Values are:
true (default)
false
arsystem.prefer_native_views
Default view, standard or web view, for the view type selection
Note: This setting is evaluated when the system progresses through the
view selection algorithm.
If no view is specified and the Prefer Standard/Windows Views check box
is:
true The browser displays the standard view of the form.
false (default) The browser displays the web view of the form, if
one is available. If no web view is available, the standard view is
displayed.
arsystem.enableBackChannelCompression
Flag that enables the content compression for the html and JS data
returned from the backchannel calls. This property helps improve mid tier
performance when a large amount of data is returned.
Values are:
true (default)
false
arsystem.ehcache.overflowToDisk
Flag that indicates whether the mid tier cache persists items to disk so that
they survive between JVM restarts
Note: If you enable this setting, BMC recommends that you disable the
arsystem.ehcache.overflowToDiskTemp setting to avoid possible
duplication of cache items on disk when mid tier is running.
Values are:
true (default)
false
arsystem.ehcache.overflowToDiskTemp
Flag that indicates whether the mid tier cache can overflow cache items
temporarily to disk
These cache items do not survive between JVM restarts. To maintain cache
items between JVM restarts, set the value of the
arsystem.ehcache.overflowToDisk property to true and set the value of
this property to false.
Note: Setting this property to True might create duplicate cache items.
Values are:
Page 676 of 4705
Home
Property name
Description
true
false (default)
arsystem.ehcache.maxElementsOnDisk
Maximum number of objects to be kept in the mid tier cache's disk storage
Default value 2147483647
arsystem.ehcache.diskcache.maxElements
InMemory
Maximum number of objects to be kept in memory for the disk cache

component of the mid tier cache. When the number of total objects in the
disk cache goes beyond this limit, these objects are stored on the disk.
Default value 1
arsystem.ehcache.memoryStoreEvictionPolicy
Policy with which objects are swapped between memory and disk
Default value LRU
arsystem.ehcache.midTierCacheDir
Indication that when the arsystem.ehcache.midTierCacheDir setting is

blank, the default cache for BMC Remedy Mid Tier is the mid tier
installation directory or cache.
arsystem.ehcache.midTierCacheTempDir
Indication that when the arsystem.ehcache.midTierCacheTempDir

setting is blank, the default temporary cache for BMC Remedy Mid Tier is
the mid tier installation directory or cache.
arsystem.ehcache.referenceMaxElements
InMemory
Default maximum elements in the memory

You can use this property to override the
arsystem.ehcache.maxElementsInMemory setting.
Default value 1250
arsystem.ehcache.referenceMaxElementsIn
Default maximum element weight for form images cache
MemoryWeight.formImages
To get the exact number of objects in the memory, you must multiply the
value of this setting with the value of the
arsystem.ehcache.referenceMaxElementsInMemory setting.
Default value 0.104
arsystem.ehcache.referenceMaxElementsIn
MemoryWeight.activeLinks
Default maximum element weight for activelinks cache

Default value 4.904
InMemoryWeight.groups
Default maximum element weight for groups cache

Default value 0.025
InMemoryWeight.roles
Page 677 of 4705
Home
Property name
Description
Default maximum element weight for roles cache
Default value 0.036
Default maximum element weight for JS cache
InMemoryWeight.js
Default value 0.195
Default maximum element weight for displayed fields cache
InMemoryWeight.displayedFields
Default value 0.157
Default maximum element weight for fieldmaps cache
InMemoryWeight.fieldMaps
Default value 0.323
Default maximum element weight for sysdata cache
InMemoryWeight.sysdata
Default value 1.202
Default maximum element weight for compiled forms cache
InMemoryWeight.compiledForms
Default value 1.14
Default maximum element weight for forms cache
InMemoryWeight.forms
Default value 0.4
Page 678 of 4705
Home
Property name
Description
Default maximum element weight for html cache
InMemoryWeight.html
Default value 0.195
Default maximum element weight for form fields images cache
InMemoryWeight.formFields
Default value 8.577
Default maximum element weight for shared resources cache
InMemoryWeight.sharedResources
Default value 0.1
Default maximum element weight for sync relationships cache
InMemoryWeight.syncRelationships
Default value 0.4
Default maximum element weight for actor view cache
InMemoryWeight.actorViews
Default value 0.32
Default maximum element weight for actor views mapping cache
InMemoryWeight.actorViewsMapping
Default value 0.32
Default maximum element weight for hash cache
InMemoryWeight.hashCache
Default value 200
Default maximum element weight for ref count cache
Page 679 of 4705
Home
Property name
Description
InMemoryWeight.refCount
Default value 0.4
arsystem.ehcache.peerListener.scheme
Replication scheme with which the selected listeners interact. Each peer
provider has a scheme name that can be used by caches to specify a
replication type.
Values are:
RMI (default)
JMS
Jgroups
Note: This setting is used by ehCache internally.
arsystem.ehcache.enableStats
Flag that indicates whether the cache statistics records cache hits and
misses
Values are:
true
false (default)
arsystem.enable_Animation
Flag that indicates whether animation in Javascript should be enabled. This

applies to animations, such as open dialog and flashboard.
Values are:
true (default)
false
arsystem.xmlhttp.get
Flag that indicates whether the AJAX calls made within the Backchannel
requests use the http GET or POST method while sending requests to BMC
Remedy Mid Tier
Values are:
true (default) Requests are sent by using the GET method
false Requests are sent by using the POST method
arsystem.windowiis.installed
Flag that indicates whether mid tier is running on the IIS server. This setting
is used to display the information on the configuration overview page.
Values are:
true
false (default)
flashboards.showgraphinflash
Indication that charts are drawn by.using either Flash (interactive) or

JFreeChart (image) in FlashboardsDefault value 1
flashboards.min_flex_width
Page 680 of 4705
Home
Property name
Description
Minimum width of a chart in Flashboards
Default value 260
flashboards.min_flex_height
Minimum height of a chart in Flashboards

Default value 200
arsystem.searches.maxAllowed
Maximum number of search qualifications that can be stored for a user

Default value 90
arsystem.enableMidTierPerfMBean
Flag that indicates whether the mid tier performance Mbean is deployed on
startup and whether mid tier can provide additional monitoring parameters
through JMX
Values are:
true
false (default)
arsystem.max_number_of_prefetch_thread
Maximum number of threads spawned during the preload operation. This

parameter is per AR System server.
Default value 4
arsystem.response.hostip
Flag that indicates whether the ARRESPONSEHOSTIP header is added to

every response that goes out from the mid tier
Values are:
true Adds the header to every response, with the value as client
IP address. This header can be used in load balancer or other
proxies to create rules.
false (default) Does not add the header.
arsystem.allow.returnback.url
Flag that indicates whether direct access URL through LoginServlet is

allowed
Values are:
true (default)
false
arsystem.daemonthread_priority
Priority for the daemon threads spawned from BMC Remedy Mid Tier for
background threads, such as preload and synch
Default value 4
arsystem.serverinfo.alertschema.update.interval
Time interval to verify whether the server information cached in mid tier is
considered old. If this value is reached or exceeded, the server information
is recached.
Default value 604800
arsystem.plugin_securitycheck
Flag that indicates whether the cross-site script attack detection should be
checked for plugins
Page 681 of 4705
Home
Property name
Description
Values are:
true (default)
false
arsystem.use_connectionpooling
Flag that indicates whether to use connection pooling for the AR System
server
Values are:
true (default)
false
arsystem.flash.detect_flashplayer
Flag that indicates whether the validation for the flash plugin in the browser
should be performed on the login page
Values are:
true (default)
false
arsystem.maxRetrieveForAutoCompleteMenu
Maximum number of items returned from a menu expand query

Default value 300
arsystem.autoCompleteTypingTimeout
Timeout value for the auto complete functionality after which the auto
complete menu will disappear
Default value 400
arsystem.min_entries_for_streaming
Minimum number of entries retrieved in a native report after which the

information is transferred to the browser
Default value 1000
arsystem.flash.enable_ui_rendering
Flag that indicates whether the HTML user interface should be rendered by
using flash objects or simple HTML and images
Values are:
true (default)
false
arsystem.emit_X_UA_compatible_mode
Flag that indicates whether to emit compatible mode for browsers

Values are:
true (default)
false
arsystem.nativereport.onscreen_max_entries
Maximum number of entries that will be displayed on the screen for native
reports
Default value 2000
arsystem.FileExport_max_entries
Maximum number of entries that will be displayed for native reports while
exporting to a file
Page 682 of 4705
Home
Property name
Description
Default value 2000
arsystem.webreport.onscreen_max_entries
Maximum number of entries that will be displayed on the screen for web (
BIRT) reports
Default value 2000
arsystem.objectlist
Flag that indicates whether the object list is enabled on mid tier
Values are:
true (default)
false
Note: When set to true, ensure that the corresponding form to display
object the list is imported on the AR System server.
arsystem.enableSkins
Flag that indicates whether skins are enabled on the mid tier
Values are:
true (default)
false
arsystem.inclusion_attachment_extensions
Comma-separated list of all file extensions that are allowed for attachments
arsystem.inclusion_goto_urls
Comma-separated list of URLs that are allowed in the goto request

parameter of LoginServlet and LogoutServlet so that the user is
automatically redirected to the specified URL
arsystem.myreport.report_cache_limit
Maximum number of reports that will be saved for quick reports

Default value 20
arsys.arf.atssoconfirmpwd
Plugin used by the BMC Remedy AR System server to fetch the user
password information from the BMC Atrium Single Sign-On (SSO) server.

You must set up a cluster with multiple tenants in the following circumstances:
Creating a new cluster environment
Migrating to a cluster environment
Setting up new hardware
Testing a cluster for performance
Before you begin

Ensure that the following prerequisites are met:
Mid tiers are configured in a cluster.
Optionally, Centralized Configuration Server is configured.
Tenant AR Configuration servers are configured in the mid tier.
Page 683 of 4705
Home
Recommendations
Set the Maximum Heap Size property value based on the number of tenants. For example,
if you are setting up a cluster with 8 tenants, ensure that the Maximum Heap Size is 6 GB for
all the mid tiers in the cluster.
Change the arsystem.ehcache.referenceMaxElementsInMemory property value ( located
at C:\Program Files\BMC Software\ARSystem\midtier\WEB-INF\classes\
config.properties ) based on the number of tenants. For example, for 8 tenants, set the
value of this property to 14000. For more information, see JVM runtime analysis.
For information on other recommendations, see < white_paper_TBD>.
To set up a cluster with multiple tenants

1. Ensure that only one mid tier is up and running in the cluster.
2. Enable preload for all Tenant AR Configuration servers on this mid tier.
3. Start the preload for all Tenant AR Configuration servers by clicking the Preload button for
each of the Tenant AR Configuration server on the Cache Settings page.
Note
Preload is a time-intensive process. It might approximately take an hour for the
preload to complete for all tenants. For example, if you have 8 tenants, preload
takes an hour to complete on all the tenants.
4. Verify that the preload is completed successfully for all Tenant AR Configuration servers.
Note
Page 684 of 4705
Home
If any one of preload statuses is Aborted, start preload again for that Tenant AR
Configuration server by clicking the Preload button.
5. Wait for the mid tier CPU to almost reach to 0%.

6. Disable preload on all Tenant AR Configuration servers by clearing the Pre-load check box
on the AR Server Settings > Edit AR Server page.
7. Gracefully shut down Tomcat.
Warning
Do not kill the Tomcat process. As an example, for 8 tenants, it takes about 10
minutes to shut down Tomcat.
8. Verify whether the shut down status shutdown_completed appears in the <
midtierInstallation>/cache.lck file.
9. Use the cache Backup utility to back up and restore the good cache on other mid tiers in the
cluster.
Related topics
Configuring a hardware load balancer with

High-load environments present special issues relating to performance, hardware capacity, system
downtime, and so on. A high-load environment presents two major issues:
System scalability is dependent upon the capacity of the hardware. If the existing hardware
is at its limit, it needs to be replaced by bigger, more powerful hardware. New hardware is
often much more expensive than existing hardware. The old hardware could only be used as
a "hot" standby system. (A hot standby system is running and ready for immediate service. It
can be switched into service manually or automatically upon detection of a failure in the
active equipment.)
The system needs to be available for as much time as possible. This can be challenging and
often requires redundant systems. The backup system is often in hot standby mode and is
only activated in the event of an outage. Only one system can be used in production.
Page 685 of 4705
Home
The solution to both challenges is a technology commonly used in the web environment a load
balancer. You can use a hardware load balancer to improve the scalability and availability of BMC
Remedy Action Request System (AR System) servers.
A load balancer is a valuable component in building a scalable, highly available BMC Remedy AR
System infrastructure. Scalability is achieved through the ability to add BMC Remedy AR System
servers as demand and workload increase. High availability is achieved by configuring multiple
BMC Remedy AR System servers to handle client requests, and if one server fails, other servers in
the group handle the additional workload. By creating an infrastructure that scales with workload
and reduces downtime, you can maximize the return on your BMC Remedy AR System investment.
This section provides the following topics to help you understand how to use a hardware load
balancer to improve the scalability and availability of the BMC Remedy AR System:
What a load balancer does
How load balancers route requests
Considerations for configuring load balancers with AR System servers
Using a load balancer with server groups
Load balancer configuration examples
Sample load-balancer- Cisco 11500 Series Content Services Switch
Special considerations and known issues
What a load balancer does

A load balancer is a transparent network device that distributes the traffic from multiple clients to
several servers, preventing BMC Remedy AR System servers from becoming overloaded.
Distributing workload among several BMC Remedy AR System servers can lead to performance
benefits and cost savings. Buying many smaller machines is far less expensive than paying for a
single high-performance machine. Since load balancers redirect incoming traffic, they are
sometimes referred to as redirectors.
A load balancer also provides high availability through redundancy and fail-over protection.
Fail-over is the process of moving operations from one server to another upon service or machine
failure. If one BMC Remedy AR System server becomes unavailable for software reasons or if the
machine hardware fails, other BMC Remedy AR System servers in the group (or cluster) can take
over the workload. Users will not be aware of any problems, nor will they experience any downtime.
Most load balancers work on the TCP level of the network protocol and can therefore balance the
load of many applications that use this protocol. Some examples include HTTP, FTP, and the BMC
Remedy AR System server. The load balancer is transparent to users, so the client application
cannot see it and is unaware that the client requests are being load-balanced.
Page 686 of 4705
Home
You can think of the load balancer as a virtual system, or as a super BMC Remedy AR System
server in this case. The load balancer is given a virtual IP address and a DNS name, either of
which is used by BMC Remedy Mid Tier clients when connecting to the group of load-balanced
BMC Remedy AR System servers. Both the short and long DNS names must be resolvable. (Long
DNS names are fully qualified with a domain.) When a client request is received, the load balancer
passes the request to one of the actual BMC Remedy AR System servers within the group. The
chosen BMC Remedy AR System server performs the work and sends the results to the client. This
balancing of connections spreads out the client requests evenly and distributes the load.
Note
For performance reasons, the BMC Remedy AR System API clients establish a
connection with the BMC Remedy AR System server and keep the connection until the
session is terminated or the connection is interrupted.
How load balancers route requests

Load balancers forward data packets in the same manner as Network Address Translation (NAT)
devices. The packets are forwarded at the TCP level with modified address information to the target
system.
To distribute client requests across each group of BMC Remedy AR System servers, the load
balancer can use various scheduling policies. The following two policies are the most common:
Round Robin This policy directs client requests to each BMC Remedy AR System server
, one at a time. Successive requests are routed to the next BMC Remedy AR System server,
then the next, and this process is repeated consecutively.
Least Connections This policy directs client requests to the BMC Remedy AR System
server that has the fewest connections.
For better throughput, most load balancers offer multiple network ports. This method avoids
collisions between the incoming and outgoing routed network traffic.
The load balancer also offers clients the ability to stick to one target system. This means that all
requests from a single client are routed to the same system.
For versions 7.6.04 or later, BMC recommends configuring the load balancer that is located
between the web servers and BMC Remedy AR System servers without setting a "sticky" bit. In
versions earlier than 7.6.04, BMC recommended setting the sticky bit to activate session affinity to
route all connections from one web server to the same BMC Remedy AR System server. For more
information, see Scenarios for load balancing between the web servers and BMC Remedy AR
System servers.
Page 687 of 4705
Home
Note
If you use other BMC products that also support load balancing without setting the "sticky"
bit, make sure your BMC Remedy AR System server and other BMC product(s) use the
same version. For example, BMC Atrium CMDB supports configuring the load balancer
without setting a "sticky" bit for version 7.6.04 Service Pack 1 or later, and does not
support it for version 7.6.04. If you configure load balancing without setting a "sticky" bit
for both of these products, your BMC Remedy AR System server must also use the
matching 7.6.04 SP1 or later version.
Considerations for configuring load balancers with AR System

servers
The load balancer acts like a NAT device that routes any TCP or UDP traffic. Since the AR System
server uses an ONC-RPC implementation that is layered on top of TCP/IP, AR System server
traffic can be load balanced. Because of the nature of the client/server interaction within BMC
Remedy AR System, setting the sticky bit is not required. While the sticky bit allows for the
spreading of the workload from multiple clients, it does reduce the balancing that can occur.
BMC Remedy AR System includes the capability for automatic fail-over of special operations and
the sharing of floating licenses among the servers. Server groups are independent of load
balancing, but the concepts are complementary.
To enable load balancing across multiple AR System servers, configure each server as outlined in
Using a load balancer with server groups

The load balancer acts like a NAT device that routes any TCP or UDP traffic. Since the AR System
server uses an ONC-RPC implementation that is layered on top of TCP/IP, AR System server
traffic can be load balanced. Server groups are independent of load balancing, but the concepts are
complementary.
You can run multiple AR System servers in a cluster and distribute the load between them with a
third-party load balancer. All of these instances work on the same database, so they are always in
sync. This is a typical server group configuration. This clustered environment creates a highly
scalable and highly available AR System installation.
The servers in a server group can be given different responsibilities (such as one handing
approvals, another escalations, etc). The servers in the group are aware of each other, and if one
of the servers fails, another can take over its responsibilities
Page 688 of 4705
Home
When installing applications in a server group environment, install all of the software on
each computer before setting up the server group. This is necessary because the installer
creates required configuration file entries, creates all required folders, and puts all the
binary files in place. After installing the software, add each server to the server group, and
configure the load balancer to distribute load among these instances.
The example below uses a load balancer to direct traffic to a server group of three AR System
servers. In the following figure, the uppermost AR System server has the primary ranking for the
Administration and Escalation operations. The other two AR System servers can be used to back
up these operations, when the uppermost server is not running.
Basic load-balancer configuration with multiple AR System servers
For more information, see Configuring a hardware load balancer with BMC Remedy AR System .
Note
If the load balancer belongs to a different domain than the AR System servers, then the
fully qualified domain name of the Server-Name alias will be wrong. In this case, the
domain name parameter should be specified in the ar.cfg file for each AR System server
using the domain of the load balancer.
Tip
Page 689 of 4705
Home
When a firewall or a load balancer exists between clients and AR System servers, you
must set the TCP "keep alive" value properly. The operating system of the host BMC
Remedy AR System server maintains the keep-alive socket (not the client). Ensure that
the keep-alive value on the firewall or load balancer is at least as long as or longer than
the keep-alive value on the largest host server of all AR System servers connected to the
firewall or load balancer.
Load balancer configuration examples

The following sections describe a number of common configuration examples. All configurations
require that BMC Remedy AR System servers have been properly configured.
Configuring a load balancer with multiple AR System servers
Configuring a load balancer with a firewall and multiple AR System servers
Configuring a load balancer with a firewall, web servers, and multiple AR System servers
Configuring a load balancer with a firewall, web servers, a second load balancer, and
multiple AR System servers
Verify that the following configuration steps have been completed before you review the examples:
1. All BMC Remedy AR System servers share the same database.
2. All BMC Remedy AR System servers have the same server name (server name alias), and
they have a unique name configured for server-to-server communication.
3. All BMC Remedy AR System plug-ins are configured to access the local server.
4. All BMC Remedy AR System servers are configured to listen on TCP ports that the load
balancer is configured for.
5. External operations managed by the server group (such as Email Engine and Flashboards)
must be must be installed locally on the BMC Remedy AR System servers that manage
them.
6. BMC Remedy Alert is configured for a load-balanced environment.
The load-balancer IP address is mapped to the BMC Remedy AR System server IP
address.
The server is configured to ignore the actual IP address recorded during Alert client
registration.
7. Distributed Server Option (DSO) is configured for a load-balanced environment.
Mappings have been updated to take advantage of the server group.
8. Full text search (FTS) is configured for a load-balanced environment.
The index collection directory is accessible to all BMC Remedy AR System servers in the
group.
9. Clients are configured to use the virtual address and port of the load balancer.
10. Servers are declared to be server group members, and operation rankings are configured.
Page 690 of 4705
Home
Configuring a load balancer with multiple AR System servers

In this example, the load balancer is directing traffic to three BMC Remedy AR System servers that
share a single database. In the following figure, the uppermost server has the primary ranking for
the Administration and Escalation operations. The other two servers can be used to back up these
operations, when the uppermost server is not running.
Basic load-balancer configuration with multiple AR System servers
Configuring a load balancer with a firewall and multiple AR System servers

In this example, client requests pass through a firewall and into the load balancer. The load
balancer directs traffic to three BMC Remedy AR System servers. The three servers share a single
database.
In the following figure, the uppermost server has the primary ranking for the administration
operation, but the bottommost server has the primary ranking for the escalation operation. As
mentioned earlier, the administrative server can be a computer other than the escalation server.
Load-balancer configuration with a firewall and AR System servers
In the following figure, AR System server client traffic comes into the firewall on TCP port 3030 and
is directed to the load balancer. The load balancer routes this traffic to one of the BMC Remedy AR
System servers listening on port 2020. As shown in the diagram, the port number for the virtual
address can be different from the port numbers for the real BMC Remedy AR System servers.
Page 691 of 4705
Home
Load-balancer configuration with a firewall, a virtual AR System server, and real AR System
servers
Configuring a load balancer with a firewall, web servers, and multiple AR System
servers
In this example, client requests pass through a firewall and into the load balancer. The load
balancer directs the web requests to three web servers. The web servers access the BMC Remedy
AR System servers to fulfill BMC Remedy AR System requests. The three servers share a single
database, as shown in the following figure.
Load-balancer configuration with a firewall, web servers, and AR System servers
Using the hosts file, the IP address of the AR System server needs to be resolved manually on
each web server. This is necessary because all web servers reference the same AR System server
name; however, each web server is linked to a different AR System server, and each AR System
server has a different IP address. If the server name was resolved using a DNS server, this server
name would resolve to the same IP address and all the web servers would communicate with the
same AR System server. Therefore, each web server uses the hosts file, and manually resolves the
AR System server name to the appropriate server.
On Windows platforms, the hosts file is located in the %WINDIR%\system32\ drivers\etc directory
. On UNIX, the hosts file is located in the /etc directory.
The hosts file on Web 1 should include the following line: myarserver 11.40.35.47
The hosts file for Web 2 should include the following line: myarserver 11.40.35.49
The hosts file for Web 3 should include the following line: myarserver 11.40.35.51
In the preceding sample hosts files, myarserver is the AR System server name that all the web
servers reference.
Page 692 of 4705
Home
Configuring a load balancer with a firewall, web servers, a second load balancer,
and multiple AR System servers
In this example, client requests pass through a firewall and into a load balancer. The first load
balancer directs web requests to the web servers. Web server requests to the BMC Remedy AR
System servers are directed through a second load balancer. The three servers share a single
database, as shown in the following figure.
Load-balancer configuration with a firewall, web servers, AR System servers, and two load
balancers
Notes
For versions 7.6.04 or later, BMC recommends configuring the load balancer that is
located between the web servers and BMC Remedy AR System servers without setting a
sticky bit. In versions earlier than 7.6.04, BMC recommended setting the sticky bit to
activate session affinity to route all connections from one web server to the same BMC
Remedy AR System server. For more information, see Scenarios for load balancing
between the web servers and BMC Remedy AR System servers .
for both of these products, your AR System server must also use the matching 7.6.04 SP1
or later version.
This type of configuration can also be used with a WAN, DMZ, or LAN as shown in the following
figure. Client requests pass through the firewall and into the first load balancer. The load balancer
routes the traffic to one of the web servers. BMC Remedy AR System requests from the web
servers pass through the first load balancer, then through the firewall, and finally to the second load
balancer. The second load balancer then routes the request to one of the BMC Remedy AR
Page 693 of 4705
Home
System servers in the group.

Load-balancer configuration with a WAN, a firewall, web servers, AR System servers, and
two load balancers
For better throughput, such as might be required in a high-performance environment, you can add
a second firewall, as shown in the following figure. AR System server traffic from the web servers is
routed through the second firewall. AR System server traffic from web servers follows a different
route from that of incoming BMC Remedy AR System client requests, thereby reducing the
likelihood of a network bottleneck in the load balancer.
Load-balancer configuration with a WAN, two firewalls, web servers, AR System servers,
and two load balancers
Page 694 of 4705
Home
Sample load-balancer- Cisco 11500 Series Content Services

Switch
The BMC Software Quality Assurance department tested a load-balancing configuration using the
Cisco 11500 Series Content Services Switch (CSS) with software version WebNS 4.10, 5, 6, 7,
build 17s. The two BMC Remedy AR System servers shared a database on another computer, as
shown in the following figure. Specific ports were not defined, and the default setting (ON) was
used for the persistence (sticky) option. The default setting of round robin was used for our
load-balancing technique.
Load-balancer configuration tested by BMC Software
The following configuration was used for the CSS appliance:
!*************************** GLOBAL ***************************

username admin1 des-password <encrypted_password> superuser
ip route 0.0.0.0 0.0.0.0 172.23.32.1 1
!************************* INTERFACE *************************
interface e5
bridge vlan 10
interface e6
bridge vlan 20
!************************** CIRCUIT **************************
circuit VLAN10
ip address 172.23.32.15 255.255.248.0
circuit VLAN20
ip address 172.23.41.5 255.255.255.0
!************************** SERVICE **************************
service www-server1
ip address 172.23.41.15
active
service www-server2
ip address 172.23.41.16
active
!*************************** OWNER ***************************
owner sample
content rule1
add service www-server1
add service www-server2
Page 695 of 4705
Home
vip address 172.23.33.95

active
For information about how to configure a load balancer with the Cisco CSS, see the Cisco Systems
website at http://www.cisco.com. The following documents are relevant to load-balancer
configuration:
"Basic CSS Load Balancing Configuration," Document ID 12557, http://www.cisco.com/en/
US/products/hw/contnetw/ps792/products_configuration_example09186a008009438d.shtml
"CSS Basic Configuration Guide," Text Part Number 78-13886-05, http://www.cisco.com/en/
US/docs/app_ntwk_services/data_center_app_services/css11500series/v7.20/configuration/
basic/guide/basicgd.pdf
Note
Website addresses change frequently. If you have difficulty finding these documents, go
to http://www.cisco.com and navigate to the Documentation pages.
Special considerations and known issues

The following topics provide information about situations you might encounter, as well as
descriptions of issues that have been identified with respect to using a load balancer with BMC
Remedy AR System.
Fail-over of escalation and archive operations
Scenarios for load balancing between the web servers and BMC Remedy AR System
servers
Load balancing between the clients and web servers without setting a sticky bit
Server configuration sharing
Licensing servers in a multiple-server environment
Fail-over of escalation and archive operations

If an escalation or archive operation results in a fail-over from one server to another, escalations or
archives running at a fixed time might be skipped or might run twice. An escalation or archive
activity might be skipped if it is scheduled to run while the operation is making the transition from
one server to another. An escalation or archive activity might be skipped or run twice if the system
clocks on the relevant systems are skewed--that is, if the clock settings differ enough to cause a
fixed time to be missed or encountered twice.
Page 696 of 4705
Home
Scenarios for load balancing between the web servers and BMC Remedy AR
System servers
For versions 7.6.04 or later, BMC recommends configuring the load balancer between the web
servers and BMC Remedy AR System servers without setting a sticky bit. This allows a session
from any web server to be distributed to any BMC Remedy AR System server.
Note
for both of these products, your BMC Remedy AR System server must also use the
matching 7.6.04 SP1 or later version.
This section describes the configuration for a load balancer between the web servers and BMC
Remedy AR System servers without setting a sticky bit for version 7.6.04 or later. As a starting
point, the configuration for setting a sticky bit for the load balancer for versions earlier than 7.6.04 is
first discussed.
Load balancing between the web servers and BMC Remedy AR System servers by setting a
sticky bit
In versions earlier than 7.6.04, BMC recommended configuring the load balancer between the web
servers and BMC Remedy AR System servers by setting a sticky bit. In this configuration, the load
balancer between the web servers and the BMC Remedy AR System servers routed all
connections from one web server to the same BMC Remedy AR System server, resulting in
session affinity.
The following figure illustrates session affinity between the web servers (WS) and the BMC
Remedy AR System servers (ARS) when the load balancer (LB) is configured with a sticky bit. For
example, session affinity is established between WS1 and ARS1, WS 2 and ARS2, and WS3 and
ARS3. The load balancer routes all connections from WS1 to ARS1.
Load-balancer configured with the sticky bit between the web servers and BMC Remedy AR
System servers
Page 697 of 4705
Home
Adding a BMC Remedy AR System server without setting a sticky bit

The following figure shows an example BMC Remedy AR System with three web servers and two
AR System servers where session affinity has been established between WS1 and ARS1, WS2
and ARS2, and WS3 and ARS1.
Load-balancer configuration with three web servers and two BMC Remedy AR System
servers with session affinity established
If a new BMC Remedy AR System server (ARS3) is added to this BMC Remedy AR System, ARS3
is never considered as available because WS1, WS2 and WS3 have already established session
affinity to either ARS1 or ARS2 (the following figure).
Load-balancer configuration with a new BMC Remedy AR System server added to three web
servers and two BMC Remedy AR System servers with session affinity established
In version 7.6.04 or later, you can route connections from a web server to a new BMC Remedy AR
System server on the fly by selecting the Enable Lifespan setting on the Connection Settings
page of the Mid Tier Configuration Tool (the following figure). This setting enables load balancing
Page 698 of 4705
Home
without setting a sticky bit.

Enable Lifespan setting on the Connection Settings page of the Mid Tier Configuration Tool
With Enable Lifespan selected, the load balancer distributes sessions from any web server (in this
case, WS3) across the BMC Remedy AR System server group according to its scheduling policy (
round robin or least connections). The newly-available BMC Remedy AR System server (ARS3) is
considered within that distribution, as shown in the following figure. Connections may or may not
get routed to ARS3 depending on the scheduling policy.
Load-balancer configuration with a new BMC Remedy AR System server added without
setting a sticky bit for the load balancer
Reestablishing a BMC Remedy AR System server after fail-over with the sticky bit set
In BMC Remedy AR System versions earlier than 7.6.04 (the following figure), suppose that ARS3
fails. If a sticky bit is configured for the load balancer, the following occurs:
The load balancer no longer uses ARS3 as an active resource.
The ARS3 end user receives an error.
The connection from WS3, which was previously routed to ARS3, is routed to ARS1 or
ARS2. In this example, WS3 sessions go to ARS1.
The following figure illustrates the resulting unbalanced connections between the web servers, load
balancer, and BMC Remedy AR System servers.
Load-balancer configuration with web servers and BMC Remedy AR System servers with the
sticky bit set for the load balancer when a BMC Remedy AR System server fails
Page 699 of 4705
Home
When ARS3 recovers and is recognized as an active resource by the load balancer, it does not
receive connections from any of the three web servers because session affinity has been
established between the web servers and either ARS1 or ARS2. To rebalance the servers in
versions earlier than 7.6.04, you need to shut down the BMC Remedy AR System servers, load
balancer, and web servers and then restart them in the proper sequence.
In version 7.6.04 or later, make sure the Enable Lifespan check box is selected on the
Connection Settings page of the Mid Tier Configuration Tool (the following figure). If a sticky bit is
not set, the load balancer distributes sessions from any web server to any BMC Remedy AR
System server, including a recovered or new BMC Remedy AR System server.
Limiting idle session connections

In BMC Remedy AR System versions earlier than 7.6.04, the idle connections between a web
server and BMC Remedy AR System server can stay open indefinitely. Performance problems from
this can occur under certain circumstances. For example:
An AR System server is removed from the server group.
The maximum number of sessions for a BMC Remedy AR System server is reached during
a resource spike.
BMC Remedy AR System servers users leave their sessions open for extended period, such
as during a lunch break or at the end of the day.
The source from these open idle sessions connections is not redistributed.
To avoid problems from idle connections in version 7.6.04 or later, you can configure the fields in
the Connection Pool Settings section on the Connection Settings page in the Mid Tier
Configuration Tool (the following figure). The Idle Connections per Server setting allows you to
limit the number of idle connections per server. The Connection Timeout field allows you to
specify how long the connections exceeding that limit will remain open before being terminated.
Lowering the Idle Connections per Server value minimizes the number of idle connections that
can stay open until their sessions ends. If the Idle Connections per Server field is set to 0, then
the connection pool will be closed when all connections are closed.
Lowering the Connection Timeout value minimizes the time that idle session-based connections
can stay connected before being closed, resulting in better load redistribution. The number of
current idle connections is determined by whether the Connection Time or Connection Lifespan
Page 700 of 4705
Home
setting is first met.

Connection Pool Settings on the Connection Settings page of the Mid Tier Configuration
Tool
Configuring the Connection Pool Settings allows idle sessions to be used again in a timely
manner. The BMC Remedy AR System server end users see no change in behavior because their
connections are not dropped.
Load balancing between the clients and web servers without setting a sticky bit
If the web servers in your BMC Remedy AR System were installed in a cluster (with fail-over
enabled), then setting the sticky bit on the load balancer between the clients and web servers is not
needed.
Server configuration sharing

There is no provision in BMC Remedy AR System for the sharing of common configuration
information among servers in a multiple-server environment. Therefore, you must synchronize
common configuration items. For example, changes made to the configuration file of one server
must be propagated to the other servers.
Licensing servers in a multiple-server environment

In an environment where several BMC Remedy AR System servers share a single database, each
server must be licensed separately. You must obtain server licenses for your primary server and
each additional server in your environment. However, other licenses on the primary server (such as
floating and DSO licenses) are extended to additional servers (sharing a single database) at no
charge.

To achieve a load balance with an email engine with multiple mailboxes, follow these steps:
1. Install the Email Engine on different machines.
2. Add following attribute in each EmailDaemon.properties file:
com.bmc.arsys.emaildaemon.Mailboxes=
3. Give different names to each mailbox, so that each installed email engine will work for only a
particular mailbox.
4.
Page 701 of 4705
Home
4. Ensure that all of the email engines refer to the same AR System server.

Use the f5 load balancer to ensure seamless failover when the mid tiers are operating in a
multi-tenant environment. The following topic provides information on how to prepare and configure
f5 load balancer.
Note
This topic provides only a sample configuration of the f5 load balancer. BMC Quality
Assurance department used this configuration for operating mid tiers in a multi-tenant
environment. Your f5 configuration can vary depending on your requirements. For more
information about f5 documentation, see http://www.f5.com/products/documentation/ .
To configure f5 load balancer, perform the following:

1. Create a pool
2. Create a node
3. Add nodes to a pool
4. Set rules
Creating a pool
You need to create a pool to which nodes can be added.
To create a pool
1. From the f5 home page, click Local Traffic > Pools > Pool list.
Page 702 of 4705
Home
2. From the Pool List page, click Create.

3. Enter the following information in the New Pool page.
a. From the Configuration drop-down list, select Basic.
b. In the Name field, enter a name for the pool. For example, add a pool named
pool_rod_arsys.
c. Optionally, in the Description field, enter a brief description for your pool.
d. For Health Monitors, from the Available list, select http, and move it to the Active list
. You need health monitors to ping the defined URLs at a defined interval and check
whether the node is alive.
e. In the Resources area, from the Load Balancing Method drop-down list, select
Round Robin.
4. Click Finished. The new pool with the specified name is created.
Notes
Ensure that you follow a naming convention to name a pool. For example,
you might want to name all the pools starting with P ool_.
If you create a node from the Resources area, the created node becomes a
part of this pool. The node will not be available for use by other pools.
Page 703 of 4705
Home
Creating a node
A node represents a Tomcat instance in the cluster. For example, if you have a cluster of 4 tomcat
instances, you will have to create 4 nodes in f5.
To create a node
1. From the f5 home page, click Local Traffic > Nodes > Node List.
2. Click Create.
3. In the New Node page, enter the following information:

a. In the Name field, enter a name for the node. For example, add a node named Node1
_RoD.
b. In the Address field, enter the IP address of the node.
c. Optionally, in the Description field, enter a brief description for the node.
d. In the Configuration area, keep the default configurations.
4. Click Finished. The new node is created.
Adding nodes
When a cluster is created, you need to add the nodes to a single pool.
To add nodes to a pool

1. From the f5 home page, click Local Traffic > Pools > Pool list.
2. Click the Members tab.
Page 704 of 4705
Home
3. Click Add.
4. Click Node List.
5. From the Address drop-down list, click to select the node that you want to add to the pool.
6. Enter 80 as the service port number.
7. Keep the default configurations.
8. Click Finished.
Repeat these steps for as many nodes you want to add to the pool.
Setting rules
You must create rules so that the f5 load balancer knows how to resolve the URL requests. For
example, if you enter URL asjust test1.onbmc.com, f5 would not know how to resolve this url. After
setting a rule, f5 can redirect such URL requests to the right mid tier.
To set a rule
1. Click Local Traffic > iRules > Data Group List .
2. Select the data group to which you want to set a rule.

3. Click Create.
Page 705 of 4705
Home
4. In the String field, enter a string. For example, enter Tenant1.onbmc.com.

5. In the Value field, enter the value for the string. For example, enter rod_arsys. Note: This is
the pool that was created in previous section.
6. Click Add. The rule is added, which specifies that in a browser, if you enter Tenant1.
onbmc.com, f5 redirects it to the correct mid tier, which is Tenant1.onbmc.com/arsys.
7. To edit a rule, from the String Records list, select a string and click Edit.
8. Make the changes and click Update. The rule is updated.

The following topics provide information about Unicode configuration:
Running your Unicode server
How BMC Remedy AR System works with Unicode
Specifying a character set for data import to a Unicode AR System server
Filter and escalation workflow considerations
Running your Unicode server

The following topics provide information about how to run your Unicode server:
Running a client from the command line on Windows
Running a Unicode client from the command line on UNIX
Restricting client access to an AR System 7.x and later Unicode server
Running a client from the command line on Windows

Use the --unicode flag when you invoke any of the following programs:
arcache
archgid
archgsel
ardisabled
Page 706 of 4705
Home
arhelp
arl10nmenu
arlabel
arreload
artext
arworkflow
fbupdate
For an example, see arlabel.txt (online documentation for the arlabel utility) in the Unsupported
folder where AR System is installed.
Running a Unicode client from the command line on UNIX

To run a Unicode client from the command line, you must:
Set the locale by using either of the following methods:
Set the LC_ALL and LANG environment variables to a value produced by the locale
-a command.
Set the locale in your .profile file (sh/bash users) or .cshrc file (csh/tcsh users).
The client uses the values you set in the Shell script. Of the locales listed, AR System
supports those ending in "UTF-8" (for Solaris and AIX) and "utf8" (for HPUX and Linux
).
See your UNIX documentation for information about how to set your locale settings.
Make sure that the dynamic libraries for AR System 7. x are available by adding the <
ARSystemServerInstallDir>/server/bin directory to your dynamic library path with the
appropriate environment variable:
LIBPATH on AIX
SHLIB_PATH on HP-UX
LD_LIBRARY_PATH on Solaris and Linux
For example, on Solaris, enter:
$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/bmc/ARSystem/server/bin
; export LD_LIBRARY_PATH
To simplify the process, if you are running on the UNIX system where the AR System server is
installed, you can use the arsystem env command:
$ <ARSystemInstallationDirectory>/server/bin/arsystem env <commandName> <
arguments>
This automatically sets the dynamic library path and locale variables to the same values that the
AR System server uses.
Page 707 of 4705
Home
Restricting client access to an AR System 7.x and later Unicode server

You can configure an AR System 7.x or later Unicode-enabled server so that only Unicode clients
have access. The Configuration tab of the AR System Administration: Server Information form
provides a Disable Non-Unicode Clients option. (This option applies to all BMC Remedy clients
except for BMC Remedy Developer Studio.)

Consider disallowing access by pre-7.x clients to prevent use of a 6.3 or earlier version of BMC
Remedy Administrator with a Unicode-enabled server. The BMC Remedy AR System
Administration Console enables you to specify the minimum API that the server supports. AR
System 7.x or later clients use API version 12, so enter the number 12 to prevent access to older
clients.
How BMC Remedy AR System works with Unicode

The following topics provide information about how BMC Remedy AR System works with Unicode:
How BMC Remedy AR System converts character sets
How field widths are determined
How serialized strings are encoded and decoded
Unicode composition and normalization
How BMC Remedy AR System derives a codeset in an API program
How BMC Remedy AR System converts character sets
Important
It is possible to convert all characters from any character set supported by BMC Remedy
AR System into Unicode. It is not possible, however, to convert all Unicode characters into
any other single character set. Where such conversion is not possible, BMC Remedy AR
System replaces the characters in question with another character.
Where conversion between code sets occurs in BMC Remedy AR System depends on which
versions of the BMC Remedy AR System clients you are running and whether the AR System
server is running in Unicode. Possible combinations are as follows:
When you run a pre-7.0.00 client against a 7.x or later AR System server running in Unicode
, the AR System server converts data to the codeset it would use if the server were not
running in Unicode.
When you run a 7.x or later client against an AR System server running in Unicode, the AR
System server transmits in UTF-8, and lets the API library code running in the client handle
any conversion. If the client program expects UTF-8, the library need not do anything. If the
client program expects some other codeset, the library converts the characters.
Page 708 of 4705
Home
When you run a 7.x or later client against a 7.x or later AR System server not running in
Unicode, the API library code running in the client handles any necessary conversion. If the
client does not expect Unicode, no conversion is needed.
If one side (either server or client) is running in Unicode, and the other is not, AR System converts
between the other code set and Unicode. For compatibility with existing practice, the system uses
Windows code pages instead of the ISO-standard encodings usually used in UNIX to represent
certain languages, as outlined in the following table.
Comparison of Windows code pages and ISO-standard encodings
Windows code page
ISO character set
Used with these languages
1252
8859-1 (Latin 1)
English and most Western European languages written in the Latin alphabet
1252
8859-15
Same as Latin 1 but with Euro symbol
1251
8859-5
Russian and other languages written in the Cyrillic alphabet
1250
8859-2 (Latin 2)
Polish, Czech, and other Central European languages
1257
8859-4
Baltic languages
1254
8859-9
Turkish
1253
8859-7
Greek
If BMC Remedy AR System determines that the client is running in Shift-JIS (universal, for
Japanese Windows systems), and the server is running in EUC-J (Japanese UNIX systems), it
converts characters between these encodings.
For other double-byte languages, BMC Remedy AR System supports:
Traditional Chinese using the Big5 character encoding (BMC Remedy AR System converts
characters between Big5 and Unicode as needed.)
Simplified Chinese using the GB2312 character encoding (BMC Remedy AR System
converts characters between GB2312 and Unicode as needed.)
Korean using the EUC-KR character encoding (BMC Remedy AR System converts
characters between EUC-KR and Unicode as needed.)
The system does not support any other character-set conversions between servers and clients. The
character encodings between clients and servers must match to prevent errors and data loss.
How field widths are determined

BMC Remedy AR System Unicode servers store characters in databases using UTF-8 (DB2,
Oracle, and Sybase databases) or UTF-16 (Microsoft SQL Server databases). UTF-8, being a
byte-oriented character encoding, is similar to other byte-oriented encodings that BMC Remedy AR
System supports, such as Shift-JIS and EUC (for Japanese) or GB2312 (for Simplified Chinese).
Page 709 of 4705
Home
However, a character sequence encoded in UTF-8 tends to be longer than the same characters in
one of the other encodings. Also, characters from European languages, which occupy 1 byte each
in the other encodings, can occupy 1 or 2 bytes in UTF-8, as outlined in the following table.
How characters are expanded in UTF-8
Characters
Expansion
Notes
in UTF-8
ASCII
Every ASCII character represents itself in UTF-8.
European
1-2
European texts combine ASCII with accented and inflected letters and special punctuation. The actual
expansion depends on the text itself, and somewhat on the language. For example, Italian text is
closer to 1 because it uses relatively few accented letters; Russian text is closer to 2 because nearly
all Russian words are spelled with non-ASCII (2-byte) characters, leaving only spaces and
punctuation as 1-byte characters.
Chinese,
1-2
Korean
Chinese and Korean encodings use 2 bytes for each character; the same characters in UTF-8 occupy
3 bytes. The actual expansion is near 1.5 unless the text makes heavy use of ASCII (which makes the
expansion slightly smaller).
Japanese
1-3
On average, this expansion is 1.5 as with Chinese and Korean: Most Japanese characters occupy 2
bytes in a codeset like Shift-JIS and 3 bytes in UTF-8. EUC (the Japanese encoding historically used
on UNIX systems) offers 3-byte forms. If your text has many of these, the expansion is
correspondingly smaller. The Japanese language is written using kanji (the full-width characters
resembling Chinese text), but also uses two other writing systems known as hiragana and katakana.
These "kana" characters occupy just 1 byte in Shift-JIS, and 3 bytes in UTF-8. So a character
sequence with a high proportion of these expands by a factor of nearly 3. (Japanese punctuation and
double-wide digits occupy 2 bytes in Shift-JIS and EUC, so they do not expand as much as kana do.)
Note
Because of this expansion on conversion into UTF-8, data converted to UTF-8 might not
be imported correctly because it no longer fits into the database columns. To avoid this
problem, expand the sizes of the affected form fields.
In UTF-16, each Unicode character occupies 1 or 2 code units (each code unit is a 16-bit quantity).
Each ASCII and European character occupies 1 code unit; each Chinese, Korean, and Japanese
character, which might be 2 bytes in its language-specific encoding, also occupies 1 code unit.
These expansions are valid for the characters of Unicode's Basic Multilingual Plane (BMP) the
original set of 65,536 characters presented in Unicode 1.0 and modified in Unicode 2.0. Since
version 3.0, Unicode provides a mechanism to define up to about 1 million supplemental characters
. Supplemental characters are defined for Chinese and also for some specialized usages in
mathematics, musical typesetting, and information processing. Each supplemental character
occupies 4 bytes in UTF-8, and 2 code units in UTF-16.
Page 710 of 4705
Home
How serialized strings are encoded and decoded

Like BMC Remedy AR System 6.3 server, BMC Remedy AR System 7.0.01 and later servers
encode and decode serialized strings using character lengths implied by the server's character
encoding. (The BMC Remedy AR System 7.0.00 server computes strings using character lengths
implied by the client's character encoding.)
The server encodes and decodes these strings using the Application-Parse-Qual and
Application-Format-Qual actions performed by filters and active links. The
ARDecodeARQualifierStruct and ARDecodeARAssignStruct C API calls (and Encode variants
of those functions) also process serialized strings.
This issue does not affect most serialized strings because they contain only ASCII characters. In
every character encoding supported by BMC Remedy AR system, each ASCII character occupies
exactly 1 byte. The lengths of non-ASCII characters depend on the character encoding in use. For
example, a qualifier such as 'Submitter' LIKE "%%" produces a serialized string that counts
the as 1 byte in the standard Windows "Code Page 1252" encoding, but 2 bytes in UTF-8. Clients
and servers generate errors if presented with strings that have incorrect lengths.
Unicode composition and normalization

BMC Remedy AR System expects to receive characters in Unicode Normalization Form C. Form C,
which is the same normalization form as expected by XML processors, uses the single-character
forms for European accented letters and for Korean jamo characters. This form is also the shortest;
that is, text encoded in this form occupies fewer bytes than in other normalization forms.
For more information, see the Unicode Consortium website at http://www.unicode.org.
How BMC Remedy AR System derives a codeset in an API program

When your API program calls ARInitialization, BMC Remedy AR System derives a client
request codeset from the locale information in ARControlStruct as follows:
If the ARControlStruct.locale.charset field contains a string, BMC Remedy AR
System uses that string to determine the codeset.
If the ARControlStruct.locale.charset field is empty, ARInitialization
examines the ARControlStruct.locale.locale field. If this field contains a string of
the form, lang_COUNTRY.codeset or lang_COUNTRY.codeset@modifiers, BMC
Remedy AR System uses the substring beginning with codeset to determine the proper
codeset to use.
If the ARControlStruct.locale.charset and ARControlStruct.locale.locale
fields are empty, BMC Remedy AR System tries to determine the client request codeset
from the system environment.
The API recognizes the following codeset strings:
Page 711 of 4705
Home
UTF-8 The client must communicate with the API in the UTF-8 character encoding of
Unicode.
"" (empty) The client must determine the client request codeset from the system
environment.
The API generates an error when the ARControlStruct.locale.charset field or the
codeset portion of the ARControlStruct.locale.locale contain a string other than UTF-8
or an empty string.
The API detects a change to the codeset and immediately applies it. This enables an API program
to change its codeset between API calls.
Specifying a character set for data import to a Unicode AR

System server
When importing pre-7.0.00 data to a BMC Remedy AR System 7.0.00 or later Unicode server using
XML .ARX or .DEF files, specify which character set the data uses. Specifying a character set lets
BMC Remedy AR System know that it needs to convert the incoming data from a non-Unicode
character set to Unicode.
Note
When you export data using BMC Remedy AR System 7.0.00 or later, it includes the
correct code for the character set in the output file.
If you do not specify a character set, the AR System server assumes the data is in the same
character set the AR System server uses. If the character sets do not match, your data is imported
but corrupted.
Important
Note the differences in syntax between the .ARX and .DEF files. Using the wrong syntax
can cause unexpected results from your import.
To specify a character set in an XML file

Open the XML file and make sure the proper encoding is specified in the following line: <?xml
version="1.0" encoding="<encodingName>"?>
For example, to specify traditional Chinese: <?xml version="1.0" encoding="big5"?>
Page 712 of 4705
Home
To specify a character set in an .ARX file

Open the .ARX file and enter the following line at the top of the file: CHAR-SET <encodingName>
For example, to specify traditional Chinese: CHAR-SET big5
To specify a character set in a .DEF file

Open the .DEF file and enter the following line at the top of the file: char-set: <encodingName
>
For example, to specify traditional Chinese: char-set: big5
The following table contains character set encoding names you should use when you edit your .
ARX or .DEF file.
Character set encoding names
Language
Encoding Name
Traditional Chinese
big5
Simplified Chinese
gb2312
Western European languages, such as English, French, German, Italian, Spanish, and so on.
windows-1252
Central European languages, such as Polish, Czech, Hungarian, and so on.
windows-1250
Cyrillic: Eastern European - Russian, Ukrainian, Belarusian, Bulgarian, Serbian, and Macedonian, and so
on.
windows-1251
Baltic languages, such as Latvian, Estonian, and Lithuanian.
windows-1257
Japanese
euc-jpshift_jis
Korean
euc-kr
Filter and escalation workflow considerations

Some server-side workflow actions call byte-oriented filter functions, such as LENGTH, SUBSTR,
and STRSTR. Character -oriented equivalents, such as LENGTHC, SUBSTRC, and STRSTRC,
also exits. Because UTF-8, Chinese, Japanese, and Korean characters can occupy one or more
bytes, the byte-oriented and character-oriented lengths and offsets are different. When creating
workflow actions, be aware of the difference. For example:
LEFT($8$, 3) extracts a prefix of no more than 3 bytes from field 8.
LEFTC($8$, 3) extracts a prefix of no more than 3 characters from field 8.
Page 713 of 4705
Home
BMC Remedy SNMP Agent configuration

You can use the Simple Network Management Protocol (SNMP) to monitor AR System using BMC
Remedy SNMP Agent.
The following topics describe how to configure BMC Remedy SNMP Agent if you did not configure
it during installation:
SNMP introduction
SNMP access control
Monitoring BMC Remedy AR System
Sending traps to clients
SNMP configuration files
arsnmpd configuration file purpose
snmpd configuration file purpose
armonitor configuration file purpose
Starting the SNMP Agent
Stopping the SNMP Agent
SNMP Configuration form in the AR System Administration Console
SNMP introduction
Simple Network Management Protocol (SNMP) is a protocol that network administrators use to
manage complex networks through SNMP-compliant management consoles to monitor network
devices.
You must configure BMC Remedy SNMP Agent before you can run it. To configure SNMP or
change your existing configuration, use the instructions in this section or visit http://
www.net-snmp.org. Check with your network administrator about specific configuration settings to
use.
Network administrators and BMC Remedy AR System administrators can use BMC Remedy SNMP
Agent to monitor AR System server and BMC Remedy Distributed Server Option (DSO) processes
and change process states.
The BMC Remedy SNMP Agent supports the following versions of SNMP:
Version 1 (community-based)
Version 2c (community-based)
Version 3 (user-based)
It supports the following levels of user-based authentication:
No authentication, no privacy (noAuthNoPriv)
Authentication only, no privacy (authNoPriv)
Page 714 of 4705
Home
Authentication with privacy (authPriv)

BMC Remedy SNMP Agent was developed using the net-snmp software toolkit, version 5.0.7. (For
more information about the net-snmp toolkit, see http://www.net-snmp.org/.) The agent runs as a
separate process on the same system as the AR System server, and supports the following basic
SNMP operations:
get
set
get-next
get-bulk (supported in SNMP v2c and v3)
trap
notification (SNMP v2c, SNMP v3)
BMC Remedy SNMP Agent is compatible with all platforms that BMC Remedy supports. For a list
of the compatible web application servers, see Compatibility matrix in the BMC Remedy ITSM
SNMP access control

For BMC Remedy SNMP Agent to respond to user requests, at least one directive specifying
access control must be in the arsnmpd configuration file. BMC Remedy SNMP Agent supports
access control for community-based and user-based access.
Community-based access (described in Querying or viewing SNMP data) must be configured for
SNMP clients that communicate with BMC Remedy SNMP Agent using either the SNMP v1 or v2c
protocol.
User-based access (described in Defining users by access level) must be configured for SNMP
clients that communicate with BMC Remedy SNMP Agent using the SNMP v3 protocol.
During the installation process, you can configure community-based or user-based authentication,
but not both.
In general, because user-based authentication is much more secure than community-based
authentication, establishing support for both forms is not recommended. However, if you do enable
support for both types of authentication, you must include directives to configure both methods.
The following topics provide more information about SNMP access control:
Querying or viewing SNMP data
Defining users by access level
Sending messages when unexpected events occur
Enabling SNMP to interact with BMC Remedy AR System
Page 715 of 4705
Home
Querying or viewing SNMP data

SNMP supports the following categories of communities:
Read-only communities Have permission to query an SNMP agent for any data that is
defined as having read permission. Communities with read-only permission cannot perform
SNMP set operations that result in a change to the value of a managed object.
Read-write communities Can view data from an SNMP agent and can change the value
of that data (if the OID is defined as having read-write permission) through an SNMP set
action.
When a client needs to gather information from an SNMP agent that supports community-based
authentication, it must supply a plain-text password known as a community string.
To establish a read-only community password, add the following directive:
rocommunity <communityString>
To establish a read-write community password, add the following directive:
rwcommunity <communityString>
Note
The community string must not include spaces and must not exceed 30 characters in
length.
For example:
rwcommunity privatecommunity
rocommunity publiccommunity
In the previous example, if a client needed to set the value of arsState (an action permitted only by
those with write permission), it would need to provide the value for the rwcommunity directive as
part of the SNMP request ( privatecommunity in this case).
Defining users by access level

User-based access control is defined in the arsnmpd and snmpd configuration files. User-based
access control defines each user by its level of access, as in community accounts: read-only
access or read-write access.
Users can be defined as using one of the following levels of authentication:
Page 716 of 4705
Home
No authentication and no privacy (noAuthNoPriv) Uses no authentication and no

privacy functions in the same way as the community-based authentication model. The user
name must be supplied to BMC Remedy SNMP Agent, and it functions as a plain-text
password (much like a community string). BMC Remedy SNMP Agent does not require a
password with a user account configured in this way.
Authentication and no privacy (authNoPriv) Uses authentication, and no privacy is
required to supply a password in addition to a valid user name. BMC Remedy SNMP Agent
verifies that the user name and password are correct before acknowledging the client
request.
Authentication and privacy (authPriv)
Uses authentication, and privacy is required to supply a password. In addition, the SNMP
packet containing the request must be encrypted. BMC Remedy SNMP Agent must have
access to the password used by the client to encrypt the packet. It uses this password to
decrypt the packet and then verifies that the user name and password are correct.
You define users in the arsnmpd file with rouser and rwuser directives, as follows:
To create a read-only user account, you must include the following directive:
rouser
<userName> [noauth|auth|priv]
The optional argument specifies the expected level of encryption to be used by this user.
The authentication noauth corresponds to noAuthNoPriv, auth to authNoPriv, and priv to
authPriv.
In the following example, rouser directive defines a user account with read-only permission.
This account does not require any form of authentication (that is, the user is authenticated in
the same way as a user providing a community-string password).
rouser user1 noauth
To create a read-write user account, you must include the following directive:
rwuser
<userName> [noauth|auth|priv]
The following example rwuser directive defines a user account with read-write permissions.
This user must supply a password, but their SNMP requests are not encrypted:
rwuser user2 auth
Page 717 of 4705
Home
You can repeat the rouser and rwuser directives to create multiple user accounts with
varying levels of authentication.
The user name supplied to the rouser or the rwuser directive must not include spaces and
must not exceed 30 characters in length.
If the optional argument is not supplied, BMC Remedy SNMP Agent defaults to auth level of
authentication.
Important
The previous directives are not sufficient to properly define a user account. See
snmpd configuration file purpose for additional configuration requirements.
Sending messages when unexpected events occur

Traps are unsolicited messages that BMC Remedy SNMP Agent sends to network management
software when unexpected events or errors occur. Messages inform administrators if the AR
System process has changed state. Traps can also inform administrators when a client has
attempted to access BMC Remedy SNMP Agent using an incorrect community string.
BMC Remedy SNMP Agent can send several standard SNMP traps. Trap messages are formatted
using version 1 or version 2 of the SNMP protocol. Using the trap configuration directives, you
instruct BMC Remedy SNMP Agent to send a trap to a system that is listening for them on a
specific port number.
To send a trap formatted to the SNMP v1 standard, add the following directive to the arsnmpd
configuration file:
trapsink
<systemNameOrIPAddress> <communityString> [<portNumber>]
To send a trap formatted to the SNMP v2c standard, add the following directive:
trap2sink
<systemNameOrIPAddress> <communityString> [<portNumber>]
You can repeat the trap directives to configure additional systems to receive trap messages.
For example:
trapsink traplistener.remedy.com public 8162
Page 718 of 4705
Home
The preceding directive instructs BMC Remedy SNMP Agent to send trap messages formatted
using SNMP v1 to the system traplistener, which is listening for trap messages on port number
8162, using community string public.
BMC Remedy SNMP Agent can also be configured to send trap messages known as authentication
failure traps. These trap messages are sent to all locations specified by the trapsink /trap2sink
directives whenever a client attempts to make an SNMP request using an incorrect community
string.
To enable authentication failure trap messages, include the following directive:
authtrapenable
<1|2>
Setting authtrapenable to 1 instructs BMC Remedy SNMP Agent to send authentication failure
traps. Setting the argument to 2 disables this feature.
Enabling SNMP to interact with BMC Remedy AR System

To enable BMC Remedy SNMP Agent to interact with BMC Remedy AR System, uncomment the
following line in the arsnmpd.cfg (arsnmpd.conf) file:
#arsmonitorfile
<absolutePathToarmonitorFile>
This is a mandatory configuration directive.
Note
Ensure that the argument represents the correct path to your armonitor file for your
environment.
Monitoring BMC Remedy AR System

You can use BMC Remedy SNMP Agent to monitor BMC Remedy AR System, to check the state
of BMC Remedy AR System, and to send traps (notifications) when the status of any BMC Remedy
AR System process changes.
BMC Remedy SNMP Agent can also be configured to monitor AR System server statistics, AR
System state, and select MIB-II data.
Monitoring BMC Remedy AR System server statistics

The statistical operations that the agent monitors are the same statistics that are available in the
Server Statistics form. For more information about these statistics, see Troubleshooting section.
Page 719 of 4705
Home
Monitoring BMC Remedy AR System state

BMC Remedy SNMP Agent monitors the state of BMC Remedy AR System (up or down), through
the use of the managed object arsState (1.3.6.1.4.1.10163.1.2.1.3.0). The current value of the
managed object arsState is used to indicate the current state of AR System. When queried, a
value of 1 indicates that AR System is running; a value of 2 indicates that AR System is down.
The managed object arsState is also writable, so the value of arsState can be changed by an
SNMP set operation (provided the proper user name or community string is supplied). Changing
the value of arsState from 1 to 2 instructs BMC Remedy SNMP Agent to stop AR System.
Changing the value of arsState from 2 to 1 instructs the agent to start AR System.
BMC Remedy SNMP Agent can monitor the following BMC Remedy AR System processes:
BMC Remedy AR System plug-in
BMC Remedy AR Monitor
If any of these process changes its state (for example, if a process becomes inactive), the agent
sends a trap (or a notification) to a trap receiver.
Monitoring MIB-II
BMC Remedy AR System supports the following objects in MIB-II:
System data (for example, system description and system location)
SNMP data and statistics
To query other objects, such as IP traffic or TCP traffic, use the SNMP agent included with your
operating system. Managed objects in these sections of MIB-II are not supported by BMC Remedy
SNMP Agent.
Monitoring Remedy MIB

The Remedy MIB file (Remedy-ARS-MIB.txt) defines all the objects managed by BMC Remedy
SNMP Agent and is necessary for querying Remedy specific objects by name from your SNMP
client.
The Remedy-ARS-MIB.txt file currently defines only BMC Remedy AR System controls, statistics,
and traps. However, as it is designed for extensibility, other branches in the Remedy-ARS-MIB.txt
file are reserved for future use.
Sending traps to clients

A trap is an asynchronous message that BMC Remedy SNMP Agent sends to clients when specific
events occur. The agent can be configured to send traps to a trap receiver (such as a network
management station) when the state of BMC Remedy AR System, specifically the armonitor
Page 720 of 4705
Home
process (or any BMC Remedy AR System process, such as AR System server, AR System plug-in
server, DSO, or email engine) changes. You can add a list of trap receivers (clients that receive
traps) to the arsnmpd.cfg file.
BMC Remedy SNMP Agents supports the following trap types:
coldstart Sent when the agent starts.
authentication failure Sent when a bad community string is supplied with an SNMP
request. This type of trap is supported only by SNMP versions 1 and 2c and must be
enabled in the arsnmpd.cfg file.
arsStateChange A Remedy enterprise-specific trap type. Sent when a change of state
occurs for any of these AR System processes: AR monitor, AR System server, AR System
plug-in server, BMC Remedy Email Engine, and DSO.
Each trap contains the following information:
The name of the process that changes state (for example, AR System plug-in server)
The name of the AR System server associated with the process
The state of the process (active =1, inactive =2)
When a monitored AR System process changes state from running to down, the trap
contains a value of 2 for arsState. When the process resumes, the trap contains a value of 1
for arsState.
Note
BMC Remedy SNMP Agent continues to run even if the processes it monitors are
not running.
For more information about configuring traps in the arsnmpd configuration file, see Sending
messages when unexpected events occur.
SNMP configuration files

Note
For information about configuring BMC Remedy SNMP Agent during installation, see the
Installing old and Upgrading old sections.
Page 721 of 4705
Home
BMC Remedy SNMP Agent was built using the Net-SNMP toolkit (version 5.0.7). This section
describes a subset of the more user-friendly and commonly used configuration options provided by
the Net-SNMP toolkit (version 5.0.7). For information about additional configuration directives and
options, see the Net-SNMP website at http://www.net-snmp.org.
BMC Remedy SNMP Agent uses the following configuration files:
Configuration file
Location
Purpose
(Windows)
(Windows)
Stores system information, access control information, and trap settings.
arsnmpd.cfg
ARSystemServerInstallDir
\conf
(UNIX)
arsnmpd.conf
(UNIX)
/usr/ar/ARSystemName/
conf
(Windows)
(Windows)
snmpd.conf
\conf
Stores engine ID, number of BMC Remedy SNMP Agent reboots, and SNMP
v3 user account information.
(UNIX)
snmpd.conf
(UNIX)
/usr/ar/ARSystemName/
conf
(Windows)
(Windows)
Enables BMC Remedy SNMP Agent to monitor BMC Remedy AR System
armonitor.cfg
\conf
and to be started by armonitor.
(UNIX)
armonitor.conf
(UNIX)
/etc/arsystem/
serverName
BMC Remedy SNMP Agent uses the information in the arsnmpd and snmpd configuration files to
initialize when the agent starts; therefore, you must restart BMC Remedy SNMP Agent after you
make changes to the configuration files. In addition, you must restart BMC Remedy AR System if
you make changes to the armonitor configuration file.
Note
If you perform an SNMP set operation to change the value of versionUpdateConfig.0 (
.1.3.6.1.4.1.2021.100.11.0) to 1, BMC Remedy SNMP Agent rereads the arsnmpd.cfg (
arsnmpd.conf) file, so in this case you do not need to restart BMC Remedy SNMP Agent.
arsnmpd configuration file purpose

Use the arsnmpd.conf (arsnmpd.cfg) file to configure any of the following information:
System information (see System information arsnmpd file)
Page 722 of 4705
Home
Access control information, which includes community strings and users ( see SNMP access
control introduction)
Trap configuration, which identifies the systems to which trap messages are sent ( see
Sending messages when unexpected events occur )
Location of the armonitor configuration file (see Enabling SNMP to interact with BMC
Remedy AR System)
To configure any of these items, apply a configuration directive and related arguments. You can
also add comments to any configuration file by beginning any comment line with a hash [#]
character. The standard syntax is as follows:
directive argument [<optionalArgument>]

# This is a comment
The following conditions apply to directives:

Each directive must occupy its own line in the configuration file.
Directives can be included in any order.
Only one instance of a directive is permitted in a configuration file unless otherwise indicated
.
Directives are considered optional unless otherwise specified.
If you configured SNMP during the installation process, many of the configuration options are
represented in this arsnmpd configuration file. If you did not configure SNMP during installation, a
sample arsnmpd.conf file with comment lines and sample directives is installed. In this case, you
need to remove the hash (#) characters, and provide valid arguments to the various directives. You
can also add configuration directives where appropriate.
System information defined in the arsnmpd file

The following system information can be defined in the arsnmpd configuration file:
Directive
Description
syslocation
A string representing the location of the system running BMC Remedy SNMP Agent.
syscontact
A string representing contact information for AR System, BMC Remedy SNMP Agent, or both.
To define the system location, add the following directive:
syslocation
<systemLocation>
To define the system contact, add the following directive:
syscontact
<systemContactInformation>
Page 723 of 4705
Home
The argument to syslocation or syscontact can include spaces. However, all the information must
be on the same line and no longer than 255 characters.
For example:
syslocation Lab in room 101

syscontact Call Joe at 555-5555 or joe@mail.com
You can access information defined by these directives from BMC Remedy SNMP Agent by
querying the related MIB-II system group OIDs:
Directive
Description
syslocation
Used to populate sysLocation OID of MIB-II (1.3.6.1.2.1.1.6.0)
syscontact
Used to populate sysContact OID of MIB-II (1.3.6.1.2.1.1.4.0)
snmpd configuration file purpose

The snmpd configuration file can contain the following information:
engineBoots
engineID
If an snmpd configuration file does not exist, you must create one in the CONF directory of your
AR System installation. In this case, engineBoots and engineID is added to the snmpd file when
BMC Remedy SNMP Agent starts.
In the snmpd file, you enter the configuration directives required to fully define a user account.
When adding information to this file, do not alter the lines corresponding to engineBoots and
engineID (if they are present).
For each user account defined in the arsnmpd file (see rwuser and rouser directive information in
Defining users by access level), you must include a corresponding createUser directive to this file
as follows:
createUser <userName>
MD5 <authenticationPassword>
DES <privatePassword>
Note
Passwords must be at least eight characters long.
Page 724 of 4705
Home
Using this directive, you can define the authentication password and privacy password used by the
user account (userName).
Note
In SNMP v3, the authentication password that the user supplies to BMC Remedy SNMP
Agent must be encrypted.
The following examples show how directives can be used:

If you defined a user in the arsnmpd file as having read-write permissions and using
authentication and no privacy:
rwuser user1 auth
The following line is required in the snmpd file:
createUser user1 MD5 mypassword
If you defined a user in the arsnmpd file as using privacy:
rwuser user1 priv
createUser user1 MD5 mypassword DES privatepassword
If you defined a user in the arsnmpd file as using no authentication and no privacy:
rwuser user1 noauth
createUser user1
Page 725 of 4705
Home
armonitor configuration file purpose

The armonitor configuration file permits the armonitor utility to start BMC Remedy SNMP Agent
and to establish a link to it.
If you configured BMC Remedy SNMP Agent during installation, no modification to this file is
necessary. If you did not configure BMC Remedy SNMP Agent during installation, you must edit the
armonitor.cfg (armonitor.conf) file to enable armonitor to start and interact with BMC Remedy
SNMP Agent.
Enable SNMP by setting the SNMP-agent-enabled configuration parameter to true as follows:
SNMP-agent-enabled: T
In addition, remove the comment marker (#) from the command line corresponding to the arsnmpd
process. (This enables armonitor to start BMC Remedy SNMP Agent.)
You might need to change the default port number from 161 because an SNMP agent might
already be running on the default port 161. To do this, change the value of udp:161 on the line
corresponding to the arsnmpd process to a new port number that is not currently in use by another
process, for example udp:8161.
Starting the SNMP Agent

You can start BMC Remedy SNMP Agent in any of the following ways:
Using armonitor
If you configured SNMP during installation, armonitor with start the SNMP agent
automatically after installation is complete.
If the SNMP agent process is terminated, armonitor restarts the SNMP agent.
Using a command line with the following syntax:
arsnmpd -c <pathToarsnmpdConfigurationFile>
udp: <portNumber>
Ensure that:
The argument to the -c option is the path to the arsnmpd configuration file, not the
snmpd file.
The argument to udp is a port number not currently in use by another SNMP agent or
any other process.
For example (UNIX):
Page 726 of 4705
Home
arsnmpd -c /user/ar/arsystem/conf/arsnmpd.conf udp:8161
Invoking the agent during BMC Remedy AR System startup, using the Services panel (on
Windows) or the arsystem shell script (on UNIX).
Stopping the SNMP Agent

On Windows, BMC Remedy AR System is installed as a service. If you stop the BMC Remedy AR
System service, BMC Remedy SNMP Agent also stops.
On UNIX, use the arsystem shell script to stop BMC Remedy AR System, which stops all BMC
Remedy AR System processes, including BMC Remedy SNMP Agent.
If you use BMC Remedy SNMP Agent to stop BMC Remedy AR System, BMC Remedy SNMP
Agent exists as an independent process that is not under the control of the armonitor, the BMC
Remedy AR System service (Windows), or the arsystem shell script (UNIX). You must manually
stop and restart BMC Remedy SNMP Agent by using specific operating system methods (for
example, by using Task Manager on Windows or by using a kill command on UNIX).
To stop BMC Remedy SNMP Agent without affecting other BMC Remedy AR System processes,
use standard operating system approaches to stopping individual processes. (Often this can be
accomplished on either a Windows or UNIX system by issuing a kill command from a command
prompt.) If BMC Remedy SNMP Agent is still a child process of armonitor, however, armonitor
attempts to restart the agent.
For more information about stopping individual processes, see your system administrator.
SNMP Configuration form in the AR System Administration

Console
Use the AR System Administration SNMP Configuration form to configure the BMC Remedy SNMP
Agent (SNMP). You can assess this form from the BMC Remedy AR System Administration
Console.
You must configure the SNMP Agent using the AR System Administration SNMP Configuration
form if you select the Install option to install SNMP Agent version 8.1.00
Note
If you select the Upgrade option to upgrade an existing version of SNMP Agent to version
8.1.00, you do not need to re-configure the SNMP Agent.
Page 727 of 4705
Home
For more information about configuring the SNMP Agent, see BMC Remedy SNMP Agent
configuration.
AR System Administration SNMP Configuration form
SNMP Configuration form fields in the AR System Administration Console

Field name
Enable SNMP Agent in
armonitor.conf
Description
Click Yes to enable the SNMP Agent.

Click No to disable the SNMP Agent.
System Location
Information
Enter the system location information.
Administrator Contact
Enter the administrator contact information.
Information
SNMP Agent Port
Number
Authentication Mode
for SNMP Requests
Enter the SNMP Agent port number.
Community Based If you select the community-based option, the following fields are
displayed. Select any one of the following community-based options.
Read-Only Community
Write-Only Community
User Based If you select the user-based option, the following fields are displayed:
User Name Enter the user name.
Access Mode Select either Read-Only Access or Read-Write Access as the
required access mode.
Authentication Mode Select any one of the following authentication mode:
No authentication. No privacy (noAuthNoPriv)
Authentication only without privacy (AuthNoPriv) If you select this option, the
Authentication Password field is displayed.
Authentication with privacy (AuthPriv) If you select this option, the
Authentication Password and Private Key Password fields are displayed.
Traps
Click Enable to enable Traps.
Note
If you click Enable, the System Receiving Traps, SNMP Trap Community, and SNMP
Trap Port Number fields are enabled.
Page 728 of 4705
Home
Field name
Description
Trap Version
Select any one of the following Trap versions:

SNMP Trap Version 1 (community-based)
SNMP Trap Version 2c (community-based)
System Receiving
Traps
Enter the system name that is receiving the Traps.
SNMP Trap Community
Enter the SNMP Trap Community details.
SNMP Trap Port

Number
Enter the SNMP Trap port number.
Authentication
Password
Enter the authentication password.
Note
The authentication password should be longer than 8 characters.
Private Key Password
Enter the private key password.
Note
The private key password should be longer than 8 characters.
Note
You must restart the BMC Remedy AR System server for the changes made to this form
to take effect.
Configuring BMC Remedy Distributed Server

Option
This section explains how to configure BMC Remedy AR System servers for a distributed
environment.
For information about BMC Remedy AR System server management, see the Administering and
Troubleshooting sections.
A BMC Remedy AR System server can be associated with only one Distributed Server Option (
DSO) server (ardsoj versionNumber _buildNumber.jar on Windows or UNIX). To the DSO server
, that BMC Remedy AR System server is the local or source BMC Remedy AR System server. All
Page 729 of 4705
Home
other servers, whether they reside on the same host as the DSO server or on a different host, are
considered remote servers.
Each DSO server can transfer data from a form on its local server to
Another form on its local server
A form on a remote server
The following topics are covered in this section:
Setting up DSO
Configuring a password for the DSO user
Assigning an RPC program number to DSO
Configuring remote AR System servers for DSO
Configuring DSO for firewalls
Specifying a DSO host name
Configuring the RPC timeout setting
AR System Administration - Server Information form - DSO tab
Setting up DSO
To set up distributed operations, follow this process:
1. Add a DSO license in the BMC Remedy AR System server.
See Enabling DSO on a BMC Remedy AR System server .
2. Configure a password for the DSO user.
See Configuring a password for the DSO user .
3. Determine whether you will use RPC program numbers.
See Assigning an RPC program number to DSO .
4. Enable the communication between the local DSO server and the remote BMC Remedy AR
System servers.
See Configuring remote AR System servers for DSO .
5. Configure DSO for firewalls.
See Configuring DSO for firewalls.
6. Determine whether you want to specify a DSO host name.
See Specifying a DSO host name.
7. Determine whether you want to specify the RPC timeout setting.
See Configuring the RPC timeout setting.
8. Determine whether you will need DSO for load balancing.
See DSO for load balancing.

Page 730 of 4705
Home
Important
You must perform this procedure on all BMC Remedy AR System servers that participate
in distributed operations.
To enable DSO on a BMC Remedy AR System server, follow the given procedure:
1. Add an AR Distributed Server license to the BMC Remedy AR System server.
For information about licensing servers, see License overview.
2. Uncomment the following DSO server entry in the armonitorconfiguration file:
Platform
Java server
Windows or UNIX
ardsojversionNumber_buildNumber.jar
By default, the armonitorconfiguration file is in this location:

(UNIX) /etc/arsystem/serverName/armonitor.conf
(Windows) ARSystemServerInstallDir\Conf\armonitor.cfg
3. Restart the BMC Remedy AR System server.
The following items are now available in your system:
DSO settings on the Administration: Server Information form
DSO editors in BMC Remedy Developer Studio:
Distributed Mapping editor Used to create and maintain distributed mappings.
See Distributed mapping.
Distributed Pool editor Used to create and maintain distributed pools. See
Distributed pools.
DSO forms on the BMC Remedy AR System server:
Distributed Pending form Lists pending distributed transfers, updates,
returns, and deletes. See Viewing items in the pending distributed queue .
Distributed Pending Errors form Lists failed pending distributed
operations. See Logging failed pending items.
Distributed Mapping form Used to store definitions of distributed mappings
. Normally, you do not need to access this form.
Distributed Logical Mapping form Used to create and store the definitions
of logical and physical names. See Creating logical mappings.
Distributed Pool form Used to store definitions of distributed pools.
Normally, you do not need to access this form.
Warning
Do not modify or delete these forms.
Page 731 of 4705
Home
You can transfer entries in the Distributed Mapping and Distributed Pool forms
to their counterparts on remote servers. See Setting up broadcast distributed
transfers.
Related topics
Configuring a password for the DSO user

The DSO server performs all operations as an internal BMC Remedy AR System user with these
attributes:
DSO user name: Distributed Server
License type: AR User Fixed
The Distributed Server user has controlled permissions and a locked name. It does not require
additional licensing.
To enable this user to communicate with its local BMC Remedy AR System server, you must
configure a password for it as follows.
Important
On BMC Remedy AR System 7.0.00 or later, DSO passwords are mandatory for all BMC
Remedy AR System servers involved in distributed operations, whether the server is the
source server or the target server.
To configure a password for the local DSO user

1. Open the AR System Administration: Server Information form for the local BMC Remedy AR
System server.
3. On the Connection Settings tab, click the DSO Server tab.
4. In the DSO Local Password field, enter a password for the local DSO user, and click OK.
Note
To avoid authentication failures, the password must not exceed 20 characters.
5. To make the change take effect, restart the BMC Remedy AR System server.
Page 732 of 4705
Home
Assigning an RPC program number to DSO

Dedicated (private) remote procedure call (RPC) program numbers are not required by DSO, but
you might want to use them in these circumstances:
You have a large environment with heavy data traffic.
Your environment distributes large amounts of data.
If you dedicate an RPC program number to DSO, it must be one of these:
390600 (administrative queue)
390621 -390634, 390636 -390669, 390680 -390694 (private queue)
The DSO server uses the assigned RPC program number for all communication with the
associated BMC Remedy AR System server. You must allocate at least one thread to the server
queue associated with the RPC program number.
If you do not assign a dedicated RPC program number to DSO, the fast and list queues process all
distributed operations.
For more information about threads and queues, see AR System server multithread architecture.
To assign an RPC program number to DSO on the local BMC Remedy AR System
server
1. Open the AR System Administration: Server Information form for the appropriate BMC
2. Click the Ports and Queues tab.
3. Verify that the RPC program number that you want to assign to DSO is listed in the Server
Queue table.
If the number is not listed, add it. (See the Setting ports and RPC numbers)
5. On the Connection Settings tab, click the DSO Server tab.
6. In the DSO Local RPC Program Number field, enter the appropriate RPC program number,
and click OK.
7. To make the change take effect, restart the BMC Remedy AR System server.
Note
If you reassign the RPC program number while running DSO and then restart the
BMC Remedy AR System server, you do not lose any items in the distributed
pending queue.
Page 733 of 4705
Home
Configuring remote AR System servers for DSO

To enable the local DSO server to communicate with remote BMC Remedy AR System servers,
perform the following steps:
1. On the remote BMC Remedy AR System server, perform these tasks:
Add a DSO license. See Enabling DSO on a BMC Remedy AR System server .
Specify a local DSO password. See Configuring a password for the DSO user .
(Optional) Specify an RPC program number for DSO. See Assigning an RPC program
number to DSO.
2. On the local BMC Remedy AR System server, open the AR System Administration: Server
Information form.
4. In the Connection Settings tab, open the DSO Server tab.
5. Enter the following information in the tables on the tab by clicking the appropriate table cell:
Server Name The name of the remote BMC Remedy AR System server
If you enter data in both tables, you must enter the server name in both tables.
RPC Program Number The RPC program number dedicated to DSO on the
remote BMC Remedy AR System server, if any. If this field is blank, a value of 0 is
entered, and the local DSO server communicates with the remote BMC Remedy AR
System server through the fast and list queues.
See Assigning an RPC program number to DSO .
Port If the remote BMC Remedy AR System server is running behind a firewall,
that server's TCP/IP port number. If this field is blank, a value of 0 is entered, and the
system uses a portmapper on the remote BMC Remedy AR System server to locate
the appropriate port number.
See Assigning TCP port numbers to AR System servers.
Password The remote BMC Remedy AR System server's local DSO password.
See Configuring a password for the DSO user .
Note
Masked editing is not supported in tables on forms. Therefore, when you
enter a password in this field, it is visible. After you save your changes in
step 6, the password is masked.
6. Click OK.
7. Restart the local BMC Remedy AR System server to make these settings take effect.
8. Repeat this procedure for each remote BMC Remedy AR System server that the local DSO
server must communicate with.
Page 734 of 4705
Home
Configuring DSO for firewalls

When you install an BMC Remedy AR System server, a DSO server is automatically installed on
the same host as the BMC Remedy AR System server. By default, that DSO server processes all
distributed transfer operations for the BMC Remedy AR System server. If an BMC Remedy AR
System server is configured to run behind a firewall, however, you can set up a DSO server outside
the firewall to support that BMC Remedy AR System server, as shown in the following figure:
DSO firewall configuration
For information about configuring a firewall for an BMC Remedy AR System server, see
Configuring firewalls with AR System servers .
To configure DSO for firewalls

In this procedure,
BMC Remedy AR System server A is the DSO source BMC Remedy AR System server
behind the firewall.
BMC Remedy AR System server B is outside the firewall.
1. On server A, open the AR System Administration: Server Information form, then click the
DSO tab.
2.
Page 735 of 4705
Home
2. Select Placeholder Mode, then click OK.

This disables the DSO server that was automatically installed with server A. That DSO
server can no longer process distributed operations.
DSO-Placeholder-Mode.
3. To make this change take effect, restart server A.
4. On server B, open the AR System Administration: Server Information form, then click the
DSO tab.
5. In the Source Server field, enter the name of server A.
DSO-Source-Server.
6. In the Backup Polling Interval field, enter an appropriate number of seconds (see Setting a
custom backup polling interval), then click Apply.
This instructs the DSO server on Host B to check the distributed pending queue on server A
every x seconds. This is necessary because the DSO server on Host B cannot receive
real-time signals from workflow on server A.
DSO-Polling-Interval.
Note
Setting this field does not make the DSO server on Host B a polling server. For
information about polling servers (DSO-Main-Thread-Polling-Interval), see
Setting a polling interval for the DSO server .
7. Click the Connection Settings tab, then click the DSO Server tab on the Connection
Settings tab.
8. In the DSO Local Password field, enter the password that the active DSO server outside
the firewall uses to communicate with server A. See Configuring a password for the DSO
user.
9. (Optional) In the DSO Local RPC Program Number field, enter a dedicated RPC program
that the active DSO server outside the firewall uses to communicate with server A. See
Assigning an RPC program number to DSO .
10. In the left table, enter the name and TCP/IP port of server A, then click OK.
See Assigning TCP port numbers to AR System servers .
11. To make these changes take effect, restart server B.
Server A is now the source BMC Remedy AR System server for the active DSO server that
was installed with server B.
Page 736 of 4705
Home
Specifying a DSO host name

In distributed mappings, DSO uses the default server name for the From Server Name field unless
you specify a DSO host name ( DSO-Host-Name) in the BMC Remedy AR System server
configuration file.
Note
The default server name is specified in the Server-Name entry in the BMC Remedy AR
System server configuration file.
Thus, if necessary, you can configure BMC Remedy AR System to use a fully qualified domain
name (FQDN) or "long name" for distributed operations. DSO automatically puts the
DSO-Host-Name value in the From Server field whenever that field is on a form involved in a
distributed operation.
Warning
The From Server Name field on distributed mappings is limited to 64 characters. If the
server name exceeds that limit, it is truncated, and the distributed operation fails. This is
most likely to occur when you select the Allow Any Server in Server Group option in a
distributed mapping (see Allow Any Server in Server Group). In that case, the From
Server Name field must contain the server name alias, which is specified in the
Server-Name option of the BMC Remedy AR System server configuration file.
To specify a DSO host name

1. Stop the BMC Remedy Action Request System Server serverName service.
2. Open the appropriate BMC Remedy AR System server configuration file:
(Windows) ARSystemServerInstallDir\Conf\ar.cfg
(UNIX) ARSystemServerInstallDir/conf/ar.conf
3. In the file, enter the host name in this format:
DSO-Host-Name:<hostName>.<domainName>
In this format, hostName is the short name of the From server, such as sanfrancisco, and
domainName is the domain name of the From server, such as acme.com.

4. Save the configuration file.
5. Restart the BMC Remedy Action Request System Server serverName service.
Page 737 of 4705
Home
Configuring the RPC timeout setting

You can configure the RPC timeout setting for pending distributed operations to accommodate
slow network connections or large amounts of data. If you do not configure this setting, the system
uses the default timeout (120 seconds).
To configure the RPC timeout setting

1. Open the AR System Administration: Server Information form for the appropriate BMC
3. In the API Timeout Normal field, enter the number of seconds before a timeout occurs.
The timeout value must be an integer between 60 (1 minute) and 21600 (6 hours).
4. Click OK.

To configure DSO for load balancing, in addition to configuring the hardware load balancer, you
must configure multiple servers to use a single database. To do this, you can use server groups.
In addition, server groups provide increased scalability and reliability and enable several servers to
be managed as a unit. If you use server groups, no further AR System configuration is required to
implement load balancing. See Configuring server groups.
For more information about how to use a hardware load balancer, see Configuring a hardware load
balancer with BMC Remedy AR System .
Related topics
AR System Administration - Server Information form - DSO tab

Many of the DSO server configuration tasks are performed in the DSO tab in the AR System
Administration: Server Information form. The fields in the DSO tab are described in the following
table:
Fields in DSO tab in the AR System Administration: Server Information form
Field
Description
Source
Server
Specifies the BMC Remedy AR System server for a DSO server to support when that BMC Remedy AR System
server is different from the one installed with the DSO server.
Page 738 of 4705
Home
Field
Description
Use this when setting up a DSO server outside a firewall to support an BMC Remedy AR System server running
behind the firewall. The corresponding BMC Remedy AR System server configuration file entry is
DSO-Source-Server. See Configuring DSO for firewalls.
Polling
Interval
Specifies the interval at which the DSO server queries the distributed pending queue for pending distributed items.
Enter any integer from 0 (no polling) to 3600 seconds (1 hour). The corresponding BMC Remedy AR System
server configuration file entry is DSO-Main-Thread-Polling-Interval. When a polling interval is specified, the DSO
server does not receive real-time signals from workflow. See Setting a polling interval for the DSO server.
Backup
Polling
Specifies the interval (in seconds) at which the DSO server checks the distributed pending queue for pending
distributed items.
Interval
This is used only as a backup in case an issue causes the DSO server to receive no signals from workflow. Unless
an issue occurs, the DSO server continues receiving real-time signals from workflow when this option is enabled.
The server does not become a polling server. The value can be any integer between 15 and 7200. By default, the
backup polling interval is disabled. The corresponding BMC Remedy AR System server configuration file entry is
DSO-Polling-Interval. See Setting a custom backup polling interval.
API
Timeout
Normal
Specifies the timeout (in seconds) that the DSO server applies during communication with the BMC Remedy AR
System server.
Enter an integer between 60 (1 minute) and 21600 (6 hours). If you enter a value out of range, the closest in-range
value is used. If you do not enter a value, the system uses the default timeout (120 seconds). The corresponding
BMC Remedy AR System configuration file entry is DSO-Timeout-Normal. See Configuring the RPC timeout
setting.
Cache
Check
Interval
Specifies the number of seconds between occurrences of these operations:

Checks by DSO for changes to the source and target forms
Updates of cached DSO mapping information
By default, this option is set to 1800 seconds (30 minutes). The maximum value is 43200 seconds (12 hours). The
corresponding BMC Remedy AR System server configuration file entry is DSO-Cache-Check-Interval. See
Setting the distributed mapping cache refresh interval.
Error Retry
Option
Specifies how the DSO server responds to errors.

Valid values are
0 (default): Retry after standard connection and transmission errors.
1: Never retry after any error.
2: Retry after every error.
3: Retry after standard connection and transmission errors and after database errors.
The corresponding BMC Remedy AR System server configuration file entry is DSO-Error-Retry-Option.
Max
Pending
Records
Per Query
Specifies the maximum number of records in the Distributed Pending form that DSO reads in a single database
query.
Valid values are
Minimum number: 1
Maximum number: Unlimited
If no value is specified, the default is 1000. The corresponding BMC Remedy AR System server configuration file
entry is DSO-Max-Pending-Records-Per-Query
Specifies whether to set the status of items in the DSO distributed pending queue to Retry after an attempt to
perform the associated operation fails.
Page 739 of 4705
Home
Field
Description
Mark
Pending
Retry
(The failure must be due to a recoverable error. Items that fail due to nonrecoverable errors are removed from the
queue.) Valid values are
T (Default) Does not set the status to Retry. Instead, the status remains set to New. Depending on the
number of pending items that the DSO server processes, this setting might improve the server's
performance.
F Sets the status to Retry. Use this to differentiate items in the queue that have never been processed (
status = New) from items that were processed but failed due to recoverable errors ( status = Retry).
Note
Regardless of this option's value, the pending item is still retried based on its retry configuration (see How
errors affect pending items).
The corresponding BMC Remedy AR System server configuration file entry is DSO-Mark-Pending-Retry-Flag.
Placeholder
Mode
When selected, disables the DSO server that was installed on the same host as the BMC Remedy AR System
server. Use this when setting up a DSO server outside a firewall to support an BMC Remedy AR System server
running behind a firewall. The corresponding BMC Remedy AR System server configuration file entry is
DSO-Placeholder-Mode. See Configuring DSO for firewalls.
Log Errors
to DSO
Pending
Errors
Specifies whether to log failed pending distributed operations to the Distributed Pending Errors form.
The corresponding BMC Remedy AR System server configuration file entry is Log-DSO-Errors-To-Form. See
Logging failed pending items.
Form
Suppress
No Such
Entry Error
Specifies whether to log BMC Remedy AR System server error 302 (entry does not exist in database) in the
arerror.log file when performing distributed delete operations.
for
Distributed
When this option is selected, ARERR 302 is never logged during distributed deletes.
(Default) When this option is not selected, ARERR 302 is always logged during distributed deletes except
Delete
when the Error Retry Option is set to 2 (retry after every error).
Note
When this option is selected, errors caused by valid problems might also be omitted from the log.
The corresponding BMC Remedy AR System server configuration file entry is

DSO-Supress-No-Such-Entry-For-Delete. See Logging the ARERR 302 error during distributed deletes.
Configuring full text search

This section contains information about configuring FTS in BMC Remedy AR System.
FTS tab configuration options
High-availability architecture for FTS
FTS Configuration form in the AR System Administration Console
Creating index files in a different directory from the default
Scheduling scans for updates
Configuring the Ignore Words List
Page 740 of 4705
Home
Displaying FTS weight in a results list

Providing a shortcut for specifying expanded FTS qualifications
Configuring FTS for localization
Advanced FTS configuration files
Adding FTS licenses
Upgrading with FTS installed
FTS tab configuration options

This section outlines the configuration options for FTS from the FTS tab of the AR System
Administration: Server Information form.
Full Text Search configuration options
FTS tab fields

Field name
Description
Disable Full
Text
Searching
Controls whether the server uses the full text search engine for searching. When disabled, the server uses the
search capability of the underlying database. This setting does not apply to multi-form searching.
FTS
Collection
Directory
The location in the file system where search engine index files are stored.
Note
If you change the directory in this field, update the pluginsvr_config.xml file with the correct directory
path. This file is in <ARSystemInstallDir>\pluginsvr\fts.
FTS
Configuration
Directory
The location in the file system where search engine configuration files are stored.
Full Text
Search
Threshold
The maximum number of search results returned from the search engine. The default value is 10,000. To limit
the number of search results (because of constraints on the computer where the search engine is running),
reduce the threshold. If you change this option, you must restart the AR System server for the change to take
effect.
Page 741 of 4705
Home
Field name
Description
Indexing
Failure
Recovery
Interval
Defines the number of minutes the server waits between periodic attempts to index entries that failed to index for
an unexpected reason in a prior attempt. The default value is 60 minutes.
Temporary
Table
Threshold
During the processing of search results, the server creates a temporary table if the number of FTS matches
reaches this value. If the number of FTS matches is less than this value, the server uses the SQL IN operator for
Complex
Search
Threshold
During the processing of search results, the server combines results from subqueries to arrive at the final result
set. If the number of rows created during processing exceeds this value, the server returns an error message
Indexer
Server Group
Signal Delay
Number of seconds before a signal is sent to the server that owns the full text indexing operation (if no signal is
a query on an existing table. The default value is 200.
indicating that the search is too complex. The default value is 1,000,000.
pending). When a server is not the owner of the full text indexing operation and generates indexing work, that
server signals the server that is the owner of indexing. To reduce the frequency of signals sent, the signaling is
conducted on a delayed basis. When indexing is generated, the server checks whether a signal is pending. If so,
the server does not need to take any action. If a signal is not pending, the server creates a pending signal to be
sent in the specified amount of time. If the full text signal delay configuration value is changed, the duration of
any pending delay interval does not change. The change takes effect the next time a delay interval is started.
Values are
Default--10 seconds
Minimum--1 second
Maximum--None
Case
Defines whether full text searching is case sensitive or insensitive. This setting affects all fields indexed for full
text search and affects how the indexes are built. Therefore, changes to this setting trigger an automatic re-index
. The default setting is case insensitive.
Search
Options
Defines how the server modifies qualifications received from the client. The choices are
Force Leading & Trailing Wildcards
Ignore Leading & Force Trailing Wildcards
Ignore Leading Wildcards
Remove Leading & Trailing Wildcards
Query Unchanged (default)
Reindex
Initiates the re-indexing of all fields selected for full text indexing. This check box is disabled if a re-index is in
progress. The dialog box must be redisplayed for the check box to become active following completion of the
re-indexing.
Disable Full
Text Indexer
Controls whether the server processes pending indexing tasks. When disabled, indexing tasks are still recorded
for processing at a later time when indexing is enabled.
Use FTS in
Workflow
Controls whether the server uses full text searches when executing queries during workflow that have full text
indexed fields in the qualification. By default, this option is selected. If you clear this check box, the server uses
the search capability of the database.
Ignore Words
List
Defines which words are ignored during indexing.
Title Field
Weight
Defines the relevancy weight for the Title field of a form in a multiple-form search. (See Configuring forms for
multiple-form FTS.) A value of 1 is the baseline and provides a slight boost to the relevancy weight. If you leave
the field empty, the weight is 1. To increase the weight, enter a positive number greater than 1 and less than or
equal to 18450000000000000000. To decrease the weight, enter any number from 0.9 to 0.1. To see a
significant difference in the relevancy score, the weight will need to be changed by increments of 100 or more.
Page 742 of 4705
Home
Field name
Description
Environment
Field Weight
Defines the relevancy weight for the Environment field of a form in a multiple-form search. (See Configuring
forms for multiple-form FTS.) A value of 1 is the baseline and provides a slight boost to the relevancy weight. If
you leave the field empty, the weight is 1. To increase the weight, enter a positive number greater than 1 and
less than or equal to 18450000000000000000. To decrease the weight, enter any number from 0.9 to 0.1. To
see a significant difference in the relevancy score, the weight will need to be changed by increments of 100 or
more.
Keywords
Field Weight
Defines the relevancy weight for the Keywords field of a form in a multiple-form search. (See Configuring forms
for multiple-form FTS.) A value of 1 is the baseline and provides a slight boost to the relevancy weight. If you
leave the field empty, the weight is 1. To increase the weight, enter a positive number greater than 1 and less
than or equal to 18450000000000000000. To decrease the weight, enter any number from 0.9 to 0.1. To see a
significant difference in the relevancy score, the weight will need to be changed by increments of 100 or more.
Note
You must re-index data so that any changes to the relevancy weights are applied to the existing data.

You can now install more than one FTS server in a server group. Each of these servers acts as an
independent FTS server, providing service failover.
How failover occurs in high-availability configuration

FTS requires that at least one of the servers in a server group act as a primary FTS indexing server
. To provide failover, you can have two or more primary FTS indexing servers in the server group
where each server acts as an independent FTS server and indexing FTS in their own Collection
directory. Each FTS indexing server (known as primary FTS indexing server) manages its own
separate local replica of the full text index data. When an indexing action takes place, each FTS
indexing server indexes it independently.
For example, if you create a form and then index a field on that form, each FTS indexing server
indexes that field. Because you can have multiple FTS servers, each with its own current copy of
the FTS data, you can fail over to a second server.
An AR System server is designated as a primary FTS indexing server by having a ranking record
for FTS in the AR System Server Group Operation Ranking form. Each FTS server defined in the
ranking form acts as an indexing server and provides FTS search services to other servers in the
server group. Each defined FTS server will always index, regardless of its ranking order. However,
the server that is ranked 2 contains redundant FTS data and must be used for failover. This server
is not intended to be a user-facing server.
Servers in the server group that are not ranked for FTS are search-only servers. The search-only
servers are user facing servers and they connect to one of the FTS indexing servers to search the
FTS data.
Page 743 of 4705
Home
Note
The servers that are not designated as indexing server should not be listed in the AR
System Server Group Operation Ranking form.
The following figure shows the FTS plug-ins and FTS high-availability architecture in a server group
.
BMC Remedy Full Text Search (FTS) plug-in and high-availability architecture
Page 744 of 4705
Home
Primary FTS indexing servers always connect to their own local indexes. The other servers in the
group can connect to any of the indexing servers. BMC recommends that all non-Primary FTS
servers initially connect to the Primary FTS server which is ranked 1. The Server-Plugin-Alias
parameter in the ar.cfg [or ar.conf] files of the servers specify the initial connection. This initial
connection is known as the home connection.
While servicing an FTS request, if an FTS indexing server experiences a connection error, the
request attempts to connect to another FTS indexing server (as specified in the AR System Server
Group Operation Ranking form) until a server is found or there are no more to try.
For example, consider a scenario where you have two primary FTS indexing servers that are
ranked 1 and 2 in the AR System Server Group Operation Ranking form. Your Server-Plugin-Alias
parameter points to the server that is ranked 1. If this server experiences a connection error, the
connection request goes to the server that is ranked 2. If for some reason even the server that is
ranked 2 is down, the request then is returned as an error since no primary FTS indexing servers
are available.
Note
In some cases, the indexes on the indexer servers can become out of sync. This
can happen when you create a form and index a field on that form between
scheduled indexing scans. If one of the indexer servers is down at the time of the
scheduled indexing scan, the indexes on that server will be out of sync until the
next scheduled indexing scan.
A slight load on the database can occur if you are performing re-indexing and your
database is running on a low memory.
Avoid performing a full re-index at the same time on two FTS index servers running
in your production environment, as failover will occur if the FTS indexing server is
busy while performing a re-index.
A slight latency in displaying the search results can occur when the failover
happens as it is required to establish a connection to the next ranked server for
FTS.
Related topics
Page 745 of 4705
Home
FTS Configuration form in the AR System Administration

Console
You can use the AR System Administration FTS Configuration form to configure Full Text Search (
FTS). You can access this form from the BMC Remedy AR System Administration Console.
You must configure FTS manually using the AR System Administration FTS Configuration form in
the following scenarios:
If you select the Install option to install FTS version 9.0.00
If you select the Upgrade option to upgrade an existing version of FTS to version 9.0.00.
Note
After completing the changes to this form, continue with the FTS configuration. See
Configuring full text search.
AR System Administration FTS Configuration form
Page 746 of 4705
Home
AR System Administration FTS Configuration form fields

Field name
Description
FTS Agent
Use the FTS Agent check box to enable or disable the FTS plug-in processes in the armonitor.cfg/conf file.
If you select this check box, the FTS plug-in processes are automatically uncommented in the armonitor file. If
you clear this check box and save the changes, the FTS processes are automatically commented in the
armonitor file.
If you are using FTS in a server group, the Primary and Secondary FTS plug-in processes are commented/
uncommented based on your selection.
Using the FTS Agent check box does not require manual intervention to uncomment the FTS plug-in processes
in the armonitor file.
You must restart the AR System server for the changes to take effect.
Select any one of the options and perform the following:
Page 747 of 4705
Home
Field name
Server
Configuration
Description
Single Server (Not a server group)
Enter values in the FTS Port1 and Max JVM Memory1 fields for the FTS Reader and Writer
instances.
If you select this option, the fields under Reader are unavailable because on a single server only
one FTS instance serves as both reader and writer.
Server Group-Primary
Enter values in the FTS Port1 and Max JVM Memory1 fields for FTS Writer.
Enter values in the FTS Port2 and Max JVM Memory2 fields for FTS Reader.
If you select the Server Group-Primary option, the Primary Server Name field under Reader is
unavailable because primary server name is not required for configuring FTS on the primary server.
Server Group-Secondary
Enter values in the Primary Server Name and FTS Port 2 fields for FTS Reader.
If you select the Server Group-Secondary option, the Max JVM Memory2 field under Reader and
the FTS Port1 and Max JVM Memory1 fields under Writer are unavailable because from the
secondary server you must connect only to the reader instance running on the primary server.
Note
A server is considered to be an indexing server if you select either the Single Server or Server Group
- Primary option on the FTS Configuration form. Only the server acting as an indexing server should
have the ranking in the AR System Server Group Operation Ranking form. Ranking the indexing server
is essential because the other non-indexing server can determine where to failover if the configured
FTS indexing server is not available.
For more information, see Configuring full text search for a server group .
FTS Port1
Enter the FTS port for primary server. The port range is 9988 - 9998.
During installation, the installer picks the available port from the port range starting from the lower port number.
For more information about port numbers, see Understanding port numbers.
Max JVM
Enter the JVM heap size (in megabytes) for primary server.
Memory1
Primary
Enter the name of the primary server.
Server Name
FTS Port2
Enter the FTS port for secondary server. The port range is 9977 - 9982.
For more information about port numbers, see Understanding port numbers.
Max JVM
Memory2
Enter the JVM heap size (in megabytes) for secondary server.
FTS
Collection
Enter the full path of the FTS Collection directory.
Directory
FTS
Configuration
Directory
Enter the full path of the FTS Configuration directory.
Notes
Page 748 of 4705
Home
You must log on to each server and perform FTS configuration on each server
using the FTS Configuration form.
You must restart the AR System server for the changes made to this form to take
effect.
Ensure that the Collection and Configuration directories are available on a local
drive of each indexing server.
Log on to each server and ensure that the paths of the Collection and
Configuration directories are identical on all the servers in the server group. For
example, if the indexing servers in a server group are running on Windows and the
paths of these directories are C:\data1\BMCData\BMCARSystem\FTS\Collection
and C:\data1\BMCData\BMCARSystem\FTS\Configuration respectively, ensure
that all reader servers have the same path set in their ar.cfg conf file with respect to
the location of the Collection directory on the indexing servers. The fail-over fails if
the directory paths are different. All indexing servers and reader servers in a server
group refer to this path in the ar.cfg conf file. The indexing servers also refer to this
path for the FTS plug-ins in the pluginsvr_conf.xml file .
Creating index files in a different directory from the default

By default, index files are stored in <ARSystemInstallDir>\ftsconfiguration\collection.
To create index files in a different directory

1. Update the FTS Collection Directory field on the FTS tab of the AR System Administration:
See FTS tab configuration options.
Alternatively, you can update the Full-Text-Collection-Directory option of the
ar.conf file. See ar.cfg or ar.conf.
2. Update the pluginsvr_config.xml file with the correct directory path.
The pluginsvr_config.xml file is in <ARSystemInstallDir>pluginsvr\fts.
Scheduling scans for updates

Updates to entries for join, vendor, and view form types are not always generated in the same
manner as regular forms. To ensure accuracy in full text searches, schedule scans for updates in
these types of forms. When the forms are scanned, the AR System server indexes only the entries
that have been added and changed.
The scans work as follows:
For join forms, the server can detect which fields on the join form represent last-modified
timestamps on base forms. Using those timestamps, the server scans for updates at the
scheduled times.
Page 749 of 4705
Home
For vendor and view forms that contain a core field with field ID 6 (equivalent of a
last-modified timestamp), the server scans for updates at the scheduled times.
If the form does not contain a field with ID 6 (vendor or view forms) or any last-modified
timestamps (join forms), the form cannot be scanned for updates only, and the server
re-indexes all indexed fields on the form each time the form is scheduled to perform a scan.
Deleted entries (or entries that disappear because join key fields are changed in base forms)
are not detected, and the entries are represented in the index until you complete a field
re-index. For more information, see Re-indexing considerations.
Use caution when scheduling scan intervals. Do not overload the system with a large number of
form scans at small intervals, especially those that perform a complete reindex because of the
unavailability of last modified timestamps.
Note
If using the BMC Remedy AR System interface is the only way your organization updates
the database table associated to a view form, you do not need to schedule scanning for
that view form.
To schedule a scan for updates

1. In BMC Remedy Developer Studio, open the form.
2. Select the Definitions tab.
3. Expand the Other Definitions panel and the Full Text Search panel.
4. Select the scan times for updates to fields that have been indexed for FTS.
5. Save the form.
Configuring the Ignore Words List

You can configure the FTS engine to ignore frequently used words (such as and, the, because, and
so on) or words that you do not want indexed. Adding entries to the Ignore Words List saves space
in the FTS index and speeds up text searches. The FTS option comes with a default set of ignored
words that you can modify as needed.
Note
You must re-index the data for the changes to the Ignore Words List to take effect.
Accrue searches that contain words from the Ignore Words List do not find any matching BMC
Remedy AR System requests for those words. However, the accrue search retrieves requests for
the other search terms. For restrictions on FTS, see Limitations of FTS.
Page 750 of 4705
Home
Note
The Ignore Words List is different for each supported language.
For information about adding words to the Ignore Words List, see FTS tab configuration options.
Displaying FTS weight in a results list

In the Results List Fields panel on the Definitions tab, you can configure results lists to display
the FTS weight for all requests retrieved.
To display FTS weight in a results list

1. In BMC Remedy Developer Studio, open the form for which you want to define the results
list format.
3. Expand the Other Definitions panel and then the Result List Fields panel.
4. Click Add.
5. In the Field Selector dialog box, select WEIGHT, and click OK.
The WEIGHT field displays the weighted value of retrieved BMC Remedy AR System
requests when you create a results list in the browser. If sorted by descending weight, the
requests are listed in order, based on a relevance factor calculated by the search engine.
6. If necessary, specify a Separator and Width.
7. Save the form.
Providing a shortcut for specifying expanded FTS qualifications

To provide a shortcut method for specifying expanded FTS qualifications, add a form search field (a
display-only field with field ID 178) to a form. Then, users can use that field to search all full text
indexed fields on the form with an expanded OR search. For example, if the Description and
Worklog fields on a form are indexed for FTS and the user performs a QBE search by supplying the
search term firewall in a form search field, the qualification generated on the server is:
'Description' LIKE "firewall" OR 'Worklog' LIKE "firewall"
On a form where a single attachment field is the only field indexed for FTS, you can use this feature
to provide a QBE search for the attachment field. Otherwise, only the advanced search bar method
is available for searching attachments.
Important
Page 751 of 4705
Home
Use caution when labeling the form search field so that users do not get the impression
that using this field searches all fields on the form. The feature searches only fields
indexed for FTS.
Note
This feature is available only from version 7.0.00 or later clients. For environments with
pre-7.0.00 clients, hide this field for those clients by using client-side workflow when $
VERSION$ < " 7" (the space in front of the 7 is intentional). If the field is visible and
used in pre-7.0.00 clients, the qualification is not sent to the server (unbeknownst to users
), potentially resulting in an unqualified query. Also, if users on a system without a full text
search server license enter a qualification in the form search field, the AR System server
returns an error.
Configuring FTS for localization

The <ARSystemInstallDir>\ftsconfiguration directory contains the files described in the following
table to enable you to configure FTS for localization.
Configuration files for FTS
Configuration
Description
file
stopwords_ <
locale>.txt
Specifies stop words used for eliminating common words. Each stop word is a separate line item in the text file.
You create a file for each locale or language. You can update this file through the Ignore Words List field on the
AR System Administration: Server Information form.
rootwords_ <
locale>.txt
Lists words and their corresponding root word. You create a file for each locale or language. By default, FTS
uses stemmers particular to the installed locale. A stemmer takes words (such as fast, faster, fastest) and
converts them to stem words at indexing time so that using a word, such as fast, finds all references to it, such
as faster and fastest.
The rootwords_<locale>.txt file overrides how the FTS or third-party stemmers define root words. If a word is
found in the root words list, then the root word is used, and the stemmer is not run on the original word. (For
information about using a third-party stemmer, see Advanced FTS configuration files.)
Each line in the rootwords_<locale>.txt file contains space-separated words with the first word being the root
word and the others being words that map to the root word, for example:
run running runs
thesaurus_ <
locale>.txt
Contains synonyms used to perform thesaurus expansion during indexing. You create a file for each locale or
language. If the thesaurus.txt file is present, any terms it finds in the thesaurus are expanded within the index to
contain its synonym values at the same word location.
Each line in the text file contains space-separated words that are synonyms. For example:
quick fast speedy
Page 752 of 4705
Home
Note
If you modify any of the FTS configuration files, you must restart the server for the
changes to take effect.
The FTSLocaleConfig.xml file (in <ARSystemInstallDir>\ftsconfiguration) contains pointers to

the configuration files. For example:
<config>
<locale locale="en">
<stopwordfile>enStopword.txt</stopwordfile>
<rootwordfile>enRootword.txt</rootwordfile>
<thesaurusfile>enThesaurus.txt</thesaurusfile>
<indexAnalyzer> </indexAnalyzer>
<searchAnalyzer> </searchAnalyzer>
<stemmer>English</stemmer>
</locale>
<locale locale="de">
.
.
.
You can include as many "locale" elements as you need in the FTSLocaleConfig.xml file. By
default, AR System is installed with two-letter locales defined, but you can also include country
codes (for example, <locale locale="en_US"> ).
If any element is blank or missing in any locale section of the FTSLocaleConfig.xml file, FTS does
not use that item in the analysis process.
For advanced configuration, you can enter the name of an index analyzer, search analyzer, or
stemmer file in the FTSLocaleConfig.xml file. For more information, see Advanced FTS
configuration files.
Advanced FTS configuration files

The following table lists the advanced files referenced in the FTSLocaleConfig.xml file.
Advanced configuration files

File
Description
indexAnalyzer
Enables you to define external Lucene analyzers for the indexing process. For more information, see http://
lucene.apache.org/java/docs/index.html.
searchAnalyzer
Page 753 of 4705
Home
File
Description
Enables you to define external Lucene analyzers for the searching process. For more information, see http://
lucene.apache.org/java/docs/index.html.
stemmer
The FTSAnalyzer uses the Snowball stemmers from the Snowball project for performing stemming functionality
. This configuration enables you to define which stemmer to use for a particular language, or it enables you to
define a custom stemmer with the Snowball project tools. For information about the Snowball project, see http:/
/snowball.tartarus.org/.
If the default FTS functionality is not producing the results you expect, you can reference third-party
index analyzers, search analyzers, and stemmers.
You might want to process the data differently when indexing versus searching.
An index analyzer expands all words in the database. For example, if a user is searching for
a word like computer, other words like system and machine are included in the search.
A search analyzer does not expand the words being searched, which improves the
performance. If a user is searching for computer, only that word is searched for.
To use third-party configuration files

1. Configure a third-party configuration jar file (for example, customAnalyzer.jar ).
This jar file can contain one or more analyzers (such as indexAnalyzer, searchAnalyzer, and
stemmer). Each analyzer should have a specific name (for example,
org.myorg.lucene.analysis.EsparantoAnalyzer).
2. Insert the analyzer names in the FTSLocaleConfig.xml file. For example:
<indexAnalyzer>org.myorg.lucene.analysis.EsparantoAnalyzer</indexAnalyzer>
<searchAnalyzer>org.myorg.lucene.analysis.EsparantoAnalyzer</searchAnalyzer>
<stemmer>Esparanto</stemmer>
3. Make sure that the Java can find the jar file that you created in step 1:
a. Place the jar file in the fts plug-in directory (by default, C:\Program Files\BMC
Software\ARSystem\pluginsvr\fts ).
b. To add the jar to the class path, edit the pathelement option of the
pluginsvr_config.xml file in the fts directory. For example:
<pluginsvr_config>
<port>9998</port>
.
.
.
<plugins>
plugin>
<name>ARSYS.ARF.FTS</name>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem/
pluginsvr/fts/ftsplugin _VerNum_.jar</pathelement>
Page 754 of 4705
Home
<pathelement type="location">C:/Program Files/BMC Software/ARSystem

/pluginsvr/fts/tika\-0.3\-standalone.jar</pathelement>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem
/pluginsvr/fts/ *customAnalyzer.jar*
</pathelement>
.
.
.
</plugin>
</plugins>
</pluginsvr_config>
Adding FTS licenses

FTS is integrated throughout the BMC Remedy IT Service Management Suite. You must define a
license before installing FTS.
To add an FTS license

1. From the IT Home page, open the AR System Administration Console.
2. Choose System > General > Add or Remove Licenses .
3. Click Add New.
4. Define the following settings:
License Type BMC Remedy Full Text Search
Number of Licenses 1
5. Click Save.

If you are upgrading and do not want to re-index the FTS indexing servers, use the following
procedure:
1. Complete any re-indexing before starting the upgrade.
2. Stop all user activity on the servers and do not start any new re-indexing.
3. Ensure that any remaining ft_pending table entries are completed before continuing (they
should complete quickly).
For more information about the ft_pending table, see FTS indexing for attachments.
4. Disable indexing for all servers in the server group.
5. (Optional) Designate additional servers for FTS in the AR System Server Group Operation
Ranking form. (You can do this after the upgrade, but then you must restart the AR System
server again.)
6. Perform the upgrade and enable indexing for FTS on the FTS indexing servers as follows:
a. Click the FTS tab on the Server Information form.
b. Clear the Disable Full Text Searching and Disable FTS Indexer check boxes.
c. Click Apply.
Page 755 of 4705
Home
This ensures that Full Text Search and the FTS Indexer are enabled after the upgrade.
Note
Other than the initial deployment where all FTS index servers might be indexed at
the same time, you should re-index only one server at a time to allow the other
servers to handle failover requests.
If you want to re-index all the FTS indexing servers while upgrading, you must
complete the procedure at Configuring full text search for a server group .
Related topic
The following topics provide information about how to configure reports:
Modifying the config.properties file for limiting report entries
Limiting entries using a published report
Configuring web and BMC Remedy AR System reports
Using Crystal reports with BMC Remedy AR System
Managing localized Crystal and Web reports
Modifying the config.properties file for limiting report entries

You can add the following new parameters to the config.properties file to limit the number of
entries in a BMC Remedy Action Request System (AR System) report.
Parameter
Description
arsystem.nativereport.onscreen_max_entries
Determines the maximum number of records that can be rendered on

the screen in an AR System report. The default value is 2000; only the
first 2,000 records are exported.
Note: If the parameter is not set in the config.properties file, reports
use the default value. If the value is set to 0 (zero), all the records are
exported.
arsystem.FileExport_max_entries
Determines the maximum number of records that can be exported (as

CSV, ARX, and so forth) in an AR System report. The default value is
2000; only the first 2,000 records are exported.
Note: If the parameter is not set in the config.properties file, reports
use the default value. If the value is set to 0 (zero), all the records are
exported.
Page 756 of 4705
Home
Parameter
Description
arsystem.webreport.onscreen_max_entries
Determines the maximum number of records that can be rendered on

the screen and the maximum number records that can be exported in
a web report. The default value is 2000; only the first 2,000 records
are exported.
Note: If the parameter is not set in the config.properties file, the
reports use the default value. If the value is set to 0 (zero), all the
records are exported.
Limiting entries using a published report

You can add the following new parameter to the <ARInstallationFolder>\pluginsvr\
pluginsvr_config.xml file (BMC Remedy AR System Server reporting plug-in) for limiting the
number of entries in a BMC Remedy Action Request System (AR System) report. This parameter is
added to the configuration information of the Publish Report plug-in. For more details about the
Publish Report plug-in, see Troubleshooting Publish Report plug-in issues.
Tip
BMC recommends that you publish a report if you estimate that the report would contain
more than 5000 entries.
Parameter
Description
maxEntriesInFileReport
Determines the maximum number of records that can be published to a file for an AR System
report. The default value is 2000 .
Example:
<plugin>
<name>ARSYS.ARF.PUBLISHREPORT</name>
<classname>
com.bmc.arsys.plugins.report.PublishReport
</classname>
<userDefined>
<birtinstallpath>
C:/Program Files/BMC Software/
ARSystem/pluginsvr/birtruntime
</birtinstallpath>
<maxEntriesInFileReport>2000</maxEntriesInFileReport>
</userDefined>
</plugin>
Note
Page 757 of 4705
Home
When you change maxEntriesInFileReport parameter value to 5000 or more, you must
also increase the heap size to more than 1 GB as per your requirement, for example,
Xmx1024m or Xmx2048m. The default value is Xmx512m. You can modify the heap size
in the armonitor.cfg file at the following location:
"C:\Program Files\Java\jre7\bin\java" Xmx512m -classpath "C:\
Program Files\BMCSoftware\ARSystem\pluginsvr;C:\Program Files\BMC
Software\ARSystem\pluginsvr\arpluginsvr88_build001.jar;C:\Program
Files\BMCSoftware\ARSystem\approval\bin\armaskingImpl88_build001.
jar;C:\Program Files\BMC Software\ARSystem\arserver\api\lib\
arcmnapp88_build001.jar"
com.bmc.arsys.pluginsvr.ARPluginServerMain -x BMC-GXDH6Q1 -i "C:\
Program Files\BMC Software\ARSystem" m
For more information about what parameters to add to the configuration file for limiting the number
of entries in a BMC Remedy Action Request System (AR System) report, see Modifying the
config.properties file for limiting report entries .
Configuring web and BMC Remedy AR System reports

This section describes information administrators need to know to configure and manage Web
reports and AR System reports for use on the web:
Backward compatibility for reports
Defining report types
Managing reports with the Report form
Reporting in BMC Remedy AR System
Reporting using table fields and results list fields
Running a report by using an Open Window active link
Setting limits on reports that users save
Backward compatibility for reports

You can view reports created by using run macro report actions on the Web by converting them to
an equivalent active link.
The following topics provide information about how to view reports:
Viewing reports by placing an active link on a form
Making localized reports available to users
Page 758 of 4705
Home
Viewing reports by placing an active link on a form

Running the conversion procedure for a run macro report action creates an equivalent active link,
which you will be prompted to name. The report content and layout (definition) become
automatically embedded within the active link during the conversion, and no additional entries are
required. After the active link is created, it can then be attached to a workflow trigger, such as a
button field, and placed on a form.
For instructions on attaching active links to a workflow trigger, such as a button field, see Attaching
an Open Window active link to a form with a button field .
For information about backward compatibility related to localization, see Backward compatibility for
reports.
Making localized reports available to users

If you have language-specific reports created using Run Macro report actions with releases prior to
BMC Remedy AR System 5.x, perform the following steps to make them available to users:
1. Convert the run macro report action to an equivalent active link.
2. Attach the active link to a workflow trigger, such as a button field, and place it on a form.
3. Create an entry in the AR System Message Catalog.
For information about the AR System Message Catalog entry required for localized reports
embedded in an active link, see Localizing message components of a form view .
Defining report types

The ReportType form defines the environment that supports creating, editing, and running reports
on the Web.
The following report types are defined in the ReportType form:
AR System
Crystal
Web
You can create report type entries, but they should follow the syntax described in the Run
Command URL keywords and descriptions table. Only administrators can submit or modify entries
to the ReportType form.
The recommended entries for AR System and Crystal report types are loaded automatically during
BMC Remedy AR System installation. Open the ReportType form in Search mode to see these
entries.
The following topics provide information about how to define a new report type and
recommendations for the different report types:
Page 759 of 4705
Home
Defining a report type

Recommended entries for BMC Remedy AR System and Crystal report types
Defining a report type

1. In a browser, open the ReportType form in New mode.
http:<host>/<contextPath>/forms/<serverName>/ReportType
ReportType form
2. In the Report Type field, enter a name for the supporting report engine.
BMC Remedy AR System uses the following names. Do not use them as it would violate a
unique index that has already been defined.
AR System
Crystal
Web
3. In the Query Converter Class field, enter the name of the Java class that converts a BMC
Remedy AR System query string into a query string format recognized in the web reporting
interface.
BMC Remedy AR System uses the com.remedy.arsys.reporting.CrystalQueryConverter
to implement the ReportQueryConverter interface that converts queries to the Crystal
report engine. Use this interface when writing your own query converter for other web-based
report engines. You can find the CrystalQueryConverter and queryConverter_ReadMe.txt
file in the midTierInstallDir\samples directory. The queryConverter_ReadMe.txt file
provides a guide for creating your own query converter class.
4. In the Query Override Capability field, select Yes or No.
The Yes option gives this report type permission to override a query stored in a report. The
No option denies this permission.
This field also is displayed on the ReportSelection form, with the selected value.
5. In the Run Command field, enter the URL that is used to connect a report to the report
engine.
The Run command begins the processing of the selected report.
The recommended Run Command is a single-line entry with no spaces. The keyword portion
of the URL corresponds to parameters that are passed to the web reporting environment.
The following table lists allowable URL keywords that can be used to build the Run
command. These keywords listed are for reporting purposes only. They are not BMC
Remedy AR System keywords.
Run Command URL keywords and descriptions
Page 760 of 4705
Home
Keyword
Description
$ARSERVER$
BMC Remedy AR System server name for report data.
$
ARAUTHENTICATION
$
Authentication string used by the user.
$CRTLOC$
Location of any version of Crystal Reports. This path is stored on the Report Settings page of
the BMC Remedy Mid Tier Configuration Tool.
$CRTXILOC$
Location of BusinessObjects Enterprise XI. This path is stored on the Report Settings page of
the BMC Remedy Mid Tier Configuration Tool.
$USR$
User name.
$PWD$
User's password.
$RPTAPP$
Application that the form belongs to.
$RPTENC$
HTML charset encoding.
$RPTOP$
Operations (Run, Edit, Create).
$RPTFORM$
Form the report is being run against.
$RPTSVR$
Name of the server where the form is located.
$RPTNAME$
Name of the report.
$RPTLOC$
Report location relative to the base directory for reports as indicated in the BMC Remedy Mid
Tier Configuration Tool.
$RPTFILE$
The report on the web server. An absolute pointer to where the report file is found.
$RPTQUERY$
Query string.
$RPTQOVR$
Query override.
$RPTVIEW$
View that the report is being run against.
$RPTVIEWEXT$
Extension to view.
$CRTSVR$
Crystal Web server. This is usually the same as the BMC Remedy Mid Tier server web host.
$CRTPORT$
Crystal Web server port.
$CRTVWR$
Crystal report viewer.
$LOC$
Locale used for generating locale-specific prompts, labels, and formatting data.
$TIMEZONE$
Time zone to use for generating date and time strings; for example, PST.
$LANGUAGE$
Language to use for formatting data.
$COUNTRY$
Country where the language is spoken.
$UPRPTSVR$
AR System server that is specified in the user preferences as the Report Server.
$RPTCHARSET$
The character set to be applied to the report.
$RPTDEST$
The selected destination for the report; for example, File or Screen.
Page 761 of 4705
Home
Note
The Edit and Create commands are no longer supported.
Recommended entries for BMC Remedy AR System and Crystal report types
The following entries are recommended for the AR System and Crystal report types. The
recommended entries for AR System and Crystal report types are loaded automatically during BMC
Remedy AR System installation.
Recommended entries for native BMC Remedy AR System reports

Report Type AR System
By default, the Report Type is AR System, but you can enter any name.
Query Converter Class Leave blank
Query Override Capability Yes
Run Command /servlet/NativeReportServlet?O=$RPTOP$&U=$USR$&P=$PWD
$&Q=$RPTQUERY$&QR=$RPTQOVR$&S=$RPTSVR$&F=$RPTFORM$&VW=$RPTVIEW$&
VWEXT=$RPTVIEWEXT$&APP=$RPTAPP$&R=$RPTNAME$&RF=$RPTFILE$&LOC=$LOC$&
TZ=$TIMEZONE$&LNG=$LANGUAGE$&CTRY=$COUNTRY$&enc=$RPTENC$&RPTCHARSET=
USESERVER&RPTDEST=FILE
Edit Command Leave blank (not supported)
Create Command Leave blank (not supported)
Recommended entries for Crystal Reports

Report Type Crystal
By default, the Report Type is Crystal, but you can enter any name.
Query Converter Class com.remedy.arsys.reporting.CrystalQueryConverter
Query Override Capability No
Run Command Examples are:
BORemoteAPPURL=$CRTXILOC$/arreports/$RPTLOC$?init=$CRTVWR$&
User0=$USR$;ARServer=$ARSERVER$;ARAuthentication=$
ARAUTHENTICATION$;ARReportLocale=$LOC$;ARVUIType=1&Password0=$
PWD$&SF=$RPTQUERY$
BOCurrentMidtierURL=$CRTXILOC$/arsys/$RPTLOC$?init=$CRTVWR$&
PWD$&SF=$RPTQUERY$
BORemoteMidtierURL=$CRTXILOC$/arsys/$RPTLOC$?init=$CRTVWR$&
PWD$&SF=$RPTQUERY$
Page 762 of 4705
Home
The $RPTLOC$ parameter refers to a report file location relative to the directory
specified as the Reporting Working Directory in the Mid Tier Configuration Tool. See
BMC Remedy Mid Tier configuration for information about configuration tool options. If
the directory specified in the Mid Tier Configuration Tool is not the web server's
document root, you must include the web server's path to the configured directory
before the $RPTLOC$. In this example, arreports is a virtual directory configured on
the web server to point to the parent of $RPTLOC$.
Note
If you are using Business Objects XI and your context path is not arsys,
ensure that you enter the context path in the BMC Remedy Mid Tier
Configuration Tool as described in Configuring the Report Settings page.
Otherwise, your reports will fail.
Edit Command Leave blank (not supported)

Create Command Leave blank (not supported)
Managing reports with the Report form

The Report form stores report definitions and metadata about the report. This section describes
most of the fields in the Report form. For information about using the locale field and localizing
reports, see Managing localized Crystal and Web reports.
To appear in the Report Console or in the ReportSelection form, a report must have an entry in the
Report form. This occurs automatically when you create and save a new Web or BMC Remedy AR
System report. For many reports, no further action is required. You should only make modifications
directly in the Report form when you need to take one of the following actions:
Change the group permissions for a report, or change the availability of the report.
Modify the base qualification or control query override settings.
Configure a localized copy of an existing report.
Register report definition designed outside of BMC Remedy AR System, such as a Crystal
report, that you want to make available to BMC Remedy AR System users.
The Report form stores report definitions for all report types, including Web reports, BMC Remedy
AR System reports, and Crystal reports. It also stores metadata about the report, including the
The report name, report type, and description
The associated form and the report definition file
The report permission and availability settings
An optional base qualification and query override controls
Localization settings
Page 763 of 4705
Home
The following sections provide information about how to work with reports:
Configuring report permissions and visibility settings
Controlling query overrides
Combining report queries
Report form fields used by applications
Deleting report definitions
Displaying external reports
Configuring report permissions and visibility settings

When a new report is created, it is automatically available for any users who are members of the
same groups as the user who created the report, except for Public. (If the user creating the report is
a member only of Public, then the report is available to Public.) The groups that have permission to
a report are listed in the Assignee Groups field of the Report form.
There are several settings you can change to control whether other users can see a report:
Mark the report private For Web reports, select the Private check box in the Report
Designer. This removes all groups from the Assignee Groups field in the Report form when
the report is saved. In this case, only the report creator and Administrator can see the report.
This is the default setting when a new report is created.
Set report permissions Add or remove groups in the Assignee Groups field in the
Report form.
Mark the report invisible To prevent a report from appearing in the Report Console or
the ReportSelection form, but still allow workflow to run the report, set the Visible in
Console field in the Report form to No.
Set status to inactive or pending To prevent a report from appearing in the Report
Console or ReportSelection forms, and prevent workflow from running the report, set the
Status field to Inactive or Pending. You can use the Pending status to let reviewers know
that the report is ready for review.
Controlling query overrides

When a user selects a report to run in the Report Console, the Override check box appears. If
allowed, the user can determine whether a qualification added at runtime will override the query
built into the report, or be added to the built-in query with an AND operator. The report creator or an
administrator can configure settings in the Report form to control whether overrides are allowed.
Note
Overrides do not affect a base qualification. Users can override a query built into the
report definition, but if there is a base qualification defined in the Report form, the base
qualification is always included when the report runs, whether or not Override is selected.
Page 764 of 4705
Home
Override behavior is managed by these fields in the Report form:

Override Query in Report? This field sets the default value of the Override option in the
Report Console. If this is set to Yes, the Override check box is selected, and if it is set to No
, the Override check box is blank. This field is automatically set to Yes for BMC Remedy AR
System reports and to No for Web reports.
Lock Override Option This field determines whether the Override check box is
read-only in the Report Console. If this is set to Yes, the Override option is read-only and
the user cannot select whether an added query will override the report query. If this is set to
No, the user can change the Override option before running a report. The default value for
this setting is No for both BMC Remedy AR System and Web reports.
Tip
By setting Override Query in Report? to No and Lock Override Option to Yes, you lock
in the query in the report definition, so that the user can only further refine the query, and
cannot broaden it.
Combining report queries

Reports can include query definitions of the following types:
Query contained in the report definition This is any query in the report definition, for
example, when you create an ad hoc report in the Report Console.
Base qualification The administrator can enter a base qualification using standard BMC
Remedy AR System syntax in the Base Qualification field of the Report form. This allows
the administrator to add a query to an existing report, without modifying the report definition
itself.
In a base qualification, you must use the database field name and not the field label on the
form.
Runtime qualification The user running the report can add additional qualifications to
the query at runtime.
Active link query An active link that runs a report can include a qualification.
In any case where the Override option is not selected and the report includes more than one of
these qualifications at runtime, the different queries are joined with an AND operator. Base
qualifications are never overridden and are always joined to other qualifications with an AND
operator.
Therefore, the effect of combining qualifications is to narrow the report to include only those entries
that match all conditions of the combined queries.
Page 765 of 4705
Home
Report form fields used by applications

Some fields in the report form are used by reports installed with BMC Remedy applications, but not
with ad hoc reports created in the Report Console. These include:
Category fields These cause reports to be filtered by the Category menu in the Report
Console. They form a hierarchy with three levels. All three, or none, should be set. You can
create your own categories by using these fields if you need to.
Date range fields These are used by BMC Remedy application reports only.
Report set name This field used by BMC Remedy application reports only. The
combination of the report set name and locale must be unique.
Deleting report definitions

Only the administrator and the person who created a report can delete it. There are two possible
ways to delete a report definition:
Select the report in the Report Console, and then click Delete.
Search the Report form for the report, and then select the entry in the results list, and click
Delete.
Note
To make a report unavailable without deleting it, select Inactive or Pending in the Status
field of the Report form, or set Visible in Console to No.
Displaying external reports

If you create a report by some means outside of the Report Console, such as a Crystal report or a
report definition in a browser, and you want it to appear in the Report Console or in the
ReportSelection form, you must manually add an entry for the report to the Report form and attach
the report definition file in the Report Definition File field.
If your server is a Unicode server, you cannot create a record in the Report form by attaching an .
arr file created in a browser. Instead, use the ReportCreator form to create reports on a Unicode
server.

As an administrator, you can use BMC Remedy Flashboards to monitor the status of the reports
that are run and published. For more information about creating flashboards, see Creating and
managing flashboards.
The following topics provide information about how to monitor reports using flashboards:
Page 766 of 4705
Home
Scheduled report parameters

Pending reports parameters
Report status parameters
Scheduled report parameters

You can use a flashboard to display the values of the parameters stored in the AR System Job form
for an individual report. The parameters include:
Job ID A unique identifier for a report.
Job Name A unique string to identify a report.
Status The execution status for a report (Active/Inactive/Disabled).
Parameters Report parameters that will be used to run and publish a report.
Previous Collection Time The most recent time that the report was scheduled to run.
Next Collection Time The next time when the report is scheduled to be run.
Schedule Start Time The start time and day when the report is scheduled to run.
Schedule End Time The end time and day when the report is scheduled to run.
Type The time interval that the report is scheduled to be run (Run Once/Daily/Weekly/
Monthly)
Recurrence An indication of whether the schedule should be repeated.
Pending reports parameters

You can use a flashboard to display the status of the jobs that can be run in the AR System
Pending Job Queue using the following parameters:
Job ID A unique identifier for a report.
Status The execution status for a report (Active/Inactive/Disabled).
Submitter The name of the user who submitted the report to be run and published.
Create Date The date that the report is scheduled to be run.
Modified Date The date that the report was last modified.
Report status parameters

You can use a flashboard to display the values of the parameters stored in the AR System Publish
Report form for an individual report that has been run and published. The parameters include:
Report Name A unique string to identify a report.
Run As The name of a user to impersonate when running a report.
Status The execution status for a report (Pending/Ready/Done/Failed).
Publish Option The method to distribute a report after it is run (such as Email).
Time Zone The time zone selected in the Report Console to run a report.
Report Parameters Report parameters that will be used to run and publish a report.
Export Options The output file format after the report is run. The available options are
PDF, Word, Powerpoint, Excel, HTML.
Email List List of recipients to distribute a report to.
Status Email List List of recipients to distribute the status of a report to.
Page 767 of 4705
Home
Attachment with Result The name of the file that is attached to a report.
Status Message Any status message that occurs while running or publishing a report.
Reporting in BMC Remedy AR System
Note
For information about how to create and run Web and BMC Remedy AR System reports
in the Report Console, see Running reports in the Report Console . For information about
configuring BMC Remedy AR System to use Crystal reports, see Using Crystal reports
with BMC Remedy AR System.
The Report Console provides a central location for all reporting tasks. Users can create and run ad
hoc reports based on user-specified criteria, and run existing reports that are defined by others or
installed with BMC applications.
The Report Console
Using the Web report type, browser users can create nicely formatted reports and save them in
common formats such as Adobe PDF. The necessary components to support Web reports are
automatically installed with the mid tier and do not require you to purchase or install any additional
third-party components. The Web report type is added to the existing BMC Remedy AR System
and Crystal report types.
For an overview of each report type, see Report types.
The following topics provide information about reporting in BMC Remedy AR System:
Report Console and related report forms
About publishing and scheduling reports
Web report limitations
Report Console and related report forms

The Report Console is integrated with the reporting components that support Web reports and with
other BMC Remedy AR System reporting forms. Administrators should use the Report Console to
design any new reports for browser users. All users can run reports of all types from the Report
Console.
Page 768 of 4705
Home
The Report Console is based on the AR System Report Console form and uses other supporting
forms such as the AR System Report Designer form, the Report form, and the ReportType form.
The Report Console opens when you click the AR System Report Console link in the Quick
Links section of the home page, or when you click the Report button that appears with search
results in a browser.
When you create or edit a report, the AR System Report Designer form opens as part of the Report
Console. This form allows you to design, modify, and save reports. When you click Back on this
screen, you return to the main Report Console.
Designing a report
Report form Stores the report definition and metadata about the report. Administrators
use this form to manage certain report settings. See Managing reports with the Report form.
ReportType form Stores the available report types. The Web, BMC Remedy AR System,
and Crystal report types are installed with BMC Remedy AR System. Administrators can
define additional report types.
Note
Two legacy reporting forms, ReportCreator and ReportSelection, are also installed with
BMC Remedy AR System. The ReportCreator form is used to edit the BMC Remedy AR
System report type. The ReportSelection form is used to display available reports in a
browser. For information about creating BMC Remedy AR System type reports, see
Defining BMC Remedy AR System reports .
About publishing and scheduling reports

Using the report publish option on the Report Console, a user who has view and run permissions
for a web report can send the report to a specified recipient or list of recipients by using an email.
For details about report permissions, see Configuring report permissions and visibility settings .
Page 769 of 4705
Home
Using the report schedule option on the Report Console, an administrator can specify the time
and date to run and publish a web report. The administrator can assign the Job Scheduler role to
groups so that members can use the report schedule option. For more information about role-based
permissions, see Role-based access overview.
Note
The report publish and schedule options are enabled for Web reports only, not for BMC
Remedy AR System reports.
For an example about modifying a qualification when scheduling a report, see Publishing reports.
Forms for publishing and scheduling reports

Administrators manage report publishing and scheduling by using the following forms:
AR System Job Stores the parameters of a report that a user has scheduled to be run
and published at a specified interval. It also stores the parameters related to multiple reports
such as, email IDs, export options. The Parameters field in the form, which also stores
query and qualification data, is applicable for all the job items linked by the job ID.
AR System Job Item Stores a unique job ID and the parameters of the report that is
scheduled to be run and published at a specified interval.
AR System Pending Job Queue Stores the parameters of the jobs that are ready for
execution. It is an intermediary queue.
Note
Only administrators have permission to delete scheduled reports from the Pending
Job Queue form.
AR System Publish Report Stores the parameters for filtering and publishing report
results. It stores the external qualification, in encoded format, that users enter when
searching a form.
Note
If the administrator disables unqualified search in the AR System Server Information form,
then a 1=1 qualification does not work when running reports. The user receives an error
when attempting to run a report for an unqualified search.
Page 770 of 4705
Home
Automated workflow for scheduling and publishing reports

The following automated workflow executes the scheduling and publishing of the reports that are
associated with these forms:
1. Every report that is either published immediately or scheduled for publishing at a later time is
associated with a unique job ID that it obtains from the Job Item form. Any report parameters
that are passed from the Report Console are also stored in the Job Item form.
2. The unique job ID and report parameters from the Job Item form are pushed to a Job form,
along with any schedule parameters that are passed from the Report Console. The schedule
parameters are used as the basis for computing the next collection time that a report is run.
3. The Job form for a report is pushed to the Pending Job Queue form on an hourly basis.
Based on the next collection time specified in the Job form, a report is run and published
immediately, or on a recurring schedule (daily, weekly, monthly). The Job Type parameter in
the Job form determines how a report will be published (such as email distribution).
4. At the next collection time, the data, report parameters, and job parameters for a report are
pushed from the Pending Job Queue to the Publish Report form. The report is run and the
results published to the specified recipient or list of recipients. If there is an error, an error
message is sent by email to the user who published the report, or a specified list of
recipients.
Related topics
Publishing reports
Scheduling reports
Web report limitations

Web reports do not support output directly to .arx, .csv, or BMC Remedy AR System XML
format. To generate output directly to these formats, you must use an BMC Remedy AR
System report.
Tip
To generate .csv output based on a Web report, save the report to Microsoft Excel
format. Then open the report output in your spreadsheet application, remove the
rows at the top and bottom of the report that do not contain field data, and then
save it in .csv format.
Web reports do not support diary fields, attachments fields, or attachment pools. Web
reports do not support currency value or currency type, but do support currency fields.
You must perform the following steps to print Web reports in HTML format.
1.
Page 771 of 4705
Home
1. Run a web report from the Report Console.

2. In the report viewer, click Print Report.
3. In the Print dialog box, click Cancel. You see the complete report in HTML format.
4. Press Ctrl+A to select the complete HTML report. You can alternatively select
specific pages that you want to print.
5. Copy and paste the selected report.
Note
When you print the report in PDF format, some of the columns might
truncate. So, you must reduce the number of columns in the report to fit the
screen size.
Reporting using table fields and results list fields

Table fields and results list fields provide a way to capture and display data from one or more
requests. By default, these field types include a Report button when the form is opened in a
browser. When the user clicks the Report button, the Report Console opens with a pre-selected set
of criteria. The same is true if the user runs a quick report by selecting from the My Reports option
in a results list.
When the user clicks the Report button on a table field or results list, or runs a report from the My
Reports list, the Report Console only lists reports that are associated with the current form. In
addition, if the user selected records in the table or results list before clicking Report, the IDs for
the selected records are passed to the Report Console, and only those records are used when the
report is run. If the Report Console opens as a result of the user selecting a report from the My
Reports list, then there is a pre-defined qualification that is passed to the Report Console.
In these cases, the Report Console is opened by an Open Window active link action as a dialog
window, dedicated to reporting on that form. The On Dialog Open Action field in the active link is
populated to set the context form name and to pass that information, along with any selected
records, into the Report Console.
You can change the label of the Report button by editing the value of the Report Button field
property for the table field or results list field. If you set a blank label, the Report button does not
appear on the table or results list field. For information about setting table properties, see Actions
that trigger cache events.
Running a report by using an Open Window active link

The Open Window active link method of running a report is useful when you want to run a report as
part of an application, or create your own interface for launching reports. Within the definition of the
active link, you direct the report to a specific form, and also define which requests to include in the
report. After defining the active link, attach it to a workflow trigger, such as a button field. When the
Page 772 of 4705
Home
user clicks the workflow trigger where the active link is attached, a new browser window opens to
display the report.
The following procedures outline methods of creating an Open Window active link:
Creating an Open Window active link for web reporting
Attaching an Open Window active link to a form with a button field
For general information about creating active links and related properties, see Creating active links.
Creating an Open Window active link for web reporting

1. In BMC Remedy Developer Studio, create an active link.
2. On the Associate Forms panel, specify the form that you want to report on.
3. Add an Open Window action, and complete the fields as described in the following table.
Open Window action fields
Field
Selection
Window
Type
Report
Target
Location
New
Data Source
SERVER
Server
Name
Name of the AR System

server on which the form
being reported on is
located
Form Name
Name of the form being

reported on
Form View
Name of the form's view
More information
Selecting New causes a new window to open for each report generated. If
you select Current, the active link uses the existing open window from where
the active link is initiated.
Name
Report Type
The type of report
Report
Location
Report Form (or

Embedded)
Report
Name
Name of the report as

stored in the Report form
(not the file name of the
attachment)
Report
Destination
Screen or File
Qualification
A query string that

determines which entries
from the form to include
in the report
The menu's data is read from the ReportType form on the AR System server
being used for the Open Window action.
If you want to use a string from a local field, use the EXTERNAL keyword,
for example, EXTERNAL($QueryStringField$). If this string and the Entry
IDs string are both left empty, all entries of the form being reported on are
included in the report.
Page 773 of 4705
Home
Field
Selection
If No
Requests
Match
Do Not Show Any

Message
More information
4. Click Show Advanced, and complete the fields as described in the following table.
Advanced fields
Field
Selection
More information
Entry IDs
A comma-separated
list of entry IDs from
Only these entries are displayed in the report. If this string is filled and contains fewer
than 256 entry IDs, it overrides the Qualification String. Otherwise, the Qualification
the form being

reported on
String takes precedence. If both are left empty, all entries in the form are included in
the report.
Yes or No
Some report engines allow the Qualification String (or Entry IDs) to override a query
that might be stored as part of the report definition. This value specifies whether the
Query
Override
report engine should do so.

Report
Operation
Create
Used to
create a new
report
definition file
If you select Crystal Report in the Report Type field, then Edit and Create are not
valid options for the Operation field.
Edit Used
to edit an
existing
report
definition file
Run Used
to run a
report
Character
Encoding
The character set to

be used for the
report
Select Use Server to apply the same character set encoding used by the server.
Attaching an Open Window active link to a form with a button field

1. In BMC Remedy Developer Studio, select a view of a form and create a new button field.
2. Attach the active link to the button field. See Creating active links.
3. Save the form.
Setting limits on reports that users save

Users can create and save reports for forms in a browser with the My Reports toolbar button (see
Using the My Reports toolbar button ). The larger the number of forms and saved report sequences,
the more memory is required on the mid tier.
To limit the number of forms and saved report sequences cached for faster user access, edit the
arsystem.myreport.report_cache_limit property in the config.properties file. This property
indicates the number of "My Reports" definitions to cache per form. For example, if you set the
Page 774 of 4705
Home
property to 20 (the default), a maximum of 20 "My Reports" definitions are saved in the cache for a
given form. The cached definitions allow faster report generation but take up mid-tier memory for
caching.
Using Crystal reports with BMC Remedy AR System

By installing the appropriate SAP BusinessObjects or SAP Crystal Reports components (not
included with BMC Remedy AR System), you can create or use Crystal reports based on BMC
Remedy AR System data and make them available to BMC Remedy AR System users.
To view Crystal reports designed for BMC Remedy AR System on the Web, you must install one of
the following products on a Windows computer:
SAP BusinessObjects Enterprise (BOXI), for managed reports
Crystal Reports Server, configured for unmanaged reports
"Managed" reports are cached with their data by the BusinessObjects Central Management Server
(CMS). This allows you to take advantage of BusinessObjects server functionality such as
scheduling reports. "Unmanaged" reports are generated on demand (at run time) and are then
discarded.
For a list of the compatible web application servers, see Compatibility matrix in the BMC Remedy
ITSM Deployment online documentation.
Note
You can also create formatted reports for the web by using the BMC Remedy AR System
Report Console. See Reporting on BMC Remedy AR System data and (for administrators)
Configuring reporting.
The following topics provide information about how to use crystal reports:
Mid tier installation options for Crystal reports
Configuring the Crystal reports integration
Report definitions for Crystal reports
Recommendations for Crystal Reports for the Web
Mid tier installation options for Crystal reports
Important
In the BMC Remedy AR System installer, the AR Web ReportViewer is called the AR
Crystal Web Application.
Page 775 of 4705
Home
The AR Crystal Web Application is installed by default only when installing BMC Remedy AR
System on Windows, and only when the installer detects registry settings indicating that a
supported version of BusinessObjects Enterprise or Crystal Reports Server is already installed.
The AR Web ReportViewer and BMC Remedy AR System ODBC Driver are also installed with
the AR Crystal Web Application
With the AR Crystal Web Application, the BMC Remedy AR System ODBC Driver ( arodbc
VerNum.dll) is also installed as a system DSN (Data Source Name). This allows the CMS to
retrieve BMC Remedy AR System data for the report.
Note
When file names are mentioned in the documentation, the placeholder VerNum
represents the version number of the release as it appears in the file name. In some
cases, this includes a build number. For example, in release 9.0.00, the BMC Remedy AR
System ODBC driver is named arapi90.dll or arapi90_build xxx.dll.
The installer prompts you for information about Crystal reports settings. You can provide these
settings at installation time or after installation. See Configuring the Crystal reports integration and
Configuring the Report Settings page.
Configuring the Crystal reports integration

To complete the integration of Crystal reports, you must set the correct report settings for the mid
tier and the AR Web ReportViewer, and certain configuration settings and directory permissions for
BusinessObjects Enterprise or Crystal Reports Server.
The following topics provide information about configuring Crystal reports:
Configuring BMC Remedy AR System settings for Crystal reports
Configuring BusinessObjects Enterprise
Configuring Crystal Reports Server
Configuring BMC Remedy AR System settings for Crystal reports

Configure the BMC Remedy AR System report settings for Crystal reports using the Report
Settings page of the BMC Remedy Mid Tier Configuration Tool or the AR Web ReportViewer
Configuration Tool. For information about how to set the options in the Report Settings page, see
Configuring the Report Settings page.
Which tool you use depends upon where you have installed the mid tier and AR Web ReportViewer
:
Page 776 of 4705
Home
If the mid tier and AR Web ReportViewer are installed together on the same computer as the
BusinessObjects or Crystal Reports server, you use the BMC Remedy Mid Tier
Configuration tool to set the report settings.
If the mid tier is installed on a different computer, then you use the AR Web ReportViewer
Configuration tool to configure the AR Web ReportViewer, and the BMC Remedy Mid Tier
Configuration tool to configure the report settings for the mid tier.
You can access the Mid Tier Configuration tool at http//:<midTierHost>/arsys/shared/config/
config.jsp.
Configuring BusinessObjects Enterprise

When you install the mid tier or AR Web ReportViewer with BusinessObjects Enterprise, you do not
need to modify any BusinessObjects settings.
To ensure that BusinessObjects Enterprise is properly configured to work with BMC Remedy AR
System:
Configure BusinessObjects Enterprise with sufficient named licenses. Consult the
BusinessObjects Enterprise documentation for information about SAP licensing
requirements.
Make sure that all necessary services are running and enabled in the page of the
BusinessObjects Central Configuration Manager and Central Management Console. See the
BusinessObjects documentation for information about the necessary services and using
these applications.
Assign the directory defined as the Reports Working Directory (for example, ARInstallDir\
midtier\reports) and the Windows Temp directory (for example, C:\WINDOWS\Temp)
permissions for the Windows user account that the web server uses.
After running a Crystal report through the mid tier, verify that the report is published properly.
To view a list of the published reports, open the ARReports folder in the Central
Management Console.
You can access the Central Management Console from the Windows Programs menu.
(Optional) By default, the CMS is configured to limit the number of records returned when
previewing or refreshing a report to 20,000. If you run large reports and see errors indicating
you have hit this limit, you can change the setting in the BusinessObjects Central
Management Console. This setting is a property of the CMS ReportApplicationServer service
.
( Optional ) Configuring the Report Application Server service properties

1. Log on to the Crystal Reports Server Central Management Console.
You can access the Central Management Console from the Programs list in the Windows
Start menu.
2. Open the Servers tab and locate the Report Application Server service in the Service
Categories section.
3.
Page 777 of 4705
Home
3. Right-click the service and open the Properties dialog box.

4. To change the default number of records returned, locate the setting labelled "Number of
database records to read when previewing or refreshing a report " and change the
setting as needed.
5. Click Save & Close.
6. Restart the Report Application Server service.
Configuring Crystal Reports Server

Although Crystal Reports Server supports both managed and unmanaged reports, you must
configure it for unmanaged reports for use with BMC Remedy AR System.
To ensure that Crystal Reports Server is properly configured to work with BMC Remedy AR System
:
Set the -ipport and -reportdirectory parameters in the properties of the Report
Application Server service, as described in this section.
Enable the Guest account, as described in this section.
Configure Crystal Reports Server with sufficient concurrent licenses. Consult the
BusinessObjects Enterprise documentation for information about SAP licensing
requirements.
Make sure that the necessary services are running and enabled in the Central Configuration
Manager, Servers tab. This includes at least the Central Management Server (the CMS) in
the Servers List section, and the Report Application Server in the Service Categories section
.
Make sure that the C:/WINNT/Temp folder has permissions for the user that the web server
runs as, because reports are copied to this folder before they are published to the CMS.
Configuring the Report Application Server service properties

Start menu.
2. Open the Servers tab and locate the Report Application Server service in the Service
Categories section.
3. Right-click the service and open the Properties dialog box.
4. In the Command Line Parameters field, add the following settings to the end of the existing
command line:
-ipport 1566 -reportdirectory " <ARInstallDir>\midtier\reports "
The value of the -reportdirectory parameter must match the path in the Reporting
Working Directory, set in the Mid Tier Configuration Tool or AR Web ReportViewer
Configuration Tool. See Configuring the Report Settings page.
6. Restart the Report Application Server service.
Page 778 of 4705
Home
Enabling the Guest account

Start menu.
2. Open the Users and Groups tab.
3. In the User List section, right-click Guest and open the Properties dialog box.
4. Clear Account is disabled.
Report definitions for Crystal reports

Crystal reports are created using the Crystal Reports designer application, which is a Windows
application from SAP BusinessObjects. Report definition files created using the Crystal Report
designer are saved with the file extension. rpt. After creating a Crystal report, you make the
definition files available for web reporting by creating an entry to the Report form.
For specific information about designing Crystal Reports for BMC Remedy AR System, see
Integrating Crystal Reports with BMC Remedy AR System .
Important
To prevent user names and passwords from being embedded in data from Crystal reports,
modify your System DSNs to remove the user name and password. For more information,
see Establishing a system DSN for Crystal reports and Configuring the ODBC driver for
Crystal reports. Additionally, when saving, select the Save Without Data option and clear
the Report Refresh on Open option to prevent the original data from being displayed
each time a report is displayed.
If form fields are modified, especially fields on which a Crystal report is reporting, then you must
update the Crystal report; otherwise, you will receive the following error message: Error detected
by database DLL. [On Report Server: serverName].
Updating a Crystal report

1. Open the report in Crystal Designer.
2. Select Database > Verify Database.
A message appears, notifying you whether the report is up to date.
3. Map your report fields to the updated report.
4. Save the report and reattach it to the corresponding entry in the Report form.
If you have report definition files created with Crystal Report Designer application, create entries for
the files in the Report form to make them available for web reporting.
Page 779 of 4705
Home
Recommendations for Crystal Reports for the Web

The following topics discuss ways to make sure that Crystal Reports work properly:
BMC Remedy AR System and BusinessObjects display integration
Establishing a system DSN for Crystal reports
Configuring the ODBC driver for Crystal reports
Restricting the number of records retrieved
Setting up optimal formatting for all environments
Saving a Crystal report
BMC Remedy AR System and BusinessObjects display integration

After BMC Remedy Mid Tier or AR Web ReportViewer executes its statements and the Crystal
report is displayed, BusinessObjects code is responsible for the controls in the display. Therefore,
you cannot use BMC Remedy AR System settings to modify the display.
Establishing a system DSN for Crystal reports

Every AR System server that a report references needs a System Data Source Name (DSN). The
recommended format of this name is serverName_DSN. For more information, see Creating
multiple data sources.
If the Crystal Report Designer application is installed on a different system from the Crystal Web
Component server, then the administrator must make sure that the System DSN on the Crystal
Web Component server has the same name as the SystemDSN embedded in the report design.
For example, if an application developer who is developing on Computer A has created a system
DSN called myServer_DSN, and the Crystal Web Component server is on Computer B, then
Computer B will also need to have a system DSN named myServer_DSN.
Important
Crystal Designer and Crystal Reports use the user name and password in the System
DSN to log on to AR System. When you create reports in Crystal Designer, you use a
System DSN complete with a user name and a password. If Crystal Designer requests
user information, do not provide it. The information in the System DSN should be sufficient
. If not, provide the required information in the System DSN, not in Crystal Designer. Do
not use a User DSN when you create or run Crystal Reports. Before you run any reports,
however, modify your System DSN to remove the user name and password. This causes
Crystal Reports to use the user name and password of the user currently logged in.
Failure to remove the user name and password from the System DSN might give you
unexpected results when you run your report.
Page 780 of 4705
Home
Configuring the ODBC driver for Crystal reports

Before creating a Crystal report, configure the ODBC settings on the computer you are using to
create the report. These settings will prevent the user name, server name, and password from
being embedded in the report.
For more information about using ODBC with Crystal Reports, see Integrating Crystal Reports with
1. Go to the Windows Control Panel, and select Administrative Tools.
2. Double-click Data Sources (ODBC).
The ODBC Data Sources Administrator dialog box opens.
3. Click the System DSN tab.
Important
Be sure to click the System DSN tab, not the User DSN tab. Never use the User
registered version of the ODBC driver to create reports.
ODBC Data Sources Administrator dialog box

4. Select AR System ODBC Data Source, and click Add.

The Create New Data Source dialog box appears.
Create New Data Source dialog box
5.
Page 781 of 4705
Home
5. Select AR System ODBC Driver, and click Finish.

The AR System ODBC Setup dialog box appears.
ODBC Setup dialog box
6. Specify the server name and user name to connect to the database.
You do not need to fill in the password.
7. Select the Use Underscore check box in the ODBC dialog box.
This will confirm that the ODBC driver translates special characters such as colons, spaces,
and so on, into underscores.
8. Select the Use Labels check box to use field labels based on the locale you specify in the
Report Locale field.
Note
It is recommended that you deselect the Verify On First Refresh report option in
Crystal Reports. Then, you do not need to match the Use Labels option for the
report to run correctly. If the Verify On First Refresh option is selected, you must
match the Use Labels option when you create the report and at runtime. For
example, if you select the Use Labels option when you create the report, you must
also select it when you run the report. Conversely, if you unselect the Use Labels
option when you create the report, you must also unselect it when you run the
report
9. In the Report Locale field, enter the locale for the language in which you want to see the
report.
Page 782 of 4705
9.
Home
Note
If you have installed two localized views (for example, German and French), and
you are using the German localized view and the report locale setting is set to the
French locale, the data returned will be in French, though the static report text will
be in German.
10. Click OK to save the settings.
Restricting the number of records retrieved

To restrict the number of records retrieved from the database when a report is run, Crystal Reports
enables you to use a Selection Formula. A Selection Formula can be added in a Crystal report by
choosing Report > Edit Selection Formula. Use the Run If Qualification panel in the Open
Window Active Link action. The data can be entered through the data stored in a form or hard
coded. When the report is run, this qualification is used to select data from the AR System forms
specified in the report.
Setting up optimal formatting for all environments

When you create a report and align the fields in the designer, and then view it in the Crystal
Designer, it might appear to be well aligned, but when you view it on the Web, the fields might not
be aligned. To address this issue, use horizontal and vertical guide lines in reports to align fields.
1. Right-click inside the designer and make sure the Snap to Grid option is not selected.
2. Select Show guide lines in design and Show guide lines in preview options from this
menu.
3. Click on the top and left page margins to make vertical or horizontal lines appear in the
designer.
4. Move the fields next to the guide lines to attach them to the guide lines. This way the column
headings and the column content can be left aligned as well as top aligned.
Note
Guide lines are displayed only in the design mode and not when the report is
actually viewed.
Guide lines in Crystal Report Designer

Page 783 of 4705
Home
Saving a Crystal report

When saving a Crystal report, do not save the report with data. You will see this as one of the
options in the Crystal Designer under the menu File > Save Data with Report, but do not select it.
Managing localized Crystal and Web reports

When you create an ad hoc report in the Report Console, it has the locale of the computer in use
when the report was created. You cannot localize an ad hoc report.
Some Web reports installed with BMC Remedy applications are localized, and you can also add
localized Crystal reports to BMC Remedy AR System. In this case, entries in the Report form and
Report Definition form (for Web reports) manage the localized report definitions.
Warning
This section contains advanced details about the reporting infrastructure in BMC Remedy
AR System. You should not make changes as described in this section unless you have
an in-depth understanding of advanced reporting using Web or Crystal reports.
The following topics provide information about how to manage the localized Crystal reports and
web reports:
Setting the Report form for localized Crystal reports
Localized Web reports
Using exported data with BMC Remedy Data Import
Setting the Report form for localized Crystal reports

For Crystal reports, you must provide a separate report definition file for each locale. Create an
entry in the Report form for each locale. In particular, set the following fields:
Report Definition File Attach the localized report definition file in this attachment field.
Locale Enter the locale code, for example, FR for French.
Report Set Name Use the same report set name for localized versions of the same
report. The combination of the report set name and locale must be unique.
Page 784 of 4705
Home
Localized Web reports

This section describes how BMC Remedy AR System manages locale settings for Web reports.
The following topics explain how to share ad hoc reports with users in other locales, and how
preconfigured Web reports, such as those installed with the BMC Remedy applications or other
reports created in the BIRT report tools, are configured for locale:
Preconfigured localized reports
Sharing ad hoc reports across locales
Preconfigured localized reports

Localized Web reports are installed by the BMC Remedy applications and you do not need to make
changes. This section describes how they are configured.
To localize a Web report created outside of BMC Remedy AR System with the BIRT report tools,
you can either localize separate copies of the report definition file, or use a single report definition
file and localize the related properties files.
Localizing separate copies of the report definition files

Create an entry for the localized Web report in the Report form. In particular, set the following fields
:
Report Definition File ---Attach the localized report definition file in this attachment field.
Locale Enter the locale code, for example, fr for French.
Report Set Name Use the same report set name for localized versions of the same
report. The combination of the report set name and locale must be unique.
Do not enter anything in the Instance ID field.
When you save the entry, workflow stores the attachment in a new entry in the Report Definition
form, and populates the Instance ID field (Report form) and Report Definition GUID field (Report
Definition form) with a matching GUID. The matching GUID links different localized versions of the
same report.
Using a single report definition file with localized properties files

To have a single report definition file with separate localized properties files, you must create a
report library and add all the localized property files to the library. The library must then be compiled
as a .zip file and added to the AR System Resource Definitions form, before creating the Report
form entry.
Preparing a single Web report definition for multi-locale use

1. Use the BIRT report tools and your localization tools to create a report library and localized
property files for Web reports.
The library file structure must adhere to the following guidelines:
Page 785 of 4705
1.
Home
Use a resource directory and make sure it has a unique name. For example, use the
report name in the directory name.
Give the properties files unique names. For example, use the report name in the
properties file names as well.
Make the names of the locale-specific properties files match the main properties file.
For example, if the primary property file is named messages.properties, then the
locale specific ones must be named messages_ language.properties, for example,
messages_de.properties, messages_fr.properties, and so on.
2. Add the library and property files to a .zip file. The .rptlibrary must be at the top level of the
zip file, with the with the subdirectories containing properties files directly below it. For
example: mylib.rptlibrary mylib_resources/ mymessages.properties
mymessages_de.properties mymessages_fr.properties
3. In the AR System Report Definitions form, create a new entry and attach the .zip file to it.
Set the type to BIRT Library
Leave the locale field blank
4. In the Report form, create and save an entry that contains the report definition file as an
attachment.
When you save this entry, workflow creates a corresponding entry in the Report Definition
file and generates a GUID.
5. Create additional Report form entries for each locale. In particular, set the following fields:
Use the same Report Set Name value as in the main Report form entry.
Enter a unique value in the locale field to identify the locale.
Copy the GUID from the Report Definition file entry that is associated with the main
Report form entry.
Sharing ad hoc reports across locales

When you create and save an ad hoc report, the Locale field of the report form entry is set by
workflow in the following ways:
If the locale of the computer you are using to create the report is set to English, the value in
the Locale field is $NULL$.
If the locale of the computer you are using to create the report is set to any language other
than English, then the appropriate language code is set in the Locale field of the Report
form entry, for example, fr for French.
Users can only see those Web reports for which the Locale field in the Report form entry matches
the locale set on the user's computer. ( $NULL$ is interpreted as English.) This means that to share
an ad hoc report with a user in another locale, you must make a copy of the report for the other
locale.
Making an ad hoc report available in another locale

1. In the Report Console, open the original report for editing. See Defining BMC Remedy AR
System reports.
2.
Page 786 of 4705
Home
2. Click Save As, and give the report a different name, such as My Report-Spanish.
3. Open the Report form, and then locate and open the record for the copied report.
4. In the Locale field, enter the two-character or four-character abbreviation for the locale
where you want to share the report, such as es for all Spanish locales or pt_BR for Brazilian
Portuguese.
5. Save the entry.
Users in the designated locale can now see the copy of the report that was configured for their
locale. After you have set the locale for the copy of the report, the copy no longer appears in the list
of reports in your Report Console.
Note
The steps in this procedure do not cause the report headings and other metadata to be
translated; the report definition remains in the original language. To create translated
copies of ad hoc reports, you must create the report on a computer configured for the
desired locale.
Using exported data with BMC Remedy Data Import

If you plan to import data into an AR System form by using BMC Remedy Data Import, you must
export the data in one of the following file formats.
File formats used with BMC Remedy Import
Data format
Extension
AR Export
.arx
AR XML
.xml
Comma-Separated Value (CSV)
.csv
ASCII
.asc
Report in XML format (partial view), displayed in browser

Page 787 of 4705
Home
Configuring the BMC Remedy Approval Server

This section explains how to configure BMC Remedy Approval Server. You must use the AP:
Administration form for managing and configuring approval server. To access the AP:Administration
form, you must be a approval server Process Administrator.
The following topics provide information to configure the BMC Remedy Approval Server:
Working with the AP-Administration form
Process administrator overview
Configuring process administrator capabilities
Configuring Approval Server to work with flowcharts
Configuring BMC Remedy Approval Server with a separate plug-in server instance
Related topics
Configuring approvals with BMC Change Management
Approvals in business process
Working with the AP-Administration form

Process administrators use the AP:Administration form to perform the following tasks of managing
and configuring approval server:
Creating or configuring other process administrators and alternates
Accessing AR System server settings that are specific to approval server
Renaming related processes and forms
Managing approval server processes, rules, notifications, roles, and forms
To access the AP:Administration form, you must be a approval server process administrator or an
AR System administrator.
AP:Administration form
Page 788 of 4705
Home
To open the AP:Administration form

1. Log in to BMC Remedy AR System as an administrator or a process administrator by using
a browser.
2. Open the AP:Administration form by using the link on the default AR System Home Page
form.
If you do not see a link on AR System Home Page, in a browser, enter the following URL
and press Enter:
http://<hostName>/arsys/forms/<serverName>/AP:Administration
hostName is the name of the web server, and serverName is the name of the AR System
server.
This section only describes how to use the following items on the AP:Administration form:
Administrator tab This tab enables you to create and configure process administrators.
See Configuring process administrator capabilities.
Server settings link This link enables you to configure approval server logging, and
customize other settings.
For information about using other tabs and links on the AP:Administration form, see:
Defining an approval process
Defining approval rules
Integrating Approval Server with an application
Adding notifications to the approval process
Defining roles
Process administrator overview

A process administrator is a BMC Remedy AR System user with the authority to define an approval
process and to perform administrative tasks related to the AR System. The first process
administrator must be set up by the BMC Remedy AR System administrator, but others can be set
up by an existing process administrator.
The process administrator is a more powerful authority than the signature authorities (approvers)
who actually sign approval requests. A process administrator has the following responsibilities:
Designing the approval process to generate approval signature data when BMC Remedy AR
System workflow needs to be authorized
Connecting approval server forms to workflow to accomplish the designed approval process
This includes configuring routing, and creating the list of authorized approvers. See also
Adding approvals to an application.
Page 789 of 4705
Home
Overriding a process, or parts of a process, when circumstances arise that must be handled
outside of established workflow.
See Performing overrides.
Creating and deleting other process administrators as needed
Other process administrators can have full or limited authority. A process administrator with
limited authority can perform the following activities:
Acting as an administrator to manage only specific processes that are assigned by a
process administrator with full authority
Acting as an override-only administrator to approve or reject requests regardless of
the approver list for the assigned processes
Configuring process administrator capabilities

Administrators who have the appropriate privileges can use the AP:Administration form to create
process administrators with the following types of authorities:
Full Admin authority Grants the ability to configure and modify processes, as well as to
approve or reject requests regardless of the normal process.
Override Only Admin authority Grants the ability to approve or reject requests
regardless of the normal process, but not create or modify processes.
In this topic:
Process administrator prerequisites
Creating a process administrator
To create a process administrator
Process administrator prerequisites

The first process administrator must be created with Full Admin authority by an AR System
administrator. Subsequent process administrators can be created by any process administrator with
the Full Admin authority. To designate a user as a process administrator, the user must exist in
BMC Remedy AR System, and must be a member of the AR System Approval Admin group. If the
user ID for a process administrator does not exist, an AR System administrator must create it and
assign the user to the Approval Admin group. See the Adding and modifying user information.

This section describes how to assign process administrator authority to an existing AR System user
who is a member of the Approval Admin group.
To create a process administrator

1. Open the AP:Administration form as described in Working with the AP:Administration form .
2.
Page 790 of 4705
Home
2. Open the Administrator tab, and click Create to open the AP:Process Administrator form.
3. On the Process Administrator tab, specify appropriate values in the various fields.
For the description of the fields, see AP-Process Administrator form.
4. Click Save.
Configuring Approval Server to work with flowcharts

1. On the AR System Server Administration Console, select System > General > Server
Information.
2. On the Ports and Queues tab, check whether a private RPC private port has been defined
for BMC Remedy Approval Server.
The values of Min Threads and Max Threads for this port should be greater than one.
3. Check whether the same port is used in the approval Plugin Loopback RPC Socket setting
on the AP:Admin-ServerSettings form.
Note
The suite installer defines the RPC port and sets the same in the approval Plugin
Loopback RPC Socket automatically. Confirm that these settings exist, and define
them if they do not.
4. On the Advanced tab, set the Default Web Path to:

http:// <ARSystemServerName>:8080/arsys
For more information, see Configuring AR System servers.
5. On the Basic tab of the AP:Process Definition form, select a value from the Generate
Preview list.
6. On the General Settings page of the BMC Remedy Mid Tier Configuration Tool:
a. Set the Data Visualization Module Server to the server where the Visualizer plug-in
is installed.
b. Select the appropriate authentication server.
See Setting external authentication options.
Note
Page 791 of 4705
Home
You must have Flash version 9.x or later installed on the machine.
7. The flowchart view is compatible with BMC Remedy Mid Tier 7.1.00 and 7.0.01. You can use
BMC Remedy Mid Tier to display the flowchart view for an approval request.
Note
The Data Visualization Field cannot be seen if you are using Mozilla Firefox
2.0.0.11 on Apple MacOS 10.4.11; this is an issue with the browser.
Configuring BMC Remedy Approval Server with a separate

plug-in server instance
To configure BMC Remedy Approval Server with a separate plug-in server instance, you must
perform the following configuration actions:
1. Open the pluginsvr_config.xml file in the ARSystemInstallDir/Approval/bin directory, and
perform the following actions:
a. Locate the pluginsvr_config tag.
b. Make a note of the port number defined in this tag, and close the file.
2. In the ar.cfg or the ar.conf file, perform the following steps:
a. Locate the following plug-in entry:
Server-Plugin-Alias: ARSYS.ARDBC.PREVIEW ARSYS.ARDBC.PREVIEW
serverName:portNumber
b. Replace the existing port number in this entry with the port number from step 1.
c. Save and close the file.
3. In the armonitor.conf file, perform the following actions:
a. Remove the hash (#) symbol from the following entry:
(For Microsoft Windows)
#"C:\Program Files\Java\jre7\bin\java" -Xmx256m -Djava.net.preferIPv4Stack=

true -Djava.net.preferIPv6Addresses=false -classpath "C:\Program Files\BMC
Software\ARSystem\approval\bin;C:\Program Files\BMC Software\ARSystem\
pluginsvr\arpluginsvr80_build001.jar;C:\Program Files\BMC Software\ARSystem
\approval\bin\arasj80_build001.jar;C:\Program Files\BMC Software\ARSystem\
arserver\api\lib\arcmnapp80_build001.jar;C:\Program Files\BMC Software\
ARSystem\approval\bin\armaskingImpl80_build001.jar;C:\Program Files\BMC
Software\ARSystem\arserver\api\lib\log4j-1.2.14.jar"
com.bmc.arsys.pluginsvr.ARPluginServerMain -x "vw-pun-rem-qa63" -i "C:\
Program Files\BMC Software\ARSystem" -m
(For UNIX)
Page 792 of 4705
Home
#/opt/jdk6_64/jre/bin/java -Xmx256m -Djava.net.preferIPv4Stack=true Djava.net.preferIPv6Addresses=false -classpath /data1/ar/IA/approval/bin:/

data1/ar/IA/pluginsvr/arpluginsvr80_build001.jar:/data1/ar/IA/approval/bin/
arasj80_build001.jar:/data1
/ar/IA/api/lib/arcmnapp80_build001.jar:/data1/ar/IA/approval/bin/
armaskingImpl80_build001.jar:/data1/ar/IA/api/lib/log4j-1.2.14.jar
com.bmc.arsys.pluginsvr.ARPluginServerMain -x premlnx02 -i /data1/ar/IA -m
Note
The entry for the separate plug-in server exists in the armonitor.conf file,
but is commented by default.
b. Remove the ARSystemInstallDir\approval\bin\armaskingImpl80_build001.jar

entry from the default plug-in server entry:
"C:\Program Files\Java\jre7\bin\java" -Xmx512m -Djava.net.preferIPv4Stack=t

rue -Djava.net.preferIPv6Addresses=false -classpath "C:\Program Files\BMC
Software\ARSystem\pluginsvr;C:\Program Files\BMC Software\ARSystem\
pluginsvr\arpluginsvr80_build001.jar;C:\Program Files\BMC Software\ARSystem
\approval\bin\armaskingImpl80_build001.jar;C:\Program Files\BMC Software\
ARSystem\arserver\api\lib\arcmnapp80_build001.jar"
com.bmc.arsys.pluginsvr.ARPluginServerMain -x vw-pun-rem-qa63 -i "C:\
Program Files\BMC Software\ARSystem" -m
This change allows Approval Server to start through a separate plug-in server
instance and avoid any conflict with the default plug-in server instance.
c. Save and close the armonitor.conf file.
4. Open the pluginsvr_config.xml file in the ARSystemInstallDir/pluginsvr directory and
modify as follows:
a. Remove the following entries for the ARSYS.ARDBC.PREVIEW plug-in:

<plugin>
<name>ARSYS.ARDBC.PREVIEW</name>
approval/bin/arasj80_build001.jar</pathelement>
<classname>com.bmc.arsys.approval.main.ApprovalPlugin</classname>
arserver/api/lib/arcmnapp80_build001.jar</pathelement>
arserver/api/lib/arutil80_build001.jar</pathelement>
</plugin>
Page 793 of 4705
Home
<maskingImplementation>com.bmc.arsys.approval.signal.SignalMaskForASJ
</maskingImplementation>
b. Save and close the file.

5. Restart the BMC remedy AR System server for the changes to take effect.

The Approval Server is an ARDBC plug-in that runs in the plug-in server. By default, armonitor
starts the plug-in server along with the BMC Remedy AR System server. Therefore, the Approval
Server is also loaded automatically when you start the BMC Remedy AR System server.
The armonitor executable uses the armonitor.cfg (Windows) or armonitor.conf (UNIX) file to
determine which services to start. Starting the plug-in server is controlled by the following line:
Windows
"$BMC_AR_SERVER_HOME$$/$arplugin.exe" $BMC_UNICODE_OPTION$ -i "$BMC_AR_SERVER_HOME$" -m
UNIX
$BMC_AR_SERVER_HOME$$/$bin$/$arplugin -s $BMC_AR_SERVER_NAME$ -i $BMC_AR_SERVER_HOME$
When the plug-in server starts, it checks the BMC Remedy AR System configuration file ( ar.cfg or
ar.conf ) for a list of plug-ins to load. The installation script adds one of the following entries for the
Approval Server plug-in to the BMC Remedy AR System configuration file:
Plugin: arasj$VERSION$.jar (Windows)
Plugin: arapprove (UNIX)
To stop and start the Approval inside the default Java plug-in server
1. To stop the Approval Server:
a. Comment the Preview plugin entry in the ar.cfg file. For example:
#Server-Plugin-Alias: ARSYS.ARDBC.PREVIEW ARSYS.ARDBC.PREVIEW

vw-pun-rem-qa63.pune-labs.bmc.com:9999
b. Comment the Preview plugin entry in the <installationFolder>\ pluginsvr \

pluginsvr_config.xml file. For example:

</plugins>

</pluginsvr_config>
2. To start the Approval Server, remove the comment markers from the files discussed in steps
1a and 1b.
To stop and start the Approval Server if it is running a separate plug-in

1. To stop the Approval Server:
a. Comment the Preview plugin entry in the ar.cfg file. For example:
#Server-Plugin-Alias: ARSYS.ARDBC.PREVIEW ARSYS.ARDBC.PREVIEW

vw-pun-rem-qa63.pune-labs.bmc.com:9999
b. Comment the Approval Server Entry in the armonitor.cfg file. For example:
#"C:\Program Files\Java\jre6\bin\java" -Xmx256m

-classpath "D:\Program
Files\BMC Software\ARSystem\approval\bin;D:\Program Files\BMC Software\
ARSystem\pluginsvr\arpluginsvr80_build002.jar;D:\Program Files\BMC Software
\ARSystem\approval\bin\arasj80_build002.jar;D:\Program Files\BMC Software\
ARSystem\arserver\api\lib\arcmnapp80_build002.jar;D:\Program Files\BMC
Software\ARSystem\approval\bin\armaskingImpl80_build002.jar;D:\Program
Files\BMC Software\ARSystem\arserver\api\lib\log4j-1.2.14.jar"
com.bmc.arsys.pluginsvr.ARPluginServerMain -x "IBMC-8PQF8BS" -i "D:\Program
Files\BMC Software\ARSystem" -m
2. To start the Approval Server, remove the comment markers from the files discussed in steps
1a and 1b.
Configuring BMC Remedy Email Engine

This section explains how to create and configure BMC Remedy Email Engine mailboxes and how
to set security options. The following topics are covered:
Configuring outgoing mailboxes
Page 795 of 4705
Home
Performance and configuration settings for Email Engine

BMC Remedy Email Engine mailboxes
Saving outgoing notifications in MAPI
Changing the default time interval
Testing your mailbox configuration
Configuring incoming mailboxes
Identifying the Email Engine component
Modifying the companionservername or RMIPort properties

You must create at least one outgoing mailbox to process outgoing mail, as described in this
section. The following figure illustrates how to set a mailbox as the default outgoing mailbox.
Setting the default outgoing mailbox
The Email Engine creates and sends messages based on the configuration options that you specify
in the AR System Email Mailbox Configuration form. Outgoing messages can include results from
actions specified in incoming messages, such as query or workflow results.
You can also link outgoing mailboxes to incoming mailboxes, to send the results of any actions
from a specific incoming mailbox to a specific outgoing mailbox.
Note
To use notifications with email, you must designate one mailbox as your default
notification mailbox. For more information, see Sending notifications.
The following topics provide detailed information about how to configure the basic and advanced
properties of outgoing mailboxes:
Configuring basic outgoing mailbox properties
Configuring advanced outgoing mailbox properties
Page 796 of 4705
Home
Configuring basic outgoing mailbox properties

Outgoing mailboxes support the MAPI and SMTP mail protocols.
To create a basic configuration for your outgoing mailbox

1. Open the AR System Email Mailbox Configuration form.
2. Enter the following information in the fields above the tabs:
Mailbox Name Enter a name that describes the function of the mailbox. For
example, enter ARSystemEmail - Outgoing.
Mailbox Function Select Outgoing.
Status Select Enabled.
3. In the Basic Configuration tab, select either SMTP or MAPI as the Email Server Type,
and set the following values in the remaining fields:
MAPI (for 32-bit JVM only):

Server Type Select MAPI.
Polling Interval Select a polling interval for the Email Engine to check for
new outgoing email from the BMC Remedy AR System server.
Profile Name Enter the name of the Microsoft Exchange profile that you
created during the product installation.
This field is required because a profile is used to see the MAPI email account
configuration information. For more information about Microsoft Exchange
profiles, see your Microsoft Exchange documentation.
SMTP
only:
Server Type Select SMTP.
new outgoing email from the BMC Remedy AR System server.
Email Server Requires SSL Select Yes to enable Secure Sockets Layer (
SSL). For more information, see Configuring SSL for the Email Engine .
Email Server Name/IP Enter the name or IP address of your company's
mail server.
Email Server Port Enter the mail server port number, or click Set Default
Email Server Port to accept the default port.
Email Server User If your mail server requires authentication information
before sending email, enter the email account user name.
Email Server Password Enter the password corresponding to the server
user.
4. Click Save.
Page 797 of 4705
Home
Configuring advanced outgoing mailbox properties

This section describes how to specify default settings for an outgoing mailbox, including default
addressing and templates. You can do this by using the Advanced Configuration tab of the AR
System Email Mailbox Configuration form as shown in the following figure:
Advanced configuration for outgoing mailboxes
You can specify only one default template of each type for a mailbox. The AR System Email
Templates form must already contain the templates.
Note
Review the information about advanced configuration settings in Creating and using email
templates.
To create an advanced configuration for your outgoing mailbox

1. In the Advanced Configuration tab of the AR System Email Mailbox Configuration form,
enter the following information in the fields above the tabs:
Associated Mailbox Name Enter the name the existing mailbox that will receive
instructions from this outgoing mailbox.
Default Outgoing Mailbox Select Yes to make this outgoing mailbox route all
emails that do not have a specified outgoing mailbox associated with them.
Display Name Enter a descriptive name that appears in the From: line of outgoing
emails.
This option is not used with MAPI.
Email Address Enter the email address of the server user that you created during
the product installation.
For example, if you entered a display name of ARSystem and an email address of
Page 798 of 4705
Home
arsystem@bmc.com, the From: line would be:

From: ARSystem [arsystem@bmc.com]
Reply To Address Specify an email address where replies to your outgoing emails
will be sent, or accept the default server user email address already in this field.
Organization If your email client displays your organization's name, enter the
name of the organization or company.
Delete Outgoing Notification Messages To have workflow-generated notification
messages deleted from the AR System Email Messages form after they have been
sent from this mailbox, select Yes.
To save workflow-generated messages in the AR System Email Messages form, or if
you are going to use email templates to modify records, select No.
System administrators or other users with the appropriate permissions must delete
manual messages.
2. Specify Default Addressing for notifications and escalations:
Default To Enter all email addresses that should receive outgoing messages from
this mailbox if no other email address is specified in the message.
Default CC Enter all email addresses that should receive copies of outgoing
messages from this mailbox if no other email address is specified in the message.
Default BCC Enter all email addresses that should receive blind copies of outgoing
messages from this mailbox if no other email address is specified in the message.
3. Specify Default Templates for notifications and escalations:
Header Template Enter the name of the template to use for the message header if
no other header template is specified.
Footer Template Enter name of the template to use for the message footer if no
other footer template is specified.
Status Template Enter name of the template to use for the status if no other
status template is specified.
Result Template Enter the name of the template to use for the result if no other
result template is specified.
4. Click Save.
For more information about notifications and escalations, see Defining a workflow to send email
notifications.
Performance and configuration settings for Email Engine

The email engine internally uses most configuration settings with their default values. The
centralized configuration forms and the EmailDaemon.properties file let you specify values other
than the defaults for these settings.
For specific troubleshooting issues, see Troubleshooting Email Engine.
Page 799 of 4705
Home
For information about the email engine properties in the centralized configuration forms, see
Configuration settings C-D.
Note
When you modify entries in the AR System Configuration Generic UI form, the changes
are effective in 30 seconds (the default value for the
com.bmc.arsys.emaildaemon.configurationcheckinterval setting). You can modify the
value for this setting from the EmailDaemon.properties file.
The following topics provide information about the various settings for Email Engine:
EmailDaemon.properties file
Settings in the EmailDaemon.properties file
Related topics
Configuration settings
Updating configuration settings
EmailDaemon.properties file
Tip
The term email daemon is frequently used when discussing the internal components of
the Email Engine. For example, "email daemon" is used to describe background
processes launched at start-time, email "handlers," the use of various threads to carry out
different tasks like sending and mails, parsing instructions, and so on. In UNIX, these
background processes are usually called "daemons," whereas for Windows they are
called "services." Following the UNIX convention, the file you use to set parameters for
the Email Engine is called EmailDaemon.properties. For the most part, the Email Engine
as synonymous with the email daemon.
When the Email Engine is installed, the EmailDaemon.properties file is created in the Email
Engine installation directory and is populated with the name of your organization's email server,
user name, and password. The main purpose of the EmailDaemon.properties file is to identify the
AR System server your Email Engine communicates with.
Sample contents of EmailDaemon.properties file
Page 800 of 4705
Home
To use the EmailDaemon.properties file, see Settings in the EmailDaemon.properties file.
Updating the EmailDaemon.properties file

If your email environment changes for example, if you need to change a server name or a TCP
port the EmailDaemon.properties file must be updated. The following procedure explains how
to update the file.
To update the value of one property at a time, open a command prompt, navigate to the
Email Engine installation directory, and execute the following command:
For Windows:
"JREInstallDir\java" -cp jarFileNamesSeparatedBySemicolons;
com.bmc.arsys.emaildaemon.EmailDaemon parameter
For UNIX:
JREInstallDir/java -cp jarFileNamesSeparatedByColons:
com.bmc.arsys.emaildaemon.EmailDaemon parameter
JREInstallDir is the path of your JRE installation.
jarFileNamesSeparatedBySemicolons or jarFileNamesSeparatedByColons are
the jar files listed in the command line of the command line from EmailStart.bat or
emaild.sh file.
Note
To use this command, you must properly set the library path for all UNIX platforms.
To update the values of multiple properties simultaneously, add them to EmailStart.bat (
Windows) or emaild.sh (UNIX) and running the executable.
Page 801 of 4705
Home
Email Engine startup parameters

Parameter
Description
-s
Server where the email forms (and the configuration information) are located.
-u
User name
-p
AR System Application Service password. The Email Engine requires the same password that is supplied on the
Connection Settings tab of the AR System Administration: Server Information form. To avoid authentication failures,
the application password must not exceed 20 characters.
-t
TCP port for the server to which the Email Engine should connect.
-r
RPC number of the server to which the Email Engine should be connected. Use this parameter to connect to a
private server. This can enhance performance if you expect a high volume of mail.
-l
Language to be used. (The default is C.)
-a
Authentication
-d
Directory where the EmailDaemon.properties file is located. If this parameter is not supplied, the system assumes
that this file is stored in the same directory as the emaildaemon.jar file.
-i
Time interval (in minutes) to use when checking the server for configuration updates (modifications to records in the
Email Mailbox Configuration form). The default is 30 minutes.
-e
Encrypts the given string and returns the value to the command line.
-f
The temporary directory to be used for internal Email Engine files.
-m
Monitor module interval (in minutes) to wait before trying to start the Email Engine again. The default is 30 minutes.
When the AR System server is not available, it tries to restart the system for every 30 minutes by default.
-o
(For 32-bit JVM only) MAPI sent folder where sent mail should be stored.
-v
Displays the client version; does not take any parameter.
Note
Changing property values does not affect the current instance of the email engine. To use
the updated property values, you must restart the email engine service manually. When
using EmailStart.bat or emaild.sh to restart the service, make sure to remove all the
parameters you used to update the property values.
Settings in the EmailDaemon.properties file

The email engine internally uses most configuration settings with their default values. The
EmailDaemon.properties file lets you specify values other than the defaults for these settings.
The following table lists the properties and their permissible values that you can specify in
EmailDaemon.properties to adjust the performance of the email engine. After adding or altering
these settings, you must stop and restart the email engine for the changes to take effect.
Page 802 of 4705
Home
For specific troubleshooting issues, see Troubleshooting BMC Remedy Email Engine and its
subtopics.
Performance and configuration settings for the BMC Remedy Email Engine
Settings
Definitions
Values
com.bmc.arsys.emaildaemon.AdditionalMailHeaders
Specifies additional email headers. Separate

the additional email headers with commas. See
Default value:
X-Loop-Detect
Adding extra custom headers to outgoing

SMTP emails.
com.bmc.arsys.emaildaemon.ARDATE
Specifies the date and time format that the

BMC Remedy Email Engine uses for parsing
date and time strings given in the incoming
mails. MMMMM dd, yyyy HH:mm:ss z is
equivalent to December 21, 2009 12:08:56
PDT.
com.bmc.arsys.emaildaemon.ARDATEONLY
Specifies the date format that BMC Remedy

Email Engine uses for parsing date strings
given in incoming mails. MMMMM dd, yyyy is
equivalent to December 21, 2009.
com.bmc.arsys.emaildaemon.ARTIMEONLY
This setting lets you specify the time format

used by BMC Remedy Email Engine for parsing
time strings given in incoming mails. HH:mm:
ss z is equivalent to 12:08:56 PDT.
com.bmc.arsys.emaildaemon.ContentTypeWithCharset
This setting indicates whether to send the

charset property in the Content-Type header
of an outgoing message. If you do not want the
charset string to be present in the
Content-Type header, set this property to
False.
com.bmc.arsys.emaildaemon.ChunkSize
Specifies the number of entries to return when
Default value:
the BMC Remedy Email Engine makes a call to

the AR System server.
100
Note: The
maximum
value is also
100.
com.bmc.arsys.emaildaemon.CommaValidAddressSeparator
Specifies whether you can use a comma as a

separator when entering multiple addresses in
the To and CC fields. If user names in the mail
server contain commas, set this property to
false (usually needed only when using the
MAPI protocol). For example, if names are
stored on the mail server as:
Smith, John and
Cho, Rick
You would need to use semicolons to separate
the addresses:
Smith, John; Cho, Rick
Page 803 of 4705
Home
Settings
Definitions
Values
com.bmc.arsys.emaildaemon.Exchange-Wait-Time
Specifies the amount of time in milliseconds for

which the BMC Remedy Email Engine waits
before processing the next incoming message,
when there are more messages residing on the
Exchange Server.
Default value:
1
com.bmc.arsys.emaildaemon.FetchUserGroupInfoOnDemand
Specifies whether to fetch the user and group

information about demand as opposed to
loading all users and groups at startup. If there
are many users or groups, you might want to
set this property to true to reduce the startup
time for email.
com.bmc.arsys.emaildaemon.getReplyToWithFromAddress
Determines whether the outgoing message

header should contain the Reply To field and
what its value should be.
getReplyToWithFromAddress is not used by
default. If you want the email engine to use this
property, you must add it to
EmailDaemon.properties and set its value to
true. If you add the property but do not specify
a value, it is considered as false. The effect of
using this property is as follows:
If no values are provided in the Reply To
Address field of the outgoing mailbox
configuration form and the Reply To field
of the messages form, andthe value of
this property is:
false (or not provided) The
Reply To field is not included in
the outgoing message header.
true The Reply To field is
included in the outgoing message
header, and its value is the
address in the From field of the
messages form.
If the Reply To Address field of the
outgoing mailbox configuration form or
the Reply To field of the messages form
contains a value, the message header
will contain the Reply To header value as
set in the message, regardless of value
of this property.
com.bmc.arsys.emaildaemon.IncomingConnectionRecycleSize
Specifies the default number of email

messages the email engine receives before the
connection is closed and reopened. In the 5.1
and 5.1.1 releases of the email engine, the
connection with the mail server was closed only
after reading all incoming messages.
Consequently, if the email engine crashed or
Default value:
100
Page 804 of 4705
Home
Settings
Definitions
Values
hung before the connection was closed, it was

possible that messages marked for deletion
would not be deleted from the mail server. This
property helps you avoid that situation.
com.bmc.arsys.emaildaemon.IncomingMessagesQueueSize
Specifies the message queue size (number of

emails). The Receiver module writes messages
Default value:
100
to the queue, and the Execution module reads

messages from this queue to parse and
execute. The Receiver module still writes
messages to the server in AR System Email
Messages form, but the Execution module
reads the message from the message queue
instead of from the server. This reduces the
traffic to the AR System server and improves
the performance.
com.bmc.arsys.emaildaemon.instructionCacheSize
Specifies the number of instructions to be
Default value:
stored in the cache, which is used to improve

performance. If the value of this property is set
20
to 15, the cache already contains 15

instructions, and another instruction is to be
added, then the oldest instruction is removed to
accommodate the newest one.
Note: If any changes are made to the BMC
Remedy AR System Email Instructions form,
the instruction cache is flushed based on the
setting of the serverName.Interval property.
com.bmc.arsys.emaildaemon.Mailboxes
If you run multiple instances of the email engine

on a single server, this property specifies which
mailboxes should the email engine process.
The value of this property should contain
comma-separated mailbox names; the email
engine only processes these mailboxes. If you
do not specify a value, the email engine
processes all of the mailboxes configured for
the server.
com.bmc.arsys.emaildaemon.MailboxPollingUnitIsMinutes
Specifies whether the polling interval is to be

considered in minutes (as configured in AR
System Email Configuration) or seconds. The
email engine interprets the value of this
property as follows:
true Consider the polling interval in
minutes.
false Consider the polling interval in
seconds.
Note: Whatever measure of unit you select
applies to all configured mailboxes that are
enabled.
Page 805 of 4705
Home
Settings
Definitions
com.bmc.arsys.emaildaemon.MaxAttachSize and
Specifies the attachment types that you want to

permit in an email message and the maximum
com.bmc.arsys.emaildaemon.MaxAttachSizeFileExtensions
Values
size of each attachment.MaxAttachSize

specifies the maximum size limit for
attachments, whereas
MaxAttachSizeFileExtensions specifies the
file types by using comma-separated
extensions. These properties must be used
together to impose limits on email attachments
of specific file types. For example, to set the
maximum size of .doc, .pdf, and .xls
attachments to 1000000 bytes (1 MB), use the
following syntax:
com.bmc.arsys.emaildaemon.MaxAttachSize
=1000000 com.bmc.arsys.emaildaemon.
MaxAttachSizeFileExtensions=doc,pdf,xls
The size limit is not imposed on files whose
extensions are not specified by using
MaxAttachSizeFileExtensions. Email
messages with attachments that exceed this
limit are logged to the AR System Email Error
Logs form. Optionally, you can create workflow
for this form to process such messages
separately.
com.bmc.arsys.emaildaemon.MBOXFromLineWith-At-The-Rate-Sign
The email engine interprets the value of this

property as follows:
true BMC Remedy Email Engine
fetches only those messages that
contain the @ sign in the "from line" (
from address).
false BMC Remedy Email Engine
fetches all the messages.
com.bmc.arsys.emaildaemon.Monitor
Specifies the interval in minutes between
Default value:
checks to see if all the threads are functioning

properly.
30 minutes
Note: If the monitoring system detects that a

thread has failed, it restarts the thread.
com.bmc.arsys.emaildaemon.NumberOfSenderThreads
Specifies the number of sender threads that the

email daemon uses for each outgoing mailbox.
The optimum number of threads depends on
many factors including the number of mailboxes
, the hardware configuration, and so on.
Permissible
range of
values: 1
through 20
Default value:
4
com.bmc.arsys.emaildaemon.OutgoingMessagesQueueSize
Specifies the size of the queue that the email

daemon maintains for outgoing messages. The
optimum number of message queue size to be
specified depends on the load on the email
daemon.
Default value:
100
Page 806 of 4705
Home
Settings
Definitions
Values
Note: This value is used to determine when to

query the database. If you set a very high value
, the database is queried too often, which might
reduce the performance.
com.bmc.arsys.emaildaemon.RMIPORT = 1100
Specifies the port number for remote method

invocation (RMI). This feature is used with the
Default value:
1100
EmailAdminAgent.jar file to stop, suspend,

resume, or change logging level of the email
engine at runtime.
com.bmc.arsys.emaildaemon.SaveSentItem
Specifies whether to retain messages in the

Email Messages form after sending. To delete
sent messages from the Email Messages form,
set this property to False.
com.bmc.arsys.emaildaemon.securityCacheSize
Specifies the number of security keys to be
Default value:
stored in the cache. If the value of this property

is set to 15, the cache already contains 15
20
security keys, and another key is to be added,

then the oldest key is removed to accommodate
the newest one.
Remedy AR System Email Security form, the
security cache is flushed based on the setting
of the serverName.Interval property.
com.bmc.arsys.emaildaemon.SendEmailSetSize
Specifies the number of outgoing emails to
Default value:
query at a time.
100
com.bmc.arsys.emaildaemon.serverName.Authentication
Specifies a string if your AR System server

requires authentication information before
handling requests.
com.bmc.arsys.emaildaemon.serverName.Interval
Specifies the interval in minutes after which to
Default value:
check with the server for the following:
30
Configuration updates (for example, if

you modified records in the BMC
Remedy AR System Email Mailbox
Configuration form)
Updates to the templates (for example, if
you modified templates in the BMC
Remedy AR System Email Templates
form)
Any changes done to the forms on the
server (for example, if you added or
deleted any field on any form)
com.bmc.arsys.emaildaemon.serverName.Language
Specifies the language that the email engine

must use.
Default value:
en_US
com.bmc.arsys.emaildaemon.serverName.RPC
Page 807 of 4705
Home
Settings
Definitions
Values
Specifies the RPC port number that the AR

System server uses if you have configured a
private server to be used with the email engine.
com.bmc.arsys.emaildaemon.serverName.TCP
Specifies the TCP port number that the AR

System server uses if it is not using the BMC
Remedy AR System portmapper.
com.bmc.arsys.emaildaemon.Servers
Specifies the name of the AR System server

that the email engine interacts with.
com.bmc.arsys.emaildaemon.SMTPTimeout
Specifies whether to wait before cancelling an

attempt to connect to the mail server and
generating an error. In case of an SMTP
timeout, the email engine waits for the timeout
interval and then marks the queued message
as erroneous.SMTPTimeout is not used by
default. If you want the email engine to use this
property, you must add it to
EmailDaemon.properties and set its value to
true. If you add the property but do not specify
a value, it is considered as false.
See Recommendation for using the SMTP
timeout properties.
com.bmc.arsys.emaildaemon.SMTPTimeoutPeriod
Specifies the duration in number of seconds to

wait before cancelling an attempt to connect to
the mail server and generating an error. In case
of an SMTP timeout, the email engine waits for
this interval and then marks the queued
message as an erroneous.
SMTPTimeoutPeriod is not used by default. If
you want the email engine to use this property,
you must add it to EmailDaemon.properties
and set its value to any positive integer (upper
limit depends on the platform). If you add the
property but do not specify a value, it is
considered as half the polling interval that is set
for outgoing mailboxes.
Note:SMTPTimeoutPeriod is dependent on
SMTPTimeout ; it works only when
SMTPTimeout is set to true. See
Recommendation for using the SMTP timeout
properties.
com.bmc.arsys.emaildaemon.SortMessages
Specifies whether to process messages with a

higher priority setting first.
com.bmc.arsys.emaildaemon.StoreInstructions
Specifies whether to store instructions and

instruction parameters in the AR System server.
If set to true, the email engine retains data in
Page 808 of 4705
Home
Settings
Definitions
Values
the Email Instructions and Instruction

Parameters forms for troubleshooting. Then,
you must delete this data explicitly. The
Execution module in the BMC Remedy Email
Engine handles both the parsing and execution
of messages. There will be one message queue
created for each Incoming mailbox. By default,
instructions are not stored in the server.
com.bmc.arsys.emaildaemon.SynchronizedLoggingMode
This property is not available by default. You

can add it if required. If this property is not
present in EmailDaemon.properties, or if it is
present but set to false, the bulk API logging
mode is used. If this property is present in
EmailDaemon.properties and its value set to
true, then the synchronized logging mode is
used.
Note: The email engine's performance might
degrade when synchronized logging is enabled,
because all the email engine threads are
suspended while processing the synchronized
logs. Synchronized logging continues to occur
periodically, and control is restored to the
threads only after the logging is over.
com.bmc.arsys.emaildaemon.templateCacheSize
Specifies the number of email templates to be
Default value:
stored in the cache to improve the performance.

If the value of this property is set to 15, the
20
cache already contains 15 templates, and

another template is to be added, then the oldest
template is removed to accommodate the
newest one.
Remedy AR System Email Templates form, the
templates cache is flushed based on the setting
of the serverName.Interval property.
com.bmc.arsys.emaildaemon.URLWithHrefTag
Specifies whether an <a href> tag is placed

around a URL in an HTML message. If the
setting is true, the <a href> tag is used. If the
setting is false, the URL is not enclosed in an <
a href> tag.
com.bmc.arsys.emaildaemon.UseNameIfNoEmailAddress
Specifies whether to retain display names that

do not have email addresses associated with
them in the To, CC, or BCC fields. If the setting
is true, the display names are not removed
from the To, CC, or BCC fields. If the setting is
false, the display names are removed from the
To, CC, or BCC fields.
Page 809 of 4705
Home
Settings
Definitions
Values
Note: The email engine checks for email

addresses associated with display names only
on the User form and not on the Exchange
server.
com.bmc.arsys.emaildaemon.UserChunkSize
Specifies the number of users (records from the

User form) to retrieve from the AR System
server at one time. This setting can be used to
tune the email engine's performance.
Default value:
5000
com.bmc.arsys.emaildaemon.AdminAddresses
Specifies the email address of the administrator

. If a database transaction fails while storing an
incoming message, the email engine forwards
the original mail to this email address, so that it
is retained. An example of a transaction failure
could be when the database is full and cannot
save anymore incoming email messages. You
can specify multiple addresses separated by
commas.
Default value
is set to the
administrator
address
specified
during
installation.
Note: This property can be used only when the

BMC Remedy Email Engine does not capture
the error out incoming email messages in the
BMC Remedy AR System Email Error
Messages Form.
BMC Remedy Email Engine mailboxes

A mailbox is an entry in the AR System Email Mailbox Configuration form that contains the
information required to access email from a mail server or to request that email be sent by a mail
server. You must configure at least one mailbox to communicate with your mail server to send or
receive email.
To send and receive email, you must create and configure outgoing and incoming mailboxes. You
can configure them during or after the product installation.
To set up advanced mailbox options (such as default values, parsing, and mailbox security), you
can update the configuration as discussed in this section.
Configuration information is stored in forms on the AR System database. For more information
about Email Engine forms, see Email Engine forms.
Outgoing mailbox configuration

The Email Engine creates and sends messages based on the configuration options that you specify
in the AR System Email Mailbox Configuration form. Outgoing messages can include results from
actions specified in incoming messages, such as query or workflow results.
Page 810 of 4705
Home
You can also link outgoing mailboxes to incoming mailboxes, to send the results of any actions
from a specific incoming mailbox to a specific outgoing mailbox.
Note
To use notifications with email, you must designate one mailbox as your default
notification mailbox. For more information, see Sending notifications.
Saving outgoing notifications in MAPI

If you use the MAPI email protocol and you want to save messages on the Exchange server, you
must configure your outgoing mailbox to save outgoing notification emails in an Outlook folder.
To save outgoing notifications, add the following line to the EmailDaemon.properties file:
ARSystemServer.MAPI_Sent_Folder=folderName
ARSystemServer is the name of the AR System server associated with the Email Engine.
folderName is the name of the folder that stores the outgoing notification emails. For
example, enter Sent Items to save messages to your Sent Items folder in Microsoft Outlook.
Changing the default time interval

When the email engine starts, it retrieves all the entries in the AR System Email Mailbox
Configuration form and creates incoming and outgoing mailboxes. Every 30 minutes, the email
engine automatically queries the form for changes to the form entries and updates the information.
To enable changes to form entries before the next default query time, stop and restart the email
engine.
Note
Changes to the Status field are not reflected automatically. If you have changed the value
of this field, you must restart the email engine for the change to take effect.
To shorten the default time interval in the EmailDaemon.properties file, set the polling parameter.
For example, shorten the time to 5 minutes: ServerName.Interval = 5.
For more information about this property or the EmailDaemon.properties file, see Settings in the
EmailDaemon.properties file.
Testing your mailbox configuration

You must test your mailbox configurations to make sure that your mailbox communicates with your
mail server correctly.
Page 811 of 4705
Home
Note
If your Email Engine requires a security key to authenticate incoming email, skip this
section and see Securing incoming and outgoing email.
Use the following procedures to verify that you can send email from your outgoing mailbox and
receive email in your incoming mailbox . If you complete the steps successfully, your outgoing and
incoming mailboxes are configured correctly. If you are unable to complete the steps, see
Troubleshooting BMC Remedy Email Engine .
Before you perform the test, obtain the correct email address for your email account or profile from
your email server administrator.
To test your outgoing mailbox

1. In the Basic Configuration tab of the outgoing mailbox you are testing, set the Polling
Interval to one minute, to view the test results promptly.
2. In a browser, open the AR System Email Messages form in New mode.
3. Create a message as follows, and click Send:
a. Mailbox Name Select the name of the outgoing mailbox to test.
b. Message Type Select Outgoing.
c. Message Tab Enter email addresses for the From: and Reply To: fields, a subject
line, and the body content.
Note
Select an email address that you can access with a third-party utility, such
as Microsoft Outlook.
4. Open the AR System Email Messages form in Search mode.

5. Perform a query for the email message that you sent.
6. In the results table, check for the following information:
An entry corresponding to the email message.
The value in the Send Message column is Yes. A Yes value indicates that the
outgoing mailbox has queued your email to be sent.
7. Open the AR System Email Mailbox Configuration form in Search mode.
8. After the time specified for the outgoing mailbox's polling interval, open the AR System Email
Messages form in Search mode.
9. Enter the name of the outgoing mailbox, and click Search.
10. In the results table, check for the following information:
An entry corresponding to the email message.
Page 812 of 4705
10.
Home
The value in the Send Message column is Sent.

The value in the Date Sent column is the precise time that the email message was
sent to the mail server.
11. Using a third-party email client, verify that the message was sent to the To address that you
specified in step 3c.
To test your incoming mailbox

1. In the Basic Configuration tab of the incoming mailbox you are testing, set the Polling
Interval to one minute, to view the test results promptly.
2. In a browser, open the AR System Email Mailbox Configuration form.
3. Search for the name of the incoming mailbox to test.
4. Make sure that the email account or profile that your incoming mailbox uses matches the
email account that you obtained from your email server administrator, and change the form
entry if necessary.
5. In a third-party email client, create an email containing a subject line and body content.
6. Send the email to the email address that you verified in step 4.
7. After the time specified for the incoming mailbox's polling interval, open the AR System
Email Messages form in Search mode.
8. Select a mailbox name and perform a search. The results table displays the entry
corresponding to the message you sent.
9. Double-click the entry to open the form containing the information for that entry.
10. Make sure that the subject line and content in the form are the same as the subject line and
content of the test email that you sent, which indicates a successful test.
Configuring incoming mailboxes

Based on the information that you enter in the AR System Email Mailbox Configuration form, the
Email Engine polls incoming mailboxes for new messages, processes the messages, parses the
contents if necessary, and performs the actions specified in the messages, such as modifying
requests or executing queries.
Incoming mailboxes support the MAPI, POP3, IMAP4, and MBOX mail protocols.
The following topics provide information about how to configure the basic and advanced properties
of incoming mailboxes:
Configuring basic incoming mailbox properties
Configuring advanced incoming mailbox properties
Configuring basic incoming mailbox properties

Basic configuration for your incoming mailbox consists of you entering the following information in
the Basic Configuration tab on the AR System Email Mailbox Configuration form:
Mailbox information, such as the mailbox name
Page 813 of 4705
Home
Server information, such as the mail protocol associated with the server and the server port
number
To create a basic configuration for your incoming mailbox

1. Open the AR System Email Mailbox Configuration form.
2. Enter the following information in the fields above the tabs:
Mailbox Name Enter a name that describes the function of the mailbox. For
example, enter ARSystemEmail - Incoming.
Mailbox Function Select Incoming.
Status Select Enabled.
3. In the Basic Configuration tab, select MAPI, POP3, IMAP4, or MBOX as the Email Server
Type, and set the following values in the remaining fields:
MAPI (for 32-bit JVM only):

Server Type Select MAPI.
new incoming email from the mail server.
Profile Name Enter the name of the Microsoft Exchange profile that you
created during the product installation.
This field is required because a profile is used to see the MAPI email account
configuration information. For more information about Microsoft Exchange
profiles, see your Microsoft Exchange documentation.
POP3 or IMAP4 only
:
Server Type Select either POP3 or IMAP4.
Email Server Requires SSL Select Yes to enable Secure Sockets Layer (
SSL). For more information, see Configuring SSL for the Email Engine .
Email Server Name/IP Enter the name or IP address of your company's
mail server.
Email Server Port Enter the mail server port number, or click Set Default
Email Server Port to accept the default port.
Email Server User If your mail server requires authentication information
before sending email, enter the email account user name.
Email Server Password Enter the password corresponding to the server
user.
MBOX only:
Server Type Select MBOX.
Page 814 of 4705
Home
Inbox Path Enter the complete path to the MBOX file that corresponds to
the user email account. For example, enter /usr/spool/mail/ARSystem, where
ARSystem is the file name.
4. Click Save.
Configuring advanced incoming mailbox properties

During advanced configuration, you enter information about associated mailboxes, templates, and
forms, and information related to mailbox security. You can do this by using the Advanced
Configuration tab of the AR System Email Mailbox Configuration form as shown in the following
figure.
Advanced configuration for incoming mailboxes
Note
Review the information about advanced configuration settings in Creating and using email
templates.
To create an advanced configuration for your incoming mailbox

1. In the Advanced Configuration tab of the AR System Email Mailbox Configuration form,
select an outgoing mailbox from the Associated Mailbox Name list to reply to incoming
emails that require responses, such as queries.
2. In the Action Configuration section, specify:
Email Action To enable the Email Engine to detect and process instructions
included in an incoming email message, select Parse. If you use templates to perform
Submit, Modify, or Query actions, you must select Parse.
For more information about templates and parsing, see Using label-value pairs in
templates and Types of email templates.
Use Original Template Format
Page 815 of 4705
Home
(enabled for upgrades from BMC Remedy Mail Server) To enable original parsing
system processing, select Yes.
Original parsing ignores special HTML fields, XML formats, and data entered in an
invalid format, such as a character string in a number field. If you use this option, the
Email Engine displays an error message when it encounters these types of fields or
formats. To use normal parsing, select No.
Note
If you select No, make sure that multiple lines in emails are encapsulated
with the [$$ and $$] multiple-line delimiters.
Reply with Result To enable the Email Engine to return the results of an action in
an email, select Yes.
This option allows the email sender to know if the incoming email succeeded or failed.
For more information, see Sharing a database without using a server group .
Reply with Entry To return the complete entry of a submit or modify action, select
Yes.
Enable Modify Actions To enable the Email Engine to modify existing entries,
select Yes.
Default Workflow Form Enter the name of the default form on which the Email
Engine executes instructions such as queries, form-entry modifications, and form
submittals, from the incoming email message.
Note
If you define a default workflow form, incoming templates do not require the
Form (or Schema) label. For more information, see Form label.
Force Default Workflow Form To confine all instructions from the incoming email
message to the form that you specified in the Default Workflow Form field, select
Yes.
Note
If an incoming template specifies a schema, the schema will not be
processed and the default workflow form will be used instead.
3.
Page 816 of 4705
Home
3. In the Incoming Security Configuration section, specify the level of security to be applied
to email messages to this mailbox. This information is used to determine which AR System
user information to apply when executing instructions parsed from an incoming email.
Depending on the level of security that you want, apply one of the following security options:
Use Security Key Select Yes to enable a security key for incoming email.
The information is added to the Email Security form, so you do not have to supply the
user name and password in the incoming email. If you use this option, you must
create and configure the security key. See Configuring incoming mailbox security.
If you select No, the security key will be disabled for incoming email containing the
modify action. In case of multiple recipients, the outgoing email message for this
modify action will not be sent.
Use Supplied User Information To use AR System server login information from
the incoming email message to execute instructions in the incoming message, such
as instructions to modify requests or submit queries, select Yes.
For more information about login syntax, see Login, Password, and TCP Port labels .
Use Email From Address To use the sender's email address as a form of
authentication, select Yes.
The Email Engine displays an error message if the sender's email address is different
from the email address stored in the AR System User form.
Note
Apply only one of the given security options.
4. Click Save.

This section describes tasks you can perform after you install BMC Remedy Email Engine.
To start and stop the Email Engine manually on Windows from the Services window
To start and stop the Email Engine manually on Windows from the command line
To start and stop the Email Engine manually on UNIX
To start and stop the Email Engine manually on Windows from the Services
window
If the Email Engine fails to start automatically after you start the server, use the instructions given
below to start it manually.
1. Go to Start > Settings > Control Panel > Administrative Tools > Services to open the
Services window.
2. Select the BMC Remedy Email Engine service.
3.
Page 817 of 4705
Home
3. Right-click the service and select Start or Stop. The email service will start or stop
immediately.
To start and stop the Email Engine manually on Windows from the command line
1. Enter the following command to change directories to the Email Engine installation directory:
cd <emailEngineInstallDirectory>
2. Enter the emailstart command to start the Email Engine:

3. To stop the Email Engine, press Ctrl+C.
Note
MAPI mailbox users only: If you did not configure your MAPI mailbox during
installation, change the Email Engine login information in the Services window to
your Windows user account.
To start and stop the Email Engine manually on UNIX

1. Enter the following command to change directories to the Email Engine installation directory:
cd <emailEngineInstallDirectory>
2. Enter either of the following commands to start the Email Engine:

emaild.sh start &
# nohup emaild.sh start &
3. Enter the following command to stop the Email Engine:
# emaild.sh stop &
After you enter this command, the AR Monitor stops the Email Engine service and
immediately restarts it automatically.
If the emaild.sh command fails to stop the Email Engine, comment out the following line in
the armonitor.conf file, then reissue the emaild.sh command:
/opt/bmc/ARSystem/AREmail/emaild.sh start
Page 818 of 4705
Home
Identifying the Email Engine component

BMC Remedy Email Engine uses the following properties to create a unique component name:
com.bmc.arsys.emaildaemon.companionservername
com.bmc.arsys.emaildaemon.RMIPORT
The naming format is:
companionServerName:RMIPort
where,
companionServerName specifies the companion server name for Email Engine
RMIPort specifies the port number for remote method invocation (RMI)
For example, myhostname.com:1100
Modifying the companionservername or RMIPort properties

To modify the value of companionservername or RMIPort, perform the following steps:
1. Stop BMC Remedy Email Engine.
See Stopping and starting the Email Engine .
2. Open the EmailDaemon.properties file.
3. Modify the values as needed.
4. Save your changes to the EmailDaemon.properties file and close the file.
5. Open the AR System Configuration Component form in search mode.
For more information about this form, see Centralized configuration system forms.
6. Search for the Email Engine component by using the following search criteria:
a. Type = com.bmc.arsys.emaildaemon
b. Name = companionservername
7. Modify the component name to reflect the changes made in the EmailDaemon.properties
file.
For example, for the myhostname.com companion server, if you changed the RMIPort (in
the EmailDaemon.properties file) from 1100 to 1200, then the new component name will be
myhostname.com:1200.
8. Restart BMC Remedy Email Engine.
Configuring BMC Remedy Flashboards

The following topics provide information about configuring BMC Remedy Flashboards:
Setting up flashboard update intervals
Starting or stopping the Flashboards server manually
Page 819 of 4705
Home
Setting up a headless environment with Tomcat to display flashboards

Configuring the display properties for a flashboard
Modifying the config.properties file for flashboards
Multiple Flashboards servers and AR System servers
Setting up flashboard update intervals

The mid tier displays flashboards in a web browser and generates Flashboards images from
information in the mid tier cache. You can change mid tier cache update times from Flashboards
Settings in the BMC Remedy Mid Tier Configuration Tool.
To change mid tier cache update times

1. Enter the following URL to open the BMC Remedy Mid Tier Configuration Tool:
http://<webServerThatSupportsFlashboards>/arsys/shared/config/config.jsp
Note
The default login password is arsystem.
2. Click Cache Settings to open the Cache Settings page.

Cache Settings page in BMC Remedy Mid Tier Configuration Tool
3. Make changes to the Update Flashboards Definition Interval settings.

The Flashboards definition is the graph and data representation. The definition interval is the
interval (in seconds) at which the server updates the Flashboards cache information. The
default value for both Windows and UNIX is 0, which means that caching is disabled.
4. Click Save Changes to save the new values.
To configure BMC Remedy AR System to view flashboards using the default URL
path
1. In a browser, from the server that contains the flashboard, open the BMC Remedy AR
System Administration Console, and click System > General > Server Information.
The BMC Remedy AR System Administration: Server Information form appears.
3.
Page 820 of 4705
Home
3. In the Default Web Path field, change the default URL path to:
http://<hostName>:port/arsys
where hostName is the location where you installed the BMC Remedy Mid Tier and port is
the port number. The port number is optional.
For example, if your host name is abc, and your port number is 230 ( optional), your default
URL path would be: http://abc:230/arsys
Note
Refresh your flashboard to view the most recent historical, summary, and real-time
data.
Starting or stopping the Flashboards server manually

Use the Flashboards server to collect historical data.
To start or stop the Flashboards server on Windows

1. Access the Services screen.
a. Choose Start > Settings > Control Panel.
b. Double-click Administrative Tools.
c. Double-click the Services icon.
2. Select the Flashboards server.
3. Select Action > Start or Action > Stop, as required.
To start or stop the Flashboards server on UNIX or Linux

1. Change directories to the installation directory of that server.
2. Enter the following commands to start or stop the Flashboards server:
server.sh start
or
server.sh stop
If you are running two Flashboards servers on the same computer and you enter the
server.sh stop command, both servers will stop. To stop only one Flashboards server,
include the port number in the command as given below:
server.sh stop -p
<portNumber>
Page 821 of 4705
Home
Setting up a headless environment with Tomcat to display

flashboards
If you use a terminal to reach a headless UNIX system where you have installed the web server
and mid tier, you might receive error messages when accessing flashboards through a browser.
To make sure that flashboards work from a headless UNIX environment, you must set Java VM
options on the servlet engine that controls BMC Remedy Mid Tier.
To set Java VM options on the servlet engine

1. In the catalina.sh file, add the following options for JAVA_OPTS near the top of the file:
-Djava.awt.headless=true
-Dsun.java2d.fontpath= sdkInstallDirectory/jre/lib/fonts
Example
JAVA_OPTS="-Djava.awt.headless=true -Dsun.java2d.fontpath=/usr/
jdk1.5.0_10/jre/lib/fonts"
2. Restart Tomcat for this change to take effect.

Use a similar procedure to add VM options to other servlet engines. See your respective server
vendor's documentation for information about configuring Java options.
Configuring the display properties for a flashboard

To ensure a similar look and feel across BMC products, the default format of BMC Remedy
Flashboards has the same color scheme and look as the BMC Dashboards product.
BMC Remedy Flashboards uses Adobe Flash technology. In leveraging the Adobe Flash
technology, the new BMC Remedy Flashboards product provides:
A more exciting UI.
Off-loading of the chart rendering to the client side (browser side)--thus freeing the mid tier to
do more processing.
More client-side interactions such as step zoom in and zoom out; dynamic chart, legend, and
color change; and full-screen view.
Note
Page 822 of 4705
Home
Because of the new client-side interactions, certain workflows (such as chart, color, and
legend changes) no longer require the mid tier to process them as is required for the older
image-based flashboard. Therefore, if you change a flashboard's definition on the BMC
Remedy AR System server (for example, to use the Adobe Flash technology), and the
user interaction with the BMC Remedy Flashboards does not require the mid tier to
perform any processing, the user will not see the new flashboard definition changes
immediately. When the user performs an action that requires mid-tier processing (such as
a browser refresh), the new Flashboard definition is applied, and the user will see the
changes.
The following topics provide more information about configuring flashboard properties:
Modifying flashboard properties
Additional flashboard properties
Enable the Embedded property
Modifying flashboard properties

The available formats for flashboards are:
Default format The out-of-the-box format that uses Adobe Flash technology that enable
users to interact with the flashboard by performing actions such as zooming, viewing in full
screen mode, changing the chart type, changing labels.
New look and feel with 7.1.00 and 7.0.01 color scheme Displays the flashboard with
interactive features, but uses the previous version's color scheme. (To use this format, set
the flashdisplay parameter to 0 as described in Parameters for display in prior version.)
Color and format for 7.1.00 and 7.0.01 ("image-based") Uses the previous version's
color scheme and look and feel. (To use this format, set the flashdisplay and
defaultlookandfeel parameters to 0 as described in Parameters for display in prior version.)
The "Formats for flashboards" figure shows the different formats.
Note
By default, Adobe Flash technology is used to display the flashboards. However, if
flashboards are too small, Flash technology cannot render the flashboard legibly. In such
cases, the image-based version of the flashboard is used. You can manually set the
minimum width and height size that is used when a flashboard reverts to the image-based
format. See Modifying the config.properties file for flashboards
Formats for flashboards

Page 823 of 4705
Home
The following table lists the available properties under the Properties tab and the flashboard format
supported for each property.
Flashboard properties
Parameter
Powered by Adobe Flash
Image-based
Default format and color scheme
7.1.00/7.0.01 color scheme
7.1.00/7.0.01 color and format
Show X Axis as Time
Show X Axis Ticks
Axis
Show X Axis
Show Y Axis
Show Y Axis Ticks
Wall 3D Color
X 3D Offset
X Axis Grid Color
X Axis Label Color
X Axis Label Font
X Axis Show Ticks Label
X Axis Ticks Label Font
X Axis Ticks Color
X Axis Ticks Label Color
+
+
Y 3D Offset
Y Axis Grid Color
Y Axis Label Color
Y Axis Label Font
Y Axis Show Ticks Label
Page 824 of 4705
Home
Parameter
Image-based
Y Axis Ticks Color
Y Axis Ticks Label Color
Y Axis Ticks Label Font
Chart Border Width
Chart Outline Width
Chart
Advanced Color Palette
Custom Time Format
Customizable Parameters
Display 3D
+
+
Foreground Color
Foreground Transparency
Graph Background Color
Graph Background Transparency
Legend Border Width
Max Bar Width
Outline Color
Display Table
Outline Legend Keys
Show Chart Title

Show Values
Time Format
+
+
Title Alignment
Title Color
Title Font
+
+
Title Placement
Top Group By Number
Top Group By Other Alias
Top Group By Other Color
Value Label Color
Value Label Font
Legend
+
Page 825 of 4705
Home
Parameter
Image-based
Background Color
Item Color
Item Font
Outline Color
Outline Width
Title Alignment
Title Color
Title Font
Meter
Alert Color
Needle Color
Normal Color
Type
Warning Color
Formats for the properties in the Properties tab are as follows:

Font properties <type-size-font name>
For example:
0-10-SanSerif
The options for type are 0 for plain, 1 for bold, and 2 for italic.
Color properties <heximdecimalColorCode>
For example, 0000FF renders a blue color.
Gradients use the following format: <
colorOrdercolorPlacementcolorCode1colorCode2>
colorOrder determines the gradient's pattern. The options are:

L For linear colors
R For reflected colors
colorPlacement determines the gradient's pattern. The options are:
H For a horizontal pattern
V For a vertical pattern
For example, the following property would render a horizontal gradient with the colors
black and white.
LH000000FFFFFF
Note
Page 826 of 4705
Home
If you have flashboards created before version 7.0.01, you can use the old
color palette to keep your old color. To keep the old palette, change the
Advanced Color Palette value to 0.
On/off properties 0 indicates that the property is turned off, and 1 indicates that the
property is turned on. For example, if the Show X Axis property is set to 1, the X axis will
appear in the flashboard.
Offset properties The number of pixels that the image is offset.
Additional flashboard properties

In the BMC Remedy Developer Studio Properties window, the following additional attributes have
been added under Axis section for flashboards.
Updated flashboard properties
Property
Description
Show X
Axis
line
Option to display the X axis line. If the value is set to 0, the axis line is invisible. If the value is set to 1, the axis line is
Show Y
Axis
line
Option to display the Y axis line If the value is set to 0, the axis line is invisible. If the value is set to 1, the axis line is
Show
Label
Option to display labels above each horizontal bar of the capacity flashboard. If the value is set to 0, the vertical axis
Inside
visible. By default, the value is set to 0.
visible. By default, the value is set to 0.
labels are displayed outside chart at the default position. If the value is set to 1, the vertical axis labels are displayed
inside the chart above each bar.
Note
This property is applicable for horizontal capacity flashboard only and it is ignored for other flashboards.
Note
The properties mentioned in the table are available for any flashboard type.
Enable the Embedded property

You can enable the Embedded property for the flashboard to embed the flashboard on the window.
Embedded flashboards do not display distinct boundaries and the background color. These support
transparency on the form and do not display borders. You can see the text description within the
flashboard. Embedded flashboards do not contain the following controls.
Show Legend
Page 827 of 4705
Home
Full Screen
Options
Embedded Flashboard
However, you can right-click on the embedded flashboard to open a context menu and view these
options.
Note
Embedded flashboards do not support zoom functionality. When you view the embedded
flashboard using BMC Remedy Mid Tier 7.6 or earlier, it appears like a regular flashboard
with borders and controls.
To enable the Embedded property for flashboard, in BMC Remedy Developer Studio Properties
window, under the Chart section, set the flashboard property Embedded to 1. By default, the value
is set to 0.
Modifying the config.properties file for flashboards

This section provides the details on modifying the config.properties file for flashboards. You can
manually change the default behavior of flashboards by changing the settings in the
Locating the config.properties file

The config.properties file is installed in the following directory: <midTierInstallationDir>\
WEB-INF\classes\config.properties
The default value of midTierInstallationDir is C:\Program Files\BMC Software\ARSystem\midtier .
Changing the default format of flashboards

You can change the default format of flashboards by changing the settings listed in the following
tables. For information about image-based and Adobe Flash formats, see Modifying flashboard
properties.
Page 828 of 4705
Home
Settings used to change the flashboards format

Setting
Description
flashboards.showgraphinflash
Defines which default format to use when displaying flashboards. The options are:
=[0 or 1]
0 Use image-based format.
1 Use Adobe Flash format.
flashboards.min_flex_width=
260
The minimum flashboard width below which a flashboard is rendered by using image-based
flashboards.min_flex_height=
The minimum flashboard height below which a flashboard is rendered by using image-based
200
technology. The default is 200.
technology. The default is 260.
Configuring data points on flashboards

If the number of data points plotted on a flashboard exceeds the configurable limit of 3000 set by
Microsoft, you will see the error message: Cannot display a graph that contains more than {0}
data points.
To increase this limit, add the following to the config.properties file:
flashboards.maxDataPoints= <numberOfPoints>
Example
flashboards.maxDataPoints=4000
Multiple Flashboards servers and AR System servers

If you run multiple BMC Remedy AR System servers with multiple BMC Remedy Flashboards
servers on the same system, only one BMC Remedy Flashboards server is active at any given time
. This section describes procedures to override this setting to start one or more additional servers
manually.
For example, you might want to run multiple BMC Remedy Flashboards servers if you run multiple
BMC Remedy AR System instances when each instance is connected to a different database that
uses a different language.
Note
One of the BMC Remedy Flashboards servers can be installed on a remote system to
avoid having to start one service manually.
Page 829 of 4705
Home
To manually start a BMC Remedy Flashboards server

1. Change the value of the Remote Method Invocation (RMI) port in the server.conf file to any
port that is not in use.
Example
RMIRegistryPort=2099
2. Start the server:

To start the server on Microsoft Windows, use the Control Panel, or type start.bat
from the command prompt.
To start the server on UNIX, type server.sh.start from the command line.
The server.bat or server.sh file is located in the BMC Remedy Flashboards server
installation directory.
3. After installing, enter the RMI port values into the Flashboards server.conf files in the
Flashboards installation directory that correspond to each BMC Remedy Flashboards server,
as follows:
server.conf 1
server.conf 2
The port numbers must correspond to unused ports.

This section provides an overview and instructions for licensing and logging on to BMC Remedy
Migrator. It describes how to add and manage server accounts, license those accounts, and use
the licensed accounts to log on to a server.
Configuring BMC Remedy Migrator includes the following steps:
1. Starting BMC Remedy Migrator
2. Setting-up BMC Remedy Migrator
3. Adding AR System server into server account
4. Adding a licensed AR System server in BMC Remedy Migrator
5. Adding or transferring BMC Remedy Migrator license to an AR System server
6. Removing an AR System server and its BMC Remedy Migrator license from view
Page 830 of 4705
Home
Removing an AR System server and its BMC Remedy Migrator

license from view
Removing a server and its BMC Remedy Migrator license from the servers list makes the server
inaccessible to BMC Remedy Migrator, but it does not remove the license from the server (or from
the local BMC Remedy Migrator license file if the server is version 4.5.2 or older). It only removes
the server from the local machine and it can no longer be viewed.
To remove a server from view

1. In BMC Remedy Migrator, select Tools > Licenses.
2. In the Server Licenses dialog box, select a server, and click Remove.
3. In the message box, click Yes to confirm the license removal, or No to keep the license in
view.
4. After confirming the server removal, indicate whether you want to remove the server from
the local cache.
By doing this, you can remove servers from the Server Licenses list, but still keep some or
all of the servers cached.
Note
If you add a removed server back to the servers list later, the definitions are
retrieved the first time you log on to the server.
Adding AR System server into server account

Using the Accounts dialog box, you can add, modify, or delete server and limit access to users from
the available servers.
After you log on to BMC Remedy Migrator and open the Accounts dialog box, either a check mark
or an X appears next to each server name.
A green check mark indicates you can connect to the server.
A red X indicates you cannot connect to the server, even if the server has been licensed.
The following steps show how to manage your server accounts as an administrator.
To add AR System server into server account

1. Select Tools > Accounts to open the Account dialog box, which shows the servers that
have been added.
If the Accounts menu selection is unavailable, you must provide login information before
proceeding.
Page 831 of 4705
1.
Home
Accounts dialog box

2. In the Account dialog box, perform any of the tasks outlined in the following table:
Adding and modifying server information
To
Do this
Add a new server
Click Add, and enter a server name. If the server you are adding is a preference server, enter the
appropriate port numbers in the slide-out dialog box that appears at the right.
Modify an existing
server
Select the server, click Modify, and make the appropriate changes.
Delete a server
Select the server, and click Delete.
Add or modify the

Users list
Click User Manager. Click Add to add a new user, or select a name in the Users list and click
Modify to modify the user account.
Note
For each user to have their own server list, you must include a specific home directory
for that user in the directory path.
View port columns

for firewall support
Select Advanced Server Properties. Select a server and click a column and type a port number
or private server number:
AR TCP Port represents the port number of the AR System server.
AR RPC # represents the program number of the specified AR System server. This
number allows you to connect to a private server behind the firewall.
Warning
Page 832 of 4705
Home
You can set different TCP ports for each server, but if the ARTCPPORT
environment variable is defined, BMC Remedy Migrator uses the port defined by
the variable for all servers while ignoring the settings in the Accounts dialog box.
3. Click OK.
The new login information is not applied to your current session. You must log on again
before your changes take effect, or proceed to one of the following actions:
If the server you added needs a license, or does not yet exist in the Server Licenses
dialog box, see License overview for licensing information.
If the server you added has already been licensed, and has been added to the Server
Licenses dialog box, continue to Removing an AR System server and its BMC
Remedy Migrator license from view.
Adding a licensed AR System server in BMC Remedy Migrator

When you have logged into BMC Remedy Migrator, you can add a licensed AR System server.
One AR System server license is issued for each AR System server you want to work with using
BMC Remedy Migrator. There is no limit to the number of clients on which you can install BMC
Remedy Migrator.
To add a licensed AR System server in BMC Remedy Migrator

1. In BMC Remedy Migrator, select Tools > Licenses to open the Server Licenses dialog box.
Server Licenses dialog box in BMC Remedy Migrator
2. Click Add.
3. Select a server from the list, and click OK.
If the server is properly licensed, it is added to the list in the New Licenses section of the
Server Licenses dialog box.
4. Click Done.
For information about removing, importing, purging, or viewing the license, see Adding or
transferring BMC Remedy Migrator license to an AR System server .
Page 833 of 4705
Home
Adding or transferring BMC Remedy Migrator license to an AR

System server
To view BMC Remedy Migrator license details for a server, select Tools > Licenses.
Each AR System server must have its own BMC Remedy Migrator license. Information about
server licenses is stored in the AR System Licenses form, which can be accessed from BMC
Remedy Mid Tier.
If you transfer an AR System server license from one server to another, you must remove the BMC
Remedy Migrator license from view in the old server, and add it to the new server.
For information about removing a deleted AR System server from view in BMC Remedy Migrator,
see Removing an AR System server and its BMC Remedy Migrator license from view . For
information about adding a licensed server in BMC Remedy Migrator, see When you have logged
into BMC Remedy Migrator, you can add a licensed AR System server .
Starting BMC Remedy Migrator

After you have installed BMC Remedy Migrator, the Windows Start menu displays the BMC
Remedy Migrator icon in the program folder that you selected during the installation process.
To start BMC Remedy Migrator

1. If you created a shortcut on your desktop during installation, double-click the BMC Remedy
Migrator icon. Or, select BMC Remedy Migrator from the Start menu.
2. Obtain a license from BMC Customer Support.
You need a license for the AR System server if you do not already have one. For information
about contacting BMC Customer Support, see Support information.
Setting-up BMC Remedy Migrator

After you start BMC Remedy Migrator, open the Login dialog box.
Note
If you need to add a server or a license, the Login dialog box appears for the first session.
After the first session, if BMC Remedy Migrator finds the correct user information, the
Select Server dialog box appears instead of the Login dialog box.
During the login process, you have two choices to make:
Do you need to add a server?
Page 834 of 4705
Home
If you do, you must add the server from the Accounts dialog box. Select Tools >
Accounts to open the Accounts dialog box.
If the server is not listed, you must add it to the list. For information about adding a
server, see Adding AR System server into server account
If the server is listed, you can continue the login process.
Is the AR System server you want to use licensed?
If a listed server is not licensed, you must license it. For more information about
licensing AR System servers, see Setting license options.
If a listed server is already licensed, you can select it and log on.
Note
You must obtain a separate BMC Remedy Migrator license key for each AR
System server that you want to access with BMC Remedy Migrator. BMC
Remedy Migrator does not function on a server that is not licensed. Also,
you must enable or add BMC Remedy Migrator on a licensed AR System
server to use the server. For information about licensing AR System servers,
see License overview.
Configuring the Assignment Engine

The following topics provide information about configuring the Assignment Engine:
Configuring Assignment Engine properties
Stopping and starting the Assignment Engine
Configuring Assignment Engine properties

You can configure the following properties in the ar.cfg file:
Property
Description
The total number of worker threads that process various assignment requests. AE-Worker-Threads:
AE-Worker-Threads
<numberOfWorkerThreads>
You can also configure the AE-Worker-Threads property from the AR System Assignment Engine:
Server Settings tab. Specify a value in the Number of Threads box.
Note
If you modify the value of AE-Worker-Threads or Number of Threads, you must restart the
AE-Poll-Interval
The time interval (in minutes) after which the Assignment Engine checks for any pending entries for
Assignment. AE-Poll-Interval: <time>
Page 835 of 4705
Home
Important
The following properties are now obsolete:
AE-Trace
AE-Trace-File
AE-Log
AE-Log-File
Assignment Engine security

Assignment Engine uses the encrypted password for the user Remedy Application Service,
available in the ar.cfg (ar.conf) file for making any back end calls to BMC Remedy AR System.
Stopping and starting the Assignment Engine

By default, the Assignment Engine is automatically started and stopped by armonitor.exe (
Windows) or armonitor (UNIX) based on the following entry in the armonitor.cfg (armonitor.conf)
file:
"javaHome\bin\java" -Xmx512m -classpath"

<ARSystemInstallDir>\assignmentengine\bin;
<ARSystemInstallDir>\assignmentengine\bin\
araej<versionNumber>_<buildNumber>.jar;
<ARSystemInstallDir>\arserver\api\lib\arapi<versionNumber>_<buildNumber>.jar;
<ARSystemInstallDir>\arserver\api\lib\
arcmnapp<versionNumber>_<buildNumber>.jar;
<ARSystemInstallDir>\arserver\api\lib\log4j-1.2.14.jar;
<ARSystemInstallDir>\arserver\api\lib\arutil<versionNumber>_<buildNumber>.jar
"com.bmc.arsys.aej.AssignmentServer
-d "<ARSystemInstallDir>\" -m
For more information, see armonitor.exe or armonitor.
To start the Assignment Engine manually on Windows

1. At the command-line prompt, go to the <ARSystemInstallDir>\assignmentengine\bin
folder.
2. Enter aejstartup.bat.
To start the Assignment Engine manually on UNIX

1. At the shell prompt, go to the <ARSystemInstallDir>/assignmentengine/bin directory.
2. Enter ./aejstartup.sh.
Page 836 of 4705
Home
To stop the Assignment Engine manually on Windows and UNIX

Press Ctrl+C or kill the aejstartup process.
Securing BMC Remedy AR System

The following topics provide information about how to secure BMC Remedy AR System:
Resetting the Application Service password

Enterprise and stand-alone certification authorities (CAs) can issue certificates for secure email by
using SSL. This section explains in general terms how to configure the Secure Sockets Layer (SSL)
for use with Email Engine. There is no "one size fits all" CA solution. You must consider various
factors when using SSL, for example, what CA to use. Configuration differs considerably between
using a commercial CA authority like VeriSign and using a certificate server in a non-active
directory environment using Microsoft's Certification Authority management console.
Note
SSL is an open standard that Netscape Communications developed to establish

and protect web communications and prevent the interception of critical information
such as credit card numbers.
By default, the Email Engine does not use SSL; you must configure the Email
Engine for it to use SSL.
A digitally signed email message that uses SSL

Page 837 of 4705
Home
To configure SSL for Email Engine

1. Set up a local CA or search for a CA to use with your mail server.
You must decide whether to use a commercial CA (for example, VeriSign) or use a CA
created in-house. Most Windows system administrators can set up a CA on a Windows
server in just a few minutes. The primary difference between a commercial or in-house CA is
that a "cert" (certificate) issued by VeriSign is trusted far and wide, while a cert issued by an
in-house CA is not trusted by anyone outside the organization.
2. In Microsoft Exchange System Manager (used by a Microsoft Exchange system
administrator only), return the properties for the IMAP virtual server.
a. Use the Certificate Wizard to generate a cert request.
For the detailed procedure, see To generate a Certificate Signing Request (CSR) for
a Microsoft Exchange server.
b. Submit the cert request to the CA.
The procedures required to submit and receive a cert from a CA vary, depending on
the CA. For more information, see To create a CA certificate from a CSR .
c. Use the Certificate Wizard to install the cert received from the CA.
For more information, see To add an SSL certificate to a Microsoft Exchange server .
3. Make sure that email users obtain their own certificate.
a. Through the CA, generate a personal certificate that users will use for signing and
encrypting their email messages. With a local CA, you can retrieve and install the cert
using a browser.
Selecting a cert to use with your IMAP account
b. In the email client, open the Properties dialog for your IMAP account and select the
new cert to use for signing and encrypting email messages.
Two users who have properly configured the certs on their mail client must then
exchange certificates so that their communications can be secured.
c. Send email messages that are signed, but not encrypted, between the two users.
A signed email message
Page 838 of 4705
Home
Outlook Express provides the facility to sign and encrypt messages. The email client
should automatically notice the signed message and store the certificate so that it can
be used to encrypt further messages exchanged between the users.
To generate a Certificate Signing Request (CSR) for a Microsoft Exchange server

1. In Microsoft Exchange System Manager, expand Servers > serverName > Protocols >
IMAP4, and select Default IMAP4 Virtual Console.
The same procedure applies to POP3 and SMTP.
2. On the Default IMAP4 Virtual Server Properties dialog, open the Access tab, and click
Certificate.
3. On the Web Server Certificate Wizard:
a. On the first page, click Next.
b. On the Server Certificate page, select Create a new certificate if you have not yet
created an SSL certificate for your web server, and click Next.
If you already have an SSL certificate for your web server, select Assign an existing
certificate, and click Next. A list of the existing SSL certificates installed on your web
server appears; select the appropriate certificate and generate a CA from the CSR.
c. On the Name and Security Settings page, enter a unique name for the certificate,
select 1024 as the bit length, and click Next.
If you plan to install the trial certificate from VeriSign, do not select the Server Gated
Cryptography (SGC) certificate check box. For more information about SGC, see
your CA documentation on SSL algorithms.
d. On the Organization Information page, select an Organization and the
Organizational unit, and click Next.
e. On the Your Site's Common Name page, enter the common name for your site.
You can access the Microsoft Exchange server with this common name. This name
will also be used to configure SSL on Outlook Express.
Do not enter an IP address as the common name, otherwise the CA would create the
SSL certificate successfully.
f. On the Geographical Information page, select the appropriate Country/Region,
State/province, and City/locality, and click Next.
g. One the Certificate Request File Name page, enter the absolute path and file name
for the CSR (for example, certreq.txt ), and click Next.
Make sure that you provide a location that is easy to remember and access.
h.
Page 839 of 4705
Home
h. On the Request File Summary page, verify the information you provided so far, and
click Next if the information is accurate.
Otherwise, click Back to navigate to the appropriate pages and change the necessary
values.
i. On the final page, click Finish to complete the process and close the wizard.
To create a CA certificate from a CSR

1. Open a browser and navigate to https://www.verisign.com/prod/srv/trial/step1.html .
2. Enter the information required to create the trial SSL certificate.
3. When prompted for the CSR, copy the contents of certreq.txt file in the appropriate text
area.
4. Upon completing the steps, a certificate is generated and sent to the email address that you
entered in your information form.
5. Open a new file in a text editor, and copy the following contents from the email you received
from VeriSign:
*-----Begin Certificate----- <Encoded data> ... ... -----End Certificate-----*
Ensure that you do not select blank lines or spaces before Begin Certificate and after
End Certificate.
6. Save the file with the .cer extension, for example, web.cer.
To add an SSL certificate to a Microsoft Exchange server

2. On Default IMAP4 Virtual Server Properties dialog, open the Access tab, and click the
Certificate.
3. On the Web Server Certificate Wizard:
a. On the first page, click Next.
b. On the Pending Certificate Request page, select Process the pending request
and install the certificate, and click Next.
c. On the Process a Pending Request page, enter the absolute path and file name that
you provided when creating the CSR, and click Next.
To enable SSL communication on a Microsoft Exchange server

2. On the Default IMAP4 Virtual Server Properties dialog, open the Access tab, and click
Communication.
3.
Page 840 of 4705
Home
3. On the Security dialog, select Require secure channel, and click OK.
If you plan to install the trial certificate from VeriSign, do not select Require 128-bit
encryption.
To set up Microsoft Outlook Express and Email Engine

1. To use IMAPS (IMAP over SSL) for Outlook Express, open a browser and navigate to http://
www.verisign.com/products-services/security-services/ssl/buy-ssl-certificates/free-trial/
test-root-ca/trialcainstall.html.
Follow the prompts on the screen and install the test root CA on the computer where you
want to configure Outlook Express.
When prompted to enter the IMAP server address, you must provide the "common name"
you entered while creating the CSR. If you provide any other value or an IP address, the "CN
does not match with passed value" warning appears.
2. To configure Email Engine to use SSL, import the test root CA certificate in keystore by
using following command:
<javaHome>\bin\keytool -import -alias "testroot"

-keystore <javaHome>\lib\security\cacerts
-file <certFilePath>/testroot.cer
javaHome is the directory where JRE ( not JDK) is installed.
Note
Find the appropriate keystore path before entering the command. Email Engine uses the
location where Oracle Java Runtime Environment (Oracle JRE) is installed as the
keystore path.
Resetting the Application Service password

If you change the Application Service password on the AR System Administration: Server
Information form after you install Flashboards, you must run the Flashboards driver to reset the
password before running the BMC Remedy Flashboards server again. If you do not reset the
password, the BMC Remedy Flashboards server will not be able to log onto the BMC Remedy AR
System server.
Note
To avoid authentication failures, passwords for BMC Remedy AR System applications
must not exceed 20 characters.
Page 841 of 4705
Home
To reset the Application Service password

1. From the UNIX command line or the Windows Command Prompt, change to the
Flashboards installation directory.
2. Enter the following commands:
For Microsoft Windows:
java -classpath arutil<versionNumber>_<buildNumber>.jar;flashd<versionNumber>_<

buildNumber>.jar;.
-DflashInstallPath= <FlashboardsInstallationDirectory>
FBDriver
For UNIX:
java -classpath arutil<versionNumber>_<buildNumber>.jar:flashd<versionNumber>_<

buildNumber>.jar:.
-DflashInstallPath= <FlashboardsInstallationDirectory>
FBDriver
Note
The Windows command uses semicolons, and the UNIX command uses colons.
3. Type spw to set the password.

4. Follow the instructions on the screen.

Incoming and outgoing emails use different security mechanisms:
For validation, incoming email messages use security keys, the user's login and password,
or the user's email address. As long as the email has one of these security mechanisms,
BMC Remedy Email Engine executes the appropriate action. You can configure BMC
Remedy Email Engine to use all three methods; however, if the email message requests a
modify action, only a security key can validate the user's request.
Outgoing email messages, which can include the results of query actions, use BMC Remedy
AR System access control for forms and fields. If a user does not have access to the field or
form being queried, the field and its contents are not included in the outgoing email message
.
The following topics provide instructions for creating security keys for incoming email, describe how
security is handled for outgoing email, and provide instructions for configuring BMC Remedy Email
Engine to allow modify actions:
Page 842 of 4705
Home
Configuring BMC Remedy Email Engine for modify actions

Configuring BMC Remedy Email Engine for replying with results
Configuring incoming mailbox security
Configuring outgoing mailbox security
Configuring BMC Remedy Email Engine for modify actions

Modifications are executed by sending a modify instruction or modify action to BMC Remedy Email
Engine. Typically, you want only trusted users making changes to records, especially if they are
using email as a client to the AR System server. For security reasons, incoming email with modify
instructions do not work by default; you must configure the incoming mailbox to accept modify
actions.
Note
You must make sure that:
The same mailbox name is not being used at two places. For example, helpdesk@
onbmc.com is being referred to from two different AR System servers.
Two Email Engines are not pointing to same AR System Server.
To configure the Email Engine for modify actions

1. In a browser, open the AR System Email Mailbox Configuration form in Search mode.
2. Search for and open the records for your incoming and outgoing mailboxes.
3. Make sure that you have an incoming mailbox and an outgoing mailbox associated with
each other.
4. Click the Advanced Configuration tab of the incoming mailbox to which you want the
modify instruction sent.
5. Set the Email Action field to Parse.
6. Set the Enable Modify Actions field to Yes.
7. Set the Use Security Key field according to your requirements. For more information, see
the Use Security Key information in Configuring advanced incoming mailbox properties.
Note
If the Use Security Key value is set to Yes, you must provide a security key for
every user who sends modify instructions to BMC Remedy Email Engine.

9.
Page 843 of 4705
Home
9. Click the Advanced Configuration tab of the outgoing mailbox from which you want the
10. Set the Delete Outgoing Notification Messages field to No.
11. Open the AR System Email Security form in New mode.
12. Create a user record as follows:
a. Set Status to Enabled.
b. Create a security key.
c. Make sure that the Force For Mailbox field is set to No (default).
d. Select either Yes or No for the Force From Email Address.
This field enforces the email address that is associated with the key to be used. If set
to Yes, the From Address of the reply sent by the user is checked against the security
key entry's From Address.
e. Enter other information as needed, for example, an expiration date.
Note
A user making modifications must have a write license unless that user is
the submitter or the Submitter Mode is set to Locked.
Configuring BMC Remedy Email Engine for replying with results

When you set the Reply with Result and Reply with Entry fields on the AR System Email Mailbox
Configuration form to Yes, the Email Engine sends reply email back to the sender. The email
contains the information that was submitted, queried, or modified on the form.
To configure the Email Engine for replying with results

1. In a browser, open the AR System Email Mailbox Configuration form in Search mode.
2. Search for and open the records for your incoming and outgoing mailboxes.
3. Make sure that you have an incoming mailbox and an outgoing mailbox associated with
each other.
4. Click the Advanced Configuration tab of the outgoing mailbox.
5. (Recommended for testing purposes) Set the Delete Outgoing Notification Messages field
to No.
7. Click the Advanced Configuration tab of the incoming mailbox from which you want the
8. Set the following fields as indicated:
Email Action: Parse
Use Original Template Format: No
Reply With Result: Yes
Page 844 of 4705
8.
Home
Reply With Entry: Yes

Enable Modify Actions: No
Force Default Workflow Form: No
9. Set one of the following fields to Yes:
Use Security Key
Use Supplied User Information
Use Email From Address
Configuring incoming mailbox security

Security keys associated with an incoming mailbox validate the permissions for incoming emails to
perform various actions on the AR System server, such as modifying entries. In the AR System
Email Mailbox Configuration form, you specify whether a security key is required for email sent to a
mailbox (see Configuring advanced incoming mailbox properties). If you use a security key, you
must create the key and associate it with a mailbox.
When mail arrives, BMC Remedy Email Engine validates the security key included in the incoming
email message against the stored information. If the key is valid, the Email Engine validates the
mailbox owner name in the form.
To create email security keys

1. In a browser, open the AR System Email Security form in New mode.
2. Enter the following information in the fields:
Status Select Enabled to activate the key.
Key Enter a set of alphanumeric characters. Consider the following issues before
you enter the characters:
Security keys are case-sensitive. For example, CITYSCAPE, Cityscape, and
cityscape are all different.
Do not use names that are common to your working environment or that could
be easy to guess. For example, do not use a favorite product nickname, your
name, or a campus building name.
Mix numbers, letters, and special characters to make the key more difficult to
guess (for example, City2Scape or City!Scape ).
Do not use spaces, forward slashes, or backslashes.
User Name Enter the name of a valid AR System user to which the security key
applies.
Force for Mailbox To enable the security key for this mailbox only, select Yes.
To enable the key for all mailboxes in your email environment, select No.
Mailbox Name Enter the name of the incoming mailbox to which the security key
applies.
Page 845 of 4705
Home
Force from Email Addresses To require this key for emails received from specific
email addresses, select Yes. Allows the key to work only if it comes from the mailbox
contained in the email addresses field.
Email Addresses Enter the email addresses to which the security key applies, if
you enabled the Force from Email Addresses key.
Expires To specify an expiration date for the key, select Yes. The Expiration Date
field is enabled.
Expiration Date Enter an expiration date for this security key. After the key expires
, you can either modify the expiration date in this form or select No for the Expires
field.
Description Enter a description of the key. For example, explain why the key was
created or include instructions to modify or delete it.
Configuring outgoing mailbox security

Outgoing email messages, which can include the results of query actions, use BMC Remedy AR
System access control for forms and fields. If a user does not have access to the field or form being
queried, the field and its contents are not included in the outgoing email message.
The email server uses the following criteria to define security for outgoing emails that contain query
results:
An email sent to only one user can contain only data that the user has permission to view in
the browser.
An email sent to more than one user can contain only data that the user with the most
restricted permissions can view in the browser.
For example, if an email is sent to both an administrator with full access permissions and to
a user with only Public access, only data allowed by Public access are included in the email.
If the system locks a record by using the row-level access feature, the record are included
only if all email recipients have access to it.
If an email that includes query results is sent to a non-registered BMC Remedy AR System
user, the form and fields queried must have Public access, and the AR System server must
be configured to allow guest users.

This section explains how to configure BMC Remedy Encryption Performance Security and BMC
Remedy Encryption Premium Security.
To view and modify your AR System server's encryption configuration, use the Encryption tab in
the AR System Administration: Server Information form:
Note
Page 846 of 4705
Home
Do not use the AR System Configuration Component Setting form to configure encryption.
Encryption tab
The Encryption tab contains the following information:

Encryption Level Available The type of encryption installed on the server:
Standard Standard security
Performance BMC Remedy Encryption Performance Security
Premium BMC Remedy Encryption Premium Security
Note
The available level of encryption is displayed in this field whether encryption
is activated or not.
Active Encryption Settings The server's current encryption configuration.

Changes applied to the New Encryption Settings box do not appear in these read-only fields
until the server is restarted.
New Encryption Settings Fields in which you can change the server's encryption
configuration.
When you change these settings and click Apply, the changes are saved in the AR System
server configuration file (ar.cfg on Windows; ar.conf on UNIX). They do not take effect or
appear in the Active Encryption Settings box, however, until the server is restarted.
The following topics provide detailed information about configuring encryption security:
Page 847 of 4705
Home
Configuring the data key

Configuring the public key
Activating encryption
Deactivating encryption
Activating FIPS compliance
Configuring the data key

The data key processes data sent between a server and its clients after the initial connection is
established.
To configure the cryptograhic algorithm and size of the data key

1. Log on to the appropriate BMC Remedy AR System server.
2. Open the AR System Administration Console.
4. In the AR System Administration: Server Information form, click the Encryption tab.
5. In the New Encryption Settings: Data Key Details area, select one of these data
encryption algorithm options:
Option
Description
DES
56-bit Data Encryption Standard (DES) using Cipher Block Chaining (

CBC) mode.
RC4-128
128-bit RC4 key.

Available for Performance Security that does not comply with FIPS.
RC42048
2048-bit RC4 key.

Available for Premium Security that does not comply with FIPS.
AES-128
128-bit AES CBC key.

Required for Performance Security that complies with FIPS,
but can be used by servers that do not comply with FIPS.
Server configuration file

setting
Encrypt-Data-Encryption-Al
gorithm: 1
gorithm: 2
gorithm: 3
FIPS noncompliant:
gorithm: 6
See FIPS encryption options for more FIPS information.

FIPS compliant:
gorithm: 8
AES-256
FIPS noncompliant:
Page 848 of 4705
Home
Option
Description
256-bit AES CBC key.

Required for Premium Security that complies with FIPS,
but can be used by servers that do not comply with FIPS.

setting
gorithm: 7
FIPS compliant:
See FIPS encryption options for more FIPS information.
gorithm: 9
Note
The available algorithms depend on the type of encryption installed and the setting
of the FIPS Enabled option.
6. (Optional) In the Key Expire Interval field, specify a different life span for the key in seconds
.
The default is 2700 seconds (45 minutes). At the end of the specified time, the key expires,
and a new key exchange occurs.
Note
Generating keys more frequently provides higher security at some marginal impact
to performance.
In the AR System server configuration file, this setting is specified as follows:
Encrypt-Symmetric-Data-Key-Expire: 2700
7. Click Apply.
9. Relog on to any clients that are connected to the server.
Configuring the public key

BMC Remedy Encryption Performance Security and BMC Remedy Encryption Premium Security
use the RSA algorithm for public key cryptography to exchange private keys. This key exchange
occurs at the beginning of the API session and when the data encryption keys expire.
If the server's security policy is changed while a client is running, the client connections using the
old policy automatically perform a key exchange to create keys that correspond to the new policy.
Page 849 of 4705
Home
To configure the cryptograhic algorithm and size of the public key

5. In the New Encryption Settings: Public Key Details area, select one of these data
encryption algorithm options:
Option
Description

setting
RSA 512
512-bit RSA key. Default for standard security.

Encrypt-Public-Key-Algori
thm: 4
RSA
1024
1024-bit RSA key. Default for BMC Remedy Encryption Performance

Security.
RSA
2048
2048-bit RSA key. Default for BMC Remedy Encryption Premium Security.
thm: 5
thm: 6
Note
The available algorithms depend on the type of encryption installed and the setting
of the FIPS Enabled option.
6. (Optional) In the Key Expire Interval field, specify a different life span for the key in seconds
.
The default is 86400 seconds (24 hours). At the end of the specified time, the key expires,
and the server generates a new key.
Note
Generating keys more frequently provides higher security at some marginal impact
to performance.
In the AR System server configuration file, this setting is specified as follows:
*Encrypt-Public-Key-Expire: 86400*
Page 850 of 4705
Home
7. Click Apply.
Activating encryption
The Security Policy value in the Encryption tab (see Encryption tab) determines whether
encryption is required to communicate with the server.
To activate or deactivate encryption

5. In the New Encryption Settings area, select one of these options in the Security Policy list
:
Encryption
state
Value
Description

setting
Activated
Optional
This is the default for BMC Remedy Encryption
Encrypt-Security-Policy
Performance Security and BMC Remedy Encryption

Premium Security FIPS noncompliance.
: 0
Clients with and without encryption installed can

communicate with the server.
Network traffic is encrypted only if the client supports the
server encryption configuration.
Otherwise, network traffic is exchanged in plain text.
Activated
Required
This is the default for BMC Remedy Encryption

Performance Security and BMC Remedy Encryption
Premium Security FIPS compliance.
Only clients with encryption installed can communicate with
the server.
: 1
Note
The encryption level installed on the client (
standard, BMC Remedy Encryption Performance
Encryption, or BMC Remedy Encryption Premium
Encryption) must be compatible with the
encryption algorithms used by the server.
Deactivated
Disabled
This is the default for standard encryption.

Whether encryption is installed on a client or not,
: 2
communication with the server is not encrypted. Network

traffic is exchanged in plain text.
Page 851 of 4705
Home
Note
If the Encrypt-Security-Policy entry is missing from the configuration file,
encryption is also deactivated.
See Security policy impact on client-server communication for Security policy planning
information.
6. (Optional) In the Data Key Details area, change the defaults. See Configuring the data key.
7. (Optional) In the Public Key Details area, change the defaults. See Configuring the public
key.
8. (Optional) Activate FIPS compliance. See Configuring the data key.
9. Click Apply.
Deactivating encryption
To deactivate encryption, select the deactivation options according to the procedure in Configuring
the data key.
Activating FIPS compliance

If BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security
8.0.00 or later is installed on a server, use the FIPS Enabled option in the Encryption tab (see
Encryption tab) in conjunction with the Security Policy setting to switch compliance with Federal
Information Processing Standard (FIPS) 140-2 on or off:
FIPS
Enabled
option
Security Policy
value
Is server FIPS
compliant?
Selected
Required
Yes
Description
Only FIPS-compatible (that is, release 8.0.00 or later) clients

can communicate with the server.
Clients communicating with the server can communicate only
with other FIPS-compliant servers.
Selected
Disabled
No
Clients communicating with the server cannot communicate with

FIPS-compliant servers.
Cleared
Optional, Required,
No
Clients communicating with the server cannot communicate with

FIPS-compliant servers.
or Disabled
For an overview of FIPS, see FIPS encryption options.
Note
Page 852 of 4705
Home
For Java-based clients such as BMC Remedy Developer Studio and the mid tier, the first
server that a client connects to determines whether the client is restricted to interacting
with FIPS-compliant or noncompliant servers. Logging out of the client does not terminate
the FIPS restriction. Instead, the client must be restarted.
Transition tips
If you are in the process of converting to a FIPS-compliant environment, consider these tips:
Do not select the FIPS Enabled option for a server until all clients that must communicate
with that server have the appropriate BMC Remedy Encryption Performance Security or
BMC Remedy Encryption Premium Security 8.0.00 or later installed.
During the transition phase, set the Security Policy to Optional on all servers that have BMC
Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security
8.0.00 or later installed so that they can communicate with clients that have not yet been
upgraded to 8.0.00 or later.
Be aware that when a server's Security Policy is set to Optional and a client cannot
support the encryption algorithm (such as AES) required by the server, communication
between the server and client is unencrypted.
To activate FIPS compliance

1. Ensure that one of these products is installed on the appropriate BMC Remedy AR System
server and on any clients that will communicate with the server:
BMC Remedy Encryption Performance Security 8.0.00 or later
BMC Remedy Encryption Premium Security 8.0.00 or later
Note
You can also activate FIPS compliance while installing these products. See
Installing BMC Remedy Encryption Security.
2. Log on to the server.

6. In the New Encryption Settings area, select the FIPS Enabled option.
7. In the Security Policy list, select Required.
8. In the Data Key Details area, select an AES algorithm.
See Configuring the data key.
Note
Page 853 of 4705
8.
Home
DES and RC4 algorithms are not FIPS compliant.
9. In the Public Key Details area, select an RSA algorithm.

See Configuring the public key.
10. Click Apply.
In the AR System server configuration file, servers use one of these encryption
configurations when FIPS compliance is on:
Encryption level
AR System server configuration file settings
Performance
Encrypt-Security-Policy: 1 Encrypt-Data-Encryption-Algorithm: 8
Premium
Encrypt-Security-Policy: 1 Encrypt-Data-Encryption-Algorithm: 9

13. Open the Java plug-in server configuration file ( pluginsvr_config.xml ) in a text editor.
By default, the file is in the ARServerInstallDir\pluginsvr directory.
14. In the following entry, set integer to 8 (Performance Security) or 9 (Premium Security):
<dataEncryptionAlg> integer</dataEncryptionAlg>
15. In the following entry, ensure that integer is set to 1 (Required).
<encryptionPolicy> integer</encryptionPolicy>
16. Save the configuration file.
17. Restart the Java plug-in server.
Using Oracle CLOBs with BMC Remedy AR

System
This section evaluates the storage and performance impacts of using in-row versus out-row storage
for large objects (LOBs) in a database table in BMC Remedy AR System.
The following topics provide information and instructions:
About Oracle LOBs
Storage size impact
Performance impact
Converting LOB storage
About Oracle LOBs

The Oracle database provides two options for storing data in large object (LOB) columns in a
database table:
In-row option Stores the LOB column in the row (inline) with other columns in the same
data block if the length of the LOB is less than 4000 bytes. (This is the default option.)
Page 854 of 4705
Home
Out-row option Stores the LOB column out of the row in a separate LOB segment.
If the length is greater than 4000 bytes, the LOB value is stored out of the row in the LOB segment
no matter which storage option is specified.
To specify the storage option at the Oracle database level, use the ENABLE|DISABLE STORAGE
IN ROW clause of the CREATE TABLE statement.
To control Oracle character large object (CLOB) storage at the system level, use the AR System
server configuration file Oracle-Clob-Storage-In-Row option.
A CLOB can hold more than 4000 characters. To create a CLOB in BMC Remedy AR System, use
one of the following fields:
BMC Remedy AR System character field with a database input length of 0
BMC Remedy AR System diary field
Setting CLOB fields to be stored in-row can save storage space and improve performance for
values that have fewer than 4000 characters. When values have more than 4000 characters, the
in-row option is similar to the out-row option with respect to storage and performance. Although the
inrow option saves space and improves performance in many cases, BMC recommends that you
conduct similar benchmark tests with your data to determine which option is best for your
environment.
For details about the CLOB data type and different storage options, see your Oracle documentation
.
Note
In BMC Remedy AR System, the attachment field creates a BLOB column. BLOBs are
stored in separate tables as part of the BMC Remedy AR System schema design. By
default, BLOBs are stored in-row and are not affected by the
Oracle-Clob-Storage-In-Row server configuration option.
Storage size impact

The following factors account for the difference between in-row and out-row storage usage:
Length of the data.
Database BLOCKSIZE. More specifically, the block size of the tablespace on which the LOB
resides.
CHUNKSIZE, which is a parameter that you can specify when creating the large object (LOB)
. The minimum for this parameter is the block size of the tablespace on which the LOB
resides. The chunk size can also be a multiple of the block size.
Page 855 of 4705
Home
Assuming that the default Oracle 8 kilobyte (KB) block size is used, the in-row option uses less
storage space than the out-row option when the following criteria are met (because the LOB value
is stored in the table):
The size of the LOB value is less than 4000 bytes.
The in-row option is specified.
A simple test that populated a BMC Remedy AR System diary field with 3500 characters showed
that the in-row option uses significantly less storage than the out-row option. This test consisted of
10,500 rows. The other required field values remained constant.
The following SQL statement was issued to find the storage size of the table and its LOB segment.
A LOB segment is created regardless of the LOB storage properties.
SELECT bytes, segment_type FROM user_segments WHERE segment_name IN('
T1344','SYS_LOB0001143348C00009$$');
The total bytes from the table and LOB segment were added to give the total storage space. The
following table shows that the in-row option saves 50,266,112 bytes of storage when LOB value
sizes are less than 4000 bytes.
Storage bytes of values that have fewer than 4000 characters
Test
In-row
Out-row
3500 characters; 10,500 rows
44,105,728 bytes
94,371,840 bytes
Out-row storage has the following characteristics, which result in the large use of storage space:
If the table is created with the out-row property and the LOB holds any data, a minimum of
one chunk of out-of-line storage space is used, even when the size of the LOB is less than
the CHUNKSIZE.
When the size of the LOB is greater than 4000 bytes, regardless of the LOB storage
properties for the column, it is stored as out-row in another segment outside the table.
However, the LOB locators are always stored in the row.
Another test with 10,000 characters in the diary field showed that for both in-row and out-row
options, the storage sizes were equivalent. This test consisted of 10,500 rows. The other required
field values remained constant.
Storage bytes of values that have more than 4000 characters
Test
In-row
Out-row
10,000 characters; 10,500 rows
178,257,920 bytes
178,257,920 bytes
Page 856 of 4705
Home
This result shows that if the in-row option is used as the default, storage space is reduced when the
LOB value is less than 4000 bytes. Storage space is not impacted when the LOB value is greater
than 4000 bytes because this is equivalent to using the out-row option. This situation is also true for
BMC Remedy AR System attachment fields (BLOBs). By default, attachment fields use the inrow
option and cannot be changed.
Finally, a similar test was conducted by populating 50 characters in the diary field for the in-row and
out-row storage options for 10,500 rows.
Storage bytes of 50 characters
Test
In-row
Out-row
50 characters; 10,500 rows
3,211,264 bytes
94,371,840 bytes
In this case, the out-row space usage is significantly higher than the in-row space usage. The
out-row option uses more space for small data sizes.
Performance impact
When values are greater than 4000 characters, in-row and out-row storage space usage is
equivalent. However, response time performance might be better when the in-row option is used.
The BMC Incident Management application contains a few character large object (CLOB) fields.
One such visible field is the detailed description field in the Incident form. A small load test of 60
users was run with each user creating an incident ticket repeatedly for one half hour. The average
mid-tier response time was recorded when the database was configured for outrow and in-row
storage. The following table shows that the mid tier performs better with the inrow option, whether
the number of characters is greater than or less than 4000.
Response times for creating incidents
Create incident test
In-row
Out-row
Description field value < 4000 characters
0.43 s
0.73 s
Description field value > 4000 characters
0.56 s
0.72 s
Additional tests with the BMC Service Request Management application show that using the in-row
option significantly improves performance. A test of 400 users executing various actions for an hour
was run, and the average mid-tier response time was recorded when the database was using
out-row and in-row options. The following figure shows that the in-row option improves response
time by at least 50%. The search keyword, the create service request, and the add work
information actions all touch the CLOB fields.
BMC Service Request Management in-row and out-row response times
Page 857 of 4705
Home
When a BMC Remedy AR System entry is requested, all column values are obtained, including 0
length fields. Because of this, performance can be slightly faster when the in-row option is used
because values that have fewer than 4000 characters are stored in the row.
Converting LOB storage

If your BMC Remedy AR System is currently using out-row storage, you can convert it to use in-row
storage, and vice versa. The following Oracle PL/SQL procedure changes the in-row or out-row
option of all the large object (LOB) columns in an Oracle schema.
The following case studies describe how to convert LOB storage:
Case 1 - Applying changes to all LOBs
Case 2 - Applying changes to LOBs only in a specified table
Case 3 - Displaying SQL statements only
To change the storage option

1. From SQL*Plus or other tools, connect to the Oracle database server as the ARAdmin user.
2. Create the following PL/SQL p_change_LOB_storage procedure:
create or replace procedure p_change_LOB_storage

(
p_in_row varchar2 default 'Yes',
p_dest_tablespace varchar2 default 'ARSYSTEM',
Page 858 of 4705
Home
p_table_name varchar2 default '%',

p_generate_SQL_only varchar2 default 'No'
)
as
lv_block_size number;
lv_in_row_clause varchar2(400);
lv_chg_to_inrow varchar2(3) default 'NO';
lv_chg_to_outrow varchar2(3) default 'NO';
lv_no_inrow_outrow_chg varchar2(3) default 'NO';
lv_sql_statement varchar2(4000 byte) default '';
BEGIN
-- check specified in_row option
IF p_in_row is not null and upper(p_in_row) not in ('YES','NO','Y','N') then
raise_application_error(-20001,'The first parameter(p_in_row) must be Yes,No or
Null.');
END IF;
-- check p_generate_SQL_only
IF upper(p_generate_SQL_only) not in ('YES','NO') then
raise_application_error(-20001,'The parameter p_generate_SQL_only must be Yes
or No.');
END IF;
-- three cases:
select case when upper(p_in_row) in ('YES' ,'Y') then 'YES' else 'NO' end
chg_to_inrow,
case when upper(p_in_row) in ('NO' ,'N') then 'YES' else 'NO' end
chg_to_outrow,
case when p_in_row is NULL then 'YES' else 'NO' end no_inrow_outrow_chg
into lv_chg_to_inrow,
lv_chg_to_outrow ,
lv_no_inrow_outrow_chg
from dual;
lv_in_row_clause :='';
select case when lv_chg_to_inrow='YES' then 'enable storage in row'
when lv_chg_to_outrow ='YES' then 'disable storage in row'
when lv_no_inrow_outrow_chg='YES' then ''
else 'error:unknown cases'
end in_row_clause
into lv_in_row_clause
from dual;
-- get the block size of destination tablespace
BEGIN
select block_size into lv_block_size
from user_tablespaces where TABLESPACE_NAME=p_dest_tablespace;
EXCEPTION
WHEN NO_DATA_FOUND THEN
raise_application_error(-20002,'The tablespace '||p_dest_tablespace||'does not
exist.');
WHEN OTHERS THEN
raise;
END;
-- use FOR loop and SQL to generate 'Alter table ... move LOB ...'SQL command
FOR r IN (
select distinct l.TABLE_NAME,
case when 'YES'= (select logging from user_tables t where t.table_name=
l.table_name )
Page 859 of 4705
Home
then
'Alter table '||l.table_name||' logging'
else
null
end alt_logging_cmd
from user_lobs l join user_tables t on l.table_name = t.table_name
where l.table_name like p_table_name
and (
l.in_row in ( case when lv_chg_to_inrow='YES' then 'NO' else '' end,
case when lv_chg_to_outrow='YES' then 'YES' else '' end)
or l.tablespace_name <> p_dest_tablespace
)
)
LOOP
lv_sql_statement := 'alter table '||r.table_name||' move ';
for r_lob in (
select ' lob ('||column_name
||') store as (chunk '||to_char(lv_block_size)
||' tablespace '||p_dest_tablespace
||' '|| lv_in_row_clause ||' ) '
mv_lob_clause
from user_lobs l join user_tables t on l.table_name = t.table_name
where l.table_name =r.table_name
and (
l.in_row in ( case when lv_chg_to_inrow='YES' then 'NO' else ''
end,
case when lv_chg_to_outrow='YES' then 'YES' else ''
end)
or l.tablespace_name <> p_dest_tablespace
)
)
LOOP
lv_sql_statement :=lv_sql_statement ||r_lob.mv_lob_clause;
END loop;
lv_sql_statement := lv_sql_statement ||' nologging';
dbms_output.put_line (lv_sql_statement);
if r.alt_logging_cmd is not null then
dbms_output.put_line (r.alt_logging_cmd);
end if;
if upper(p_generate_SQL_only) <>'YES' THEN
-- execute SQL
execute immediate lv_sql_statement;
if r.alt_logging_cmd is not null then
execute immediate r.alt_logging_cmd;
end if;
end if;
-IF upper(p_generate_SQL_only) ='YES' THEN
FOR r1 IN (
select 'Alter index '||index_name ||' rebuild nologging' sqlCmd,
case when ind.logging='YES' then
'Alter index '||ind.index_name||' logging'
else null
end alt_logging_cmd
Page 860 of 4705
Home
from user_indexes ind where table_name = r.table_name and index_type <>'

LOB'
)
LOOP
dbms_output.put_line (r1.sqlCmd);
if r1.alt_logging_cmd is not null then
dbms_output.put_line (r1.alt_logging_cmd);
end if;
END LOOP;
END IF;
IF upper(p_generate_SQL_only) <>'YES' THEN
FOR r1 IN (
select 'Alter index '||index_name ||' rebuild nologging' sqlCmd,
case when ind.logging='YES' then
'Alter index '||ind.index_name||' logging'
else null
end alt_logging_cmd
from user_indexes ind
where table_name = r.table_name and status = 'UNUSABLE'
)
LOOP
dbms_output.put_line (r1.sqlCmd);
execute immediate r1.sqlCmd;
if r1.alt_logging_cmd is not null then
dbms_output.put_line (r1.alt_logging_cmd);
execute immediate r1.alt_logging_cmd;
end if;
END LOOP;
END IF;
END LOOP;
END;
/
3. Execute the p_change_LOB_storage procedure with appropriate parameter values.

The storage option is changed.
Case 1 - Applying changes to all LOBs

To apply changes to all LOBs, execute the procedure as specified in the following table.
Task
SQL statement
Change all LOBs from out-row to in-row, and keep
exec p_change_LOB_storage(p_in_row =>'Yes',

p_dest_tablespace =>'ARSYSTEM');
them in tablespace ARSYSTEM.

Change all LOBs from out-row to in-row, and move
them to tablespace AR_LOB.

p_dest_tablespace =>'AR_LOB');
Move LOBs to tablespace AR_LOB without changing

the storage option.
exec p_change_LOB_storage(p_in_row =>Null,
Change all LOBs from in-row to out-row, and keep
exec p_change_LOB_storage(p_in_row =>'No',

p_dest_tablespace =>'ARSYSTEM');
them in tablespace ARSYSTEM.
p_dest_tablespace =>'AR_LOB');
Page 861 of 4705
Home
Case 2 - Applying changes to LOBs only in a specified table

To apply changes to LOBs only in specified tables, execute the procedure as specified in the
following table.
Task
SQL statement
Change the LOBs in table T1866 from out-row to

p_dest_tablespace =>'ARSYSTEM', p_table_name =>'T1866');
in-row, and keep them in tablespace ARSYSTEM.

Change the LOBs in table T1866 from out-row to
in-row, and move them to tablespace AR_LOB.

p_dest_tablespace =>'AR_LOB', p_table_name =>'T1866');
Move LOBs in table T1866 to tablespace
exec p_change_LOB_storage(p_in_row =>Null,
AR_LOB without changing the storage option.
p_dest_tablespace =>'AR_LOB', p_table_name =>'T1866');
Change LOBs in table T1866 from in-row to
exec p_change_LOB_storage(p_in_row =>'No',
out-row, and keep them in tablespace
p_dest_tablespace =>'ARSYSTEM', p_table_name =>'T1866');
ARSYSTEM.
Case 3 - Displaying SQL statements only

The p_change_LOB_storage stored procedure runs SQL statements to apply changes to large
objects (LOBs). To display those SQL statements without applying changes to the LOBs, execute
the procedure as specified in the following table.
Task
SQL statement
Display the SQL statements that the stored procedure
Set serveroutput on
will execute to change the LOBs in table T1866 from

out-row to in-row.
Display the SQL statements that the stored procedure

will execute to change all LOBs from out-row to in-row
Set serveroutput on
and move them to tablespace AR_LOB.
p_dest_tablespace =>'AR_LOB', p_generate_SQL_only='
p_dest_tablespace =>'ARSYSTEM', p_table_name =>'T1866

', p_generate_SQL_only='Yes');

Yes');
Monitoring API calls

As BMC Remedy administrator, you can monitor the AR System server API calls by configuring
certain fields in the AR System Server Information Advanced tab. You can monitor the API
calls between an AR System server and its clients and capture the following information, which is
recorded in the AR System API Statistics form:
Number of API calls by client type (for example, mid tier or BMC Remedy Developer Studio)
Total amount of data sent to the client as a result of the API calls
Total amount of data sent by the client to the server as a request
Number of successful API calls
Number of failed API calls
IP address of the client from where the call was initiated
IP address of the server that responded to the request
Page 862 of 4705
Home
To monitor API calls

Server Information.
3. In the API Recording Client Types field, enter the client types for which you want to
monitor API calls.
By default, calls from all client types are monitored. Specify values separated by semicolons
in the following format: clientType;IPAddressExpression;clientType;IPAddressExpression.
For more information, see Setting performance and security options.
4. In the Enable API Recording field, select whether you want to enable the system for
monitoring API calls.
By default, monitoring is disabled. Selecting Yes in this field indicates that you have enabled
the system for monitoring.
For more information, see Setting performance and security options.
5. Save the changes.
To view API call details

Open the AR System API Statistics form by typing the URL in a browser in this format: http://
midTier:port/arsys/forms/server/AR+System+API+Statistics.
The AR System API Statistics form displays the following information:
Field name
Description
Client type
Type of client that initiated an API call (see the following table)
Total count
Total number of successful and failed calls
Error count
Number of unsuccessful calls
Client IP Address
IP address of the client making a call
End client IP Address
IP address of the client using the mid tier or the web service
Data In
Total number of bytes sent as a request from the source IP address
Data Out
Total number of bytes sent out as a response to the API call
Start Timestamp
Time when the API call monitoring started, specified in hours. The monitoring time frame is 1 hours.
End Timestamp
End time of API call monitoring. For example, if the start time is 03:00, the end time will be 04:00.
Server
IP address of the computer where the AR System server is running
The following table lists the supported client types and the value associated with each client type.
Client types
Page 863 of 4705
Home
Client type
Value
Unknown
Pre-5.0 AR System clients
BMC Remedy Administrator
BMC Remedy User
BMC Remedy AR System ODBC
AR Web Server
BMC Remedy Mid Tier
Palm Pilot
10
11
Flashboards Mid Tier
12
BMC Remedy Enterprise Integration Engine
13
arreload
14
arcache
15
ardist
16
runmacro
17
armail
18
Command-line import tool
19
Report Creator plug-in
20
22
Debugger
24
Object Store API
25
Object Store Sync Utility
26
Server Administration plug-in
27
BMC Service Impact Management Publishing server
28
BMC Service Impact Management Service Model Editor
29
BMC Atrium CMDB Engine
30
BMC Atrium CMDB Driver
31
BMC Atrium CMDB Reconciliation Engine
32
33
BMC Remedy AR System Web Service
34
Page 864 of 4705
Home
Client type
Value
Normalization Engine
35
36
Full Text Reader
37
BMC Atrium Single Sign-On Server
38
AR Migrator
39
AR UDM Adapter
40
BMC Remedy Knowledge Management Operations plug-in
41
BMC Remedy Knowledge Management Form Permissions plug-in
42
BMC Remedy Knowledge Management Document Migrator plug-in
43
BMC Remedy Knowledge Management File System plug-in
44
BMC Remedy Knowledge Management File System Sync plug-in
45
BMC Remedy Knowledge Management Group plug-in
46
BMC Remedy Knowledge Management Registration plug-in
47
BMC Asset Management SWLM Rule Engine plug-in
48
BMC Asset Management Software Usage plug-in
49
BMC Asset Management RLE Configuration plug-in
50
BMC Asset Management Charge Back plug-in
51
BMC Remedy IT Service Management (ITSM) Common plug-in
52
BMC Remedy ITSM CAI plug-in
53
BMC Remedy ITSM Utility plug-in
54
BMC Remedy ITSM AppQuery plug-in
55
BMC Remedy ITSM Next ID plug-in
56
BMC Atrium Integrator
57
BMC Atrium Discovery (ADDM)
58
BMC Proactive Performance Management
59
Driver
4000
Dispatcher
4001
arhelp
4002
arjanitor
4003
armenu
4004
arstruct
4005
artext
4006
arsqled
4007
Page 865 of 4705
Home
Client type
Value
archgsel
4008
archgid
4009
arlabel
4010
BMC Remedy AR System Installer
4011
BMC Remedy Install Kit (RIK)
4012
Reserved range
5000
Page 866 of 4705
Home
Upgrading
For the latest installation information, see BMC Remedy ITSM 9.0 Deployment online
documentation .
About BMC Remedy ITSM Suite 9.0

Deployment online documentation
The following graphic illustrates scope and the contents of this online documentation.
The following table describes the contents of the different branches in this online documentation.
Branch
Description
Planning the
deployment
This section describes the deployment scenarios for the following new components:
Click here for a list of topics in this section
Planning BMC Remedy Smart Reporting deployment
Planning BMC Remedy shared service architecture
Preparing
This section provides information about the preparation you must do before installing or upgrading any
component of the BMC Remedy ITSM Suite.
Reviewing system requirements
Downloading the installation files
Obtaining BMC Remedy license keys
Preparing your database
Preparing the base platform
Preupgrade checks and configuration checks
Completing the planning spreadsheet
Page 867 of 4705
Home
Installing
This section provides information about the steps for performing a fresh installation.
Installing the platform components
Installing the application components
Installing offline documentation
Deploying BMC Remedy shared services
Upgrading
This section provides information about the steps for performing an upgrade.
Interactive end-to-end steps depending on the base version:
Upgrading from version 8.1 and later
Upgrading from a version 7.6.04 or 8.0.xx
Upgrading from a version earlier than 7.6.04
Upgrading information the individual components in the BMC Remedy ITSM Suite
Upgrading the platform
Upgrading the applications
Detailed information of different stages within the upgrade process:
Restrictions after restoring the database on the upgrade server
Setting up upgrade servers
Capturing a snapshot of your current environment
Creating overlays
Adjusting customizations when upgrading
Migrating customizations
Setting up a staging server
Updating hard-coded server hostname references
Migrating delta data
Update to the multi-tenancy model
Post-upgrade activities
Upgrading secondary servers
User acceptance testing
Cutover activities
Go live activities
Troubleshooting
This section provides information about troubleshooting the issues specific to install or upgrade.
Working with logs
Troubleshooting data and workflow import issues
Troubleshooting driver issues
Troubleshooting information for individual components in the BMC Remedy ITSM Suite
Troubleshooting BMC Remedy AR System issues
Troubleshooting BMC Atrium Core issues
Troubleshooting BMC Remedy ITSM issues
Troubleshooting Process Designer issues
Troubleshooting BMC Service Request Management issues
Troubleshooting BMC Service Level Management issues
Troubleshooting the multi-tenancy update
Page 868 of 4705
Home
Integrating
This section is written for developers and administrators who are responsible for creating,
customizing, and maintaining integrations between BMC Remedy AR System and external systems
.
Before applying any instructions in this section, you should have a strong working knowledge of
BMC Remedy AR System and BMC Remedy Developer Studio. Also, working knowledge of the
external systems that you are considering for integration with BMC Remedy AR System is helpful.
Goal
Instructions
Selecting integration points, platforms, an implementation method, and a technology method
Integration considerations
Extending AR System server functionality to external data by using installed and created plug-ins
Enabling Plug-ins
Configuring and using the ARDBC and AREA LDAP plug-ins to integrate BMC Remedy AR System
Integrating with a directory
with a directory service
service
Using plug-ins and the AREA API to integrate BMC Remedy AR System with external user
authentication services
AR System external
authentication
Viewing and processing external data, accessing external relational database tables, reading data
from the AR System database with a third-party application, and providing read-only access to data
Data and database

integrations
in BMC Remedy AR System forms

Creating custom plug-ins for BMC Remedy Developer Studio
Extending BMC Remedy

Developer Studio
Automating tasks and processes by integrating BMC Remedy AR System with BMC Atrium
Orchestrator
BMC Atrium Orchestrator

integration
Importing and exporting data to or from BMC Remedy AR System across the BMC Remedy ITSM
product suite
Atrium Integrator adapter

for BMC Remedy AR
System
Executing and controlling external applications within workflow to supplement AR System servers
and clients
Running external processes

with the Run Process action
Automatically specifying the person responsible for handling a request in an application
Integrating the BMC

Remedy Assignment
Engine into an application
Page 869 of 4705
Home
Integration considerations
Special mechanisms can be used to integrate BMC Remedy AR System with another application.
This section discusses the issues to consider when planning an integration.
This section contains information about:
Where to integrate BMC Remedy AR System
Multiplatform issues
Choosing an implementation method
Integration technologies
Where to integrate BMC Remedy AR System

The three options for integration points with BMC Remedy AR System are the client, the server,
and the database server. The choice depends on the nature of the integration and whether user
interaction is involved.
In this topic:
Integrating BMC Remedy AR System client
Integrating the AR System server
Integrating the database
Integrating the mid tier
Integrating BMC Remedy AR System client

BMC Remedy AR System to third-party application Integration with the BMC Remedy
AR System client typically involves taking data from a form and passing it to another
application where the user can then perform some additional function. Integration can also
simply consist of launching another application that reads data from the BMC Remedy AR
System database. In general, client integration assumes that the user will access the other
application to some extent. Most instances are real-time, where a user is involved right now.
Page 870 of 4705
Home
Third-Party application to BMC Remedy AR System Often, a third-party application

launches a mid tier and directs it to display specific data. For example, a network
management system might have a graphical map of the network devices. Selecting a device
on the map and choosing a "List Open Tickets" from a menu could cause the mid tier to be
triggered with the ID of the selected device passed as a parameter, and generate a results
list of all of the open trouble tickets for the device. This way, a network technician can quickly
see all of the outstanding problems for a device, but does not need to know the details of
starting BMC Remedy AR System and issuing queries.
Integrating the AR System server

Integration with the AR System server generally implies data sharing or transfer, either to or from
the server. The integration might involve workflow that triggers secondary actions. Sometimes, the
server initiates the interaction. For example, a filter is triggered that uses a Run Process action to
call a pager application to send a notification to a technician. In other instances, a third-party
application might submit new requests to the server or query for the status of existing requests. For
example, a system management agent running on a PC might discover the addition of a new sound
card. The agent sends a message to a (remote) management application that, in turn, submits a
new request to an asset application in BMC Remedy AR System. BMC Remedy AR System users
are not directly aware that a new request has been created, but the next time someone generates
an asset report, the new information is included.
Integrating the database

The following three modes of integration involve the database directly:
A third-party application reading the AR System database
BMC Remedy AR System reading an external database
BMC Remedy AR System writing to an external database
The first two modes, which involve reading databases, are relatively straightforward. Any
application that can issue SQL commands and which has the appropriate permissions can read the
data in the AR System tables. In a similar manner, AR System workflow actions can execute SQL
read commands and scripts that query external database tables and retrieve information. For more
information, see the Integrating section.
The third mode, having BMC Remedy AR System write data to an external database table, can be
accomplished using Direct SQL. Another method is to create AR System workflow that executes an
SQL command script, passing any AR System data as parameters to the script.
In addition, View and Vendor forms are available to provide access to external databases in BMC
Remedy AR System forms.
Page 871 of 4705
Home
Having a third-party application write data to an AR System table is not supported. The AR System
server maintains the relationships among the tables in the AR System database. If a third-party
application attempts to add data and does not maintain these relationships, the entire database can
become corrupted.
Integrating the mid tier

The mid tier provides integration capabilities to interface with third-party products. Integration
provides the mid tier access to external data and third-party products can access AR System data
through the mid tier. BMC Remedy AR System allows applications to expose interfaces as web
services and it allows BMC Remedy AR System applications to consume external web services.
You can also use the data visualization field for external web content integration.
For more information, see the Integrating section.
Multiplatform issues
A major consideration for every integration implementation is the range of platforms that are
involved.
BMC Remedy AR System clients are available for Windows and on all major platforms through the
Web using the mid tier. In some cases, integration at the client level is unique for the different
platforms.
The BMC Remedy AR System workflow qualifications include functions to test for the different
platforms.
Multiple workflow definitions can be triggered in parallel, and the one appropriate for the platform is
executed. In some cases, you can avoid the client functionality issue by running a process on the
server from client workflow. Because the application executes on the AR System server's platform
and operating system, it does not matter which client platform triggered the workflow.
Similarly, different AR System server platforms might require adjustments to integration
implementations.
Choosing an implementation method

The following section outlines some methods by which you can implement integration with BMC
Remedy AR System.
How quickly do you want to have the integration working?
Some options are easy to get running for demonstration purposes, but have drawbacks for
production deployment. The more complex the integration, the more time is required to
implement it.
Page 872 of 4705
Home
How "robust" does the integration need to be? How heavy will the usage be, and are there
any data throughput requirements?
For an integration that will be used infrequently, some of the methods are simple to
implement. If the integration involves moving a large amount of information, other methods
might require more effort but produce better results.
Will users be able to modify the integration? How will it be supported?
Some of the methods do not lend themselves to user modification. Others are easily
modifiable, but might be more difficult to support if changes are made.
Integration technologies
A basic design philosophy of BMC Remedy AR System is that it is almost always used in
conjunction with other tools and products to create an integrated solution. BMC Remedy AR
System is designed to have many integration points, making it easy to combine with your other
solutions.
This table lists the technologies available for integrating with BMC Remedy AR System:
Method
Description
Section or topic
C API (
Application
The AR System API on the server is the most technically complex method. It requires
knowledge of C programming and building executables. However, it provides access to all
BMC Remedy AR
System C API
Programming
Interface)
AR System server functionality for tightly linked, high-performance integration.
overview
Java API
The AR System Java API is a collection of Java classes that provide AR System C API
functionality in a Java development environment. Using this abstraction layer allows
BMC Remedy AR
System Java API
developers to quickly build enhanced applications for the web.
overview
This integration technology (XML, WSDL, UDDI, and SOAP) allows you to build
distributed applications without programming:
Publishing the
BMC Remedy AR
Web Services
Use the Set Fields workflow action and a Web Services object to "consume"
third-party web services in AR System applications.
System
functionality as a
web service
Use BMC Remedy AR System to create and "publish" a Web Services object.
BMC Remedy
AR System
Plug-Ins
AR System clients perform data operations on external systems through the AR System
server, plug-in service, and plug-in related APIs. The plug-in service extends the AR
System server to integrate with external data sources. The AR System server connects to
the plug-in service, which activates the proper plug-in when a transaction is made.
Enabling Plug-ins
Data
Visualization
Field
The data visualization field provides a framework and services for mid tier-based graphing
solutions. It provides an efficient way to add graphical elements (such as BMC Remedy
Flashboards) to AR System forms.
Data visualization
fields
AREA Plug-Ins
(BMC Remedy
AR System
External
Authentication)
BMC Remedy provides a special API that allows user logins to be validated from a data
source outside the AR System database. This API is called the AR System External
Authentication (AREA) API.
AREA plug-ins
introduction and
Installing sample
AREA
implementations
Filter API
Plug-Ins
The filter API enables you to use filters to permit other applications to make calls back into
Integration
considerations
Page 873 of 4705
Home
Method
Description
Section or topic
ARDBC
Plug-Ins (BMC
Remedy AR
System
Database
Connectivity)
AR System Database Connectivity enables you to access and manipulate data that is not
stored in BMC Remedy AR System.
Using the ARDBC API, you can create plug-ins used by AR System server to manage
data. These plug-ins are loaded at run time and implement calls that are analogous to the
set, get, create, delete, and get-list API calls for entries in a form.
AR filter API
plug-ins
introduction
Vendor Forms
Vendor forms allow BMC Remedy AR System to present data from external sources as
entries in an AR System form. Vendor forms require you to have an ARDBC plug-in
installed and configured.
Vendor forms
introduction
View Forms
View forms allow direct read-and-write access to data in database tables that are not
owned by BMC Remedy AR System. This allows direct access to these tables, as if they
were owned by BMC Remedy AR System, without programming, database replication, or
synchronization.
View forms
introduction
SQL Database
Access
Third-party tools with appropriate permissions can access any information in the AR
System database. In addition, AR System workflow can query other databases.
SQL database
access
ODBC Access
ODBC (Open DataBase Connectivity) is a standard database access method developed

by Microsoft. Using the ODBC driver, any client capable of accessing ODBC can have
read-only access to AR System forms. Reporting is a common use of ODBC.
ODBC database
access
introduction
BMC Atrium
Integration
Engine (AIE)
The BMC Atrium Integration Engine mediates between the AR System server and vendor
applications such as SAP, Oracle, and other applications and databases for which
Integration
considerations
Command Line
Interface (CLI)
A Command Line Interface (CLI) is available with most AR System clients. This enables a
client to be started and passed a set of parameters so that either it is in a specific state
and displays information or it completes a process and exits with no user interface
displayed.
Integration
considerations
XML Import and

Export
BMC Remedy AR System can export and import object definitions in XML.
Importing object
AR System clients can convert AR System objects to XML and vice versa without making
calls to the AR System server.
definitions and
Exporting objects
When the server exports the file in XML format, it adds a header required to make it a
valid XML document. This same header is required for the server to import an XML file
and data to XML

format
adapters are developed. Adapters can come from BMC Remedy, from partners, or from
customers.
correctly. Otherwise, the file is assumed to be in the standard AR System definition format
.
Running
External
Applications (
Run Process)
One of the actions available in AR System workflow is the Run Process action. BMC
Remedy AR System can use the command line interfaces of other applications to start
those applications and pass them initial data.
In some cases, the third-party application is simply started, while in others BMC Remedy
AR System waits for a response.
Running external
processes
introduction
SNMP
You can use SNMP to manage complex networks through SNMP-compliant management
consoles and monitor network devices.
BMC Remedy
SNMP Agent
configuration
Licensing
Applications
Authorized integration system vendors (ISVs) can make their applications licensable at the
application and user levels.
Making
applications
licensable for
integration
system vendors
Page 874 of 4705
Home
Enabling plug-ins
BMC Remedy AR System plug-ins enable you to extend AR System server functionality to external
data (data not contained in the AR System database). This section describes each type of AR
System plug-in and provides general information about plug-ins.
Note
To extend client functionality, you use the AR System C API or Java API. See Integration
considerations and Creating and executing BMC Remedy AR System C API programs .

AR System plug-ins introduction
Plug-in types supported by BMC Remedy AR System
AR Filter API plug-ins introduction
AREA plug-ins introduction
ARDBC plug-ins introduction
Installed plug-in components
Creating C plug-ins
C plug-in naming conventions
Configuring the Java plug-in server
Creating Java plug-ins
Configuring the AR System server to access a plug-in server
Running the plug-in server
Common plug-in C functions and Java methods
Opening Knowledge Management System Configuration form
AR System plug-ins introduction

The AR System plug-in server allows integration between BMC Remedy AR System and external
programs or environments by managing the interaction between the plug-in code and the AR
System server. All plug-ins are registered with the plug-in server, which runs them as needed and
coordinates all interaction.
A plug-in is defined by using one of the plug-in APIs to write code to handle the integration with the
external program. Plug-in API functions provide the main routine, threading control, and
communication with the AR System server. The plug-in application that you write provides the logic
for one or more callback routines, defined by the API, that perform operations against the external
program or environment.
When a plug-in function is invoked, the AR System server makes a call to the plug-in server,
Page 875 of 4705
Home
requesting a specific plug-in to perform an operation with a set of parameters. The plug-in server
passes the parameters to the appropriate callback routine in the external application and awaits the
response. When the response is received, it is returned to BMC Remedy AR System and
processing continues.
Plug-in types supported by BMC Remedy AR System

BMC Remedy AR System supports the following types of plug-ins that you create:
AR System External Authentication (AREA)
AR System uses AREA plug-ins to authenticate the identity of users. AREA plug-ins access
network directory services or other authentication services to verify user login names and
passwords. When you use an AREA plug-in, you do not have to maintain duplicate user
authentication data in the BMC Remedy AR System directories because the AR System
server can access user identification information from external sources.
Notes
If you have users with fixed licenses or users who use BMC Remedy
applications, you must maintain user authentication data in AR System
directories because users must exist in the User form for the license tracking
feature and for the applications.
See AREA plug-ins introduction. A ready-to-use Atrium SSO plug-in is
available for the purpose of single sign-on. This plug-in is used for
integrating the AR System server and the Atrium SSO server and
authenticates the user against the Atrium SSO server by calling the Atrium
SSO APIs. For more information, see Configuring BMC Atrium SSO
integration.
AR System Database Connectivity (ARDBC)

ARDBC plug-ins enable BMC Remedy AR System to access data stored in external sources.
You can integrate ARDBC with the external data sources through their own APIs. ARDBC
plug-ins, which you access through vendor forms, enable you to perform these tasks:
Search external data sources
Create, delete, modify, and set entries in external data sources
Populate search-style character menus from external data sources
Implement workflow that accesses external data sources
See ARDBC plug-ins introduction.
AR System Filter (AR Filter)
AR filter API plug-ins are used when server-side workflow objects, such as filters and
escalations, reference filter API calls. AR filter API plug-ins offer an alternative method to
send information requests to and from external servers. In previous versions of BMC
Page 876 of 4705
Home
Remedy AR System, run processes performed external information requests. AR Filter uses
fewer system resources than run processes use and enables the AR System server to return
to its workflow faster.
See AR filter API plug-ins introduction.
Note
BMC Remedy AR System also offers two ready-to-use Lightweight Directory
Access Protocol (LDAP) plug-ins that you access through Developer Studio. See
Integration considerations.
Installed plug-in components shows how the AR System server calls the plug-in server that
calls the plug-in.
AR System plug-in architecture
Page 877 of 4705
Home
Note
The arrows in this figure identify the directions in which each program or process
can initiate API function calls. Data can flow in any direction.

AR System Filter (AR Filter) API plug-ins enable you to create tight, efficient integrations between
your systems and the AR System server. They are triggered with Set Field actions in filters and
escalations. Because this middleware is loaded as a plug-in when BMC Remedy AR System is
started instead of as a stand-alone executable at each event, it consumes fewer resources and less
processor time than a Set Fields $PROCESS$ action.
You use Developer Studio to create AR Filter Set Field actions in filters and escalations.
At run time, the AR System server sends AR Filter API requests to the plug-in, which directs the
requests to the appropriate plug-in. The plug-in processes the input arguments and can return
values that can be used in the Set Fields action.
When you enter AR Filter API requests in the Create Filter form, the AR System server sends the
requests to the plug-in, which sends them to AR Filter. AR Filter either processes the data or
request itself or retrieves output data from the external data source and returns it in the opposite
direction.
Unlike AREA plug-ins, multiple AR Filter API plug-ins can be loaded simultaneously by the plug-in
server.
The following figure shows the flow of requests and information for AR Filter API plug-ins.
Flow of requests and information for the AR Filter API plug-in
Page 878 of 4705
Home

AR Filter API plug-in Java methods
AR Filter API plug-in C function
AR Filter API plug-ins configuration
AR Filter API plug-in Java methods

The methods defined in the ARFilterAPIPluggable interface and the ARFilterAPIPlugin abstract
class are common to all plug-in types. For more information, see the Java plug-in API online
documentation located at ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdoc
VerNum.jar. ( VerNum represents the release version number.)
AR Filter API plug-in C function

The AR Filter API plug-in API has one function, ARFilterApiCall. For more information, see
ARFilterApiCall.
The AR Filter API plug-in function is a blocking call, so the AR System server thread that makes the
call waits for the plug-in to respond. For best performance, the plug-in should return quickly. Tell
your plug-in installers about the expected latency, and have them set their
AR_SERVER_INFO_FILTER_TIMEOUT value accordingly.
The following example files, which can be used to create an AR Filter API DLL or shared library,
are located in the ARSystemServerInstallDir/Arserver/Api/arfilterapi/example directory:
arfilterapisamp.c
arfilterapisamp.dep
arfilterapisamp.vcproj
arfilterapisamp.mak
Page 879 of 4705
Home
AR Filter API plug-ins configuration

AR System Filter (AR Filter) API plug-ins enable you to create tight and efficient integrations
between your systems and the AR System server.
The configuration information for the AR Filter API plug-ins is available in the following configuration
files:
<ARInstallationFolder>\pluginsvr\pluginsvr_config.xml
(Windows) <ARInstallationFolder>\conf\ar.cfg
(UNIX) <ARInstallationFolder>/conf/ar.conf
Log file configuration is available in the <ARInstallationFolder>\pluginsvr\log4j_pluginsvr.xml
file. For information about how to configure a server to use plug-ins, see Configuring a server to
use plug-ins.
Use the configuration files to:
Configure a plug-in server and port
Enable plug-in logging
Troubleshoot plug-in issues
The following topics describe the configuration information of the AR Filter API plug-ins.
AR Alert plug-in configuration
AR Registry plug-in configuration
CAI plug-in configuration
CAI RESTful plug-in configuration
Charge-back plug-in configuration
Docs Migration plug-in configuration
File System Sync plug-in configuration
Form Permissions plug-in configuration
FTS plug-in configuration
ITSM Util plug-in configuration
Log Level Change plug-in configuration
NextId plug-in configuration
Registration plug-in configuration
Rule Engine plug-in configuration
SDG plug-in configuration
Twitter Alert Notification plug-in configuration
Twitter User Registration plug-in configuration
Update KAM Mapping plug-in configuration
Web Service plug-in configuration
Page 880 of 4705
Home
Related topics
Troubleshooting issues with AR System Filter API plug-ins
AR Alert plug-in configuration

The AR Alert plug-in provides a way to send notifications to web services external to BMC Remedy
AR System.
BMC Remedy Alert is one of the notification mechanisms provided by the AR System server to
send notifications (alerts) to a registered group of users or individual users. The AR Alert plug-in
extends this functionality to send notifications to web services by using SOAP (Simple Object
Access protocol). To enable users to receive alert notifications on external web
services, you need to register the users using the AR System Alert Registration form.
Use the AR System Alert Registration form to:
Receive alerts through web services.
Send alerts to multiple web services.
Determine whether a specific alert mechanism was successful in sending an alert.
Plug-in type
AR Alert is a Java-based Filter API plug-in.
AR System server connectivity

The AR System server interacts with the AR Alert plug-in when an event occurs on the AR System
Alert Registration form. The AR Alert plug-in ( websvcalrtjavaVerNum.jar VerNum represents
the release version number) is installed in the <ARInstallationFolder>\pluginsvr folder.
Configuration information
The configuration information of the AR Alert plug-in is available in the <ARInstallationFolder>\
pluginsvr\pluginsvr_config.xml file that contains the plug-in details in XML code as follows:
<plugin>
<name>ARSYS.ALRT.WEBSERVICE</name>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem/pluginsvr/
websvcalrtjava81_build001.jar</pathelement>
<classname>com.bmc.arsys.ws.alert.ARAlertPlugin</classname>
websvcalrtjava81_build001.jar</pathelement>
</plugin>
Page 881 of 4705
Home
The ar.cfg/ar.conf file contains the Server-Plugin-Alias setting that points to the correct plug-in
server alias:
Server-Plugin-Alias: ARSYS.ALRT.WEBSERVICE ARSYS.ALRT.WEBSERVICE HOST:
9999
Related topic
Registering users for alerts
Troubleshooting AR Alert plug-in issues
AR Registry plug-in configuration

After you publish a web service, you need to find the web service. Use the AR Registry plug-ins to
register, modify, and unregister web services.
Plug-in type
ARSYS.ARF.REGISTRY is a Java-based AR Filter API plug-in.
ARSYS.ARDBC.REGISTRY is a Java-based ARDBC plug-in.

The AR System server interacts with the AR Registry plug-in when an event occurs on the AR
System Web Services Registry form. The AR Registry plug-ins are installed in the <
ARInstallationFolder>\pluginsvr folder.
The configuration information of the AR Registry plug-ins is available in the <ARInstallationFolder
>\pluginsvr\pluginsvr_config.xml file that includes the plug-in details in XML code as follows:
<plugin>
<name>ARSYS.ARF.REGISTRY</name>
arregistryplugin81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.registry.ARRegistryPlugin</classname>
WSRegistryAPI8.1.jar</pathelement>
activation.jar</pathelement>
tibco-uddi-client3.0.jar</pathelement>
</plugin>
<plugin>
<name>ARSYS.ARDBC.REGISTRY</name>
arregistryquery81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.registry.ARDBCRegistryQuery</classname>
Page 882 of 4705
Home

activation.jar</pathelement>
tibco-uddi-client3.0.jar</pathelement>
</plugin>
The ar.cfg/ar.conf file includes the Server-Plugin-Alias setting that points to the correct plug-in
server alias:
Server-Plugin-Alias: ARSYS.ARF.REGISTRY ARSYS.ARF.REGISTRY HOST:9999
Server-Plugin-Alias: ARSYS.ARDBC.REGISTRY ARSYS.ARDBC.REGISTRY HOST:9999
Related topics
Troubleshooting AR Registry plug-in issues
Registering, modifying, and de-registering web services
CAI plug-in configuration

The Command Automation Interface (CAI) plug-in is used to create, update, and receive data from
other back-office applications. The CAI plug-in provides dynamic data-mapping mechanism
because you cannot use workflow to push values to dynamic fields. The CAI plug-in also helps to
address issues caused by incompatible permission models. The CAI plug-in is used within BMC
Service Request Management to process variables that are used during processing of submitted
service requests. The CAI plug-in also helps you move data between different sources and
destinations. The CAI plug-in enables bidirectional communication with external applications and
delivers command events, depending on the protocol used.
For more information, see the Integrating BMC Service Request Management with Third-Party
Applications white paper.
Plug-in type
CAI is a Java-based Filter API plug-in.

The CAI plug-in connects to the AR System server by using the CAI Events process. The CAI
plug-in (CAIPlugin.jar) is installed in the <ARInstallationFolder>\pluginsvr\cai folder.
The CAI plug-in receives its configuration information from the following locations:
CAI Application Registry form that defines the integrating applications, interface forms, logon
information, and the plug-in location: local or remote
CAI Plug-in Registry that enables you to define a private server queue to be used for CAI AR
System server API calls
ar.cfg/ar.conf file that has the configuration to reference the private server queue defined in
the CAI Plug-in Registry
Page 883 of 4705
Home
The configuration information of the CAI plug-in is available in the <ARInstallationFolder>\

pluginsvr\pluginsvr_config.xml file that includes the plug-in details in XML code as follows:
<plugin>
<name>REMEDY.ARF.CAI</name>
<type>FilterAPI</type>
<code>JAVA</code>
<filename/>
<classname>com.bmc.itsm.cai.filterapi.cai.CAIFilterPlugin</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\cai\CAIPlugin.jar</
pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\foundation_shared\
ITSMCommonUtils.jar</pathelement>
<pathelement type="path">C:\BMC Software\ARSystem\pluginsvr\cai</pathelement>
<userDefined>
<server_name>myServer</server_name>
<server_port>0</server_port>
<max_params_retries>300</max_params_retries>
<params_retry_interval>100</params_retry_interval>
</userDefined>
</plugin>
server alias:
Server-Plugin-Alias: REMEDY.ARF.CAI REMEDY.ARF.CAI myServer:9999
Related topic
Troubleshooting CAI plug-in issues
CAI RESTful plug-in configuration

The CAI RESTful plug-in establishes communication between the Change Management application
and BMC ProactiveNet Performance Management Server. It gets data from CAI and pushes data to
a RESTful web service exposed by BMC ProactiveNet Performance Management. This plug-in
refers to the configuration data for communicating with RESTful web services.
Plug-in type
CAI RESTful is a Java-based Filter API plug-in.

The AR System server interacts with the CAI RESTful plug-in by using the BMC Remedy AR
System Java APIs. This plug-in ( cai-restful-plugin.jar) is installed in the <ARInstallationFolder>\
pluginsvr\cairestful folder.
The configuration information of the CAI RESTful plug-in is available in the <ARInstallationFolder
Page 884 of 4705
Home
<name>RMDY.CAI.RESTFUL.CLIENT.FILTER.PLUGIN</name>
<code>JAVA</code>
<filename>C:\Program Files\BMC Software\ARSystem\pluginsvr\cairestful\
cai-restful-plugin.jar</filename>
<classname>
com.bmc.remedy.cai.restful.plugin.CAIRestfulFilterPlugin</classname>
<pathelement type="location">C:\Program Files\BMC Software\ARSystem\pluginsvr\cairestful
\cai-restful-plugin.jar</pathelement>
<pathelement type="location">C:\Program Files\BMC Software\ARSystem\pluginsvr\
<pathelement type="location">C:\Program Files\BMC Software\ARSystem\pluginsvr\json.jar</
pathelement>
<userDefined>
</userDefined>
</plugin>
server alias. For example:
Server-Plugin-Alias: RMDY.CAI.RESTFUL.CLIENT.FILTER.PLUGIN
RMDY.CAI.RESTFUL.CLIENT.FILTER.PLUGIN myServer:9999
Related topic
Troubleshooting CAI RESTful plug-in issues
Charge-back plug-in configuration

BMC Asset Management uses the Cost module to track costs associated with configuration items (
CIs). This integration uses the common cost creation dialog box that is provided by the Cost
module. The fields on the CI user interface forms integrate with BMC Asset Management forms to
show cost data related with a CI.
BMC Asset Management also uses the charge-back functionality in the Cost module. Charge-backs
are roll-ups of costs that are incurred over a period and involved in the various cost centers in a
company. The charge-back component of the Cost module generates charge-back entries, enables
the financial manager to make appropriate adjustments to the costs, and generates invoices to be
sent to the individual cost centers.
Plug-in type
Charge-back is a Java-based Filter API plug-in.

The Charge-back plug-in connects to the AR System server by using the BMC Remedy AR System
Java API. The plug-in (chargebacks.jar) is installed in the <ARInstallationFolder>\pluginsvr\chb
folder.
Page 885 of 4705
Home
The configuration information of the Charge-back plug-in is available in the <ARInstallationFolder
<plugin>
<name>REMEDY.ARF.CBDATA</name>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\chb\chargebacks.jar</filename>
<classname>com.bmc.itsm.chargeback.filterapi.chargeback.ChargeBackFilterAPI</
classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\chb\chargebacks.jar<
/pathelement>
<userDefined>
</userDefined>
</plugin>
Server-Plugin-Alias: REMEDY.ARF.CBDATA REMEDY.ARF.CBDATA myServer:9999
Related topic
Troubleshooting Charge-back plug-in issues
Docs Migration plug-in configuration

The Docs Migration plug-in converts an old Remedy Knowledge Management (RKM) System (7.1/
7.2/7.5 non-AR System based) article to a BMC Remedy AR System-based RKM article.
Plug-in type
Docs Migration is a Java-based Filter API plug-in.

The Docs Migration plug-in connects to the AR System server by using the BMC Remedy AR
System Java API. The Docs Migration plug-in ( rkm-docs-migrator.jar) is installed in the C:\BMC
Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
When the Docs Migration plug-in is running, you must copy the data folder from the old RKM
system to the AR System server and provide the absolute folder path during conversion.
Page 886 of 4705
Home
The configuration information of the Docs Migration plug-in is available in the <
ARInstallationFolder>\pluginsvr\pluginsvr_config.xml file that includes the plug-in details in
XML code as follows:
<plugin>
<name>RMDY.ITSM.RKM.DOCSMIGRATION</name>
<code>JAVA</code>
<filename>C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins\
rkm-docs-migrator.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.docsmigrator.MigratorPlugin</classname>
<pathelement type="location">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\
plugins\3rd_party\commons-io-1.4.jar</pathelement>
plugins\3rd_party\dom4j-1.6.1.jar</pathelement>
plugins\rkm-common.jar</pathelement>
plugins\3rd_party\jconn2-2.0.jar</pathelement>
plugins\3rd_party\ojdbc14-10.1.0.4.0.jar</pathelement>
plugins\3rd_party\sqljdbc-1.1.1501.jar</pathelement>
plugins\3rd_party\mysql-connector-java-5.1.16-bin.jar</pathelement>
<pathelement type="path">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins<
/pathelement>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RKM.DOCSMIGRATION
RMDY.ITSM.RKM.DOCSMIGRATION myServer:9999
The log4j_pluginsvr.xml file contains the plug-in log level information. For example:
<logger additivity="true" name="com.bmc.itsm.rkm">

<level value="warn"/>
</logger>
Related topic
Troubleshooting Docs Migration plug-in issues
Page 887 of 4705
Home
File System Sync plug-in configuration

The File System Sync plug-in synchronizes files that were modified or added since the last sync
with the RKM:KnowledgeArticleManager form. A BMC Remedy AR System escalation calls this
plug-in and passes the latest sync time.
Plug-in type
File System Sync is a Java-based Filter API plug-in.

The File System Sync plug-in connects to the AR System server when an escalation occurs at a
given interval. The File System Sync plug-in ( file-system-sync.jar) is installed in the C:\BMC
Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the File System Sync plug-in is available in the <
<plugin>
<name>RMDY.ITSM.RKM.FS.KAM.SYNC</name>
<code>JAVA</code>
file-system-sync.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.kamfilesystemsync.RkmFileSystemKamSyncPlugin</
classname>
<pathelement type="path">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins
</pathelement>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RKM.FS.KAM.SYNC RMDY.ITSM.RKM.FS.KAM.SYNC
myServer:9999
The log4j_pluginsvr.xml file contains the plug-in log level information:

</logger>
Page 888 of 4705
Home
Related topic
Troubleshooting File System Sync plug-in issues
Form Permissions plug-in configuration

The Form Permissions plug-in is used when you register the BMC Remedy AR System form as a
knowledge base item. This plug-in is called when you open the Accessibility screen of the
Knowledge Registration Wizard. This plug-in also extracts the permissions that are assigned to the
AR System form by using the BMC Remedy AR System API and adds this information to the RKM:
SourceFormPermissions_Temp form.
Plug-in type
Form Permissions is a Java-based Filter API plug-in.

The Form Permissions plug-in connects to the AR System server by using the BMC Remedy AR
System Java API. The Form Permissions plug-in ( rkm-form-permissions.jar) is installed in the C:\
BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the Form Permissions plug-in is available in the <
<plugin>
<name>RMDY.ITSM.RKM.FORMPERMISSIONS</name>
<code>JAVA</code>
rkm-form-permissions.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.formpermissions.Permissions</classname>
plugins\rkm-form-permissions.jar</pathelement>
</pathelement>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RKM.FORMPERMISSIONS
RMDY.ITSM.RKM.FORMPERMISSIONS myServer:9999
Page 889 of 4705
Home

</logger>
Related topic
Troubleshooting Form Permissions plug-in issues
FTS plug-in configuration

The FTS plug-in is used to create and maintain Full Text Search indexes, which is a feature of AR
System server. The FTS plug-in provides row-level and field-level security for indexed data during
searches.
The FTS plug-in supports the multiform search used by applications such as BMC Remedy
Knowledge Management (RKM). The multiform search uses a vendor form that displays an
interface through which an application customizes the search to suit its requirements. The search
can contain a request to return a specific list of fields, how the filters are returned, or terms that may
or may not be available in the document, and so on. It also permits you to specify the forms to
search. You can also tailor the search to target just the indexed data rather than all data.
Plug-in type
FTS is a Java-based Filter API plug-in.

The FTS plug-in interacts with the AR System server through the BMC Remedy AR System Java
API. The plug-in (ftspluginVerNum.jar VerNum represents the release version number) is
installed in the <ARInstallationFolder>\pluginsvr\fts folder.
The FTS plug-in is installed during the AR System installation and is hosted with the standard AR
Java plug-in server. Each instance of the AR Java plug-in server is permitted to run only one
instance of the FTS plug-in. By default, the FTS plug-in runs on port 9998. If you want to change
the plug-in port value, you must change the default port number in both ar.cfg/ar.conf and
pluginsvr_config.xml files.
In a single-server installation, ensure that the collection directory is on the same computer as the
server. In a server group, ensure that all the FTS plug-in instances always point to the same
collection directory. To ensure high performance in a server group, all instances of the FTS plug-ins
must be running on a single server with the collection directory on the same computer as the server
. For information about configuring FTS, see the following topics:
Configuring full text search
Page 890 of 4705
Home
The configuration information of the FTS plug-in is available in the <ARInstallationFolder>\

<pluginsvr_config>
<port>9998</port>
<regPortMapper>false</regPortMapper>
<encryptionPolicy>2</encryptionPolicy>
<publicKeyAlg>4</publicKeyAlg>
<publicKeyExpiry>86400</publicKeyExpiry>
<dataEncryptionAlg>1</dataEncryptionAlg>
<dataKeyExpiry>2700</dataKeyExpiry>
<numCoreThreads>5</numCoreThreads>
<numSelectorThreads>2</numSelectorThreads>
<workQueueMonitorLogInterval>0</workQueueMonitorLogInterval>
<workQueueTaskThreshold>5</workQueueTaskThreshold>
<plugins>
<plugin>
<name>ARSYS.ARF.FTS</name>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem/pluginsvr/fts/
ftsplugin80_build001.jar</pathelement>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem/pluginsvr/fts/
tika-app-0.6.jar</pathelement>
<classname>com.bmc.arsys.plugins.ftsplugin.FTSPlugin</classname>
<userDefined>
<ftCollectionDir>C:/Program Files/BMC Software/ARSystem/ftsconfiguration/collection<
/ftCollectionDir>
<ftConfigDir>C:/Program Files/BMC Software/ARSystem/ftsconfiguration/conf</
ftConfigDir>
<ftCaseSensitivity>false</ftCaseSensitivity>
<ftStopFile>C:/Program Files/BMC Software/ARSystem/ftsconfiguration/conf/arsfts.stp<
/ftStopFile>
<ftLangCode>en</ftLangCode>
<ftSearchThreshold>1000000</ftSearchThreshold>
</userDefined>
</plugin>
</plugins>
</pluginsvr_config>
server alias:
Server-Plugin-Alias: ARSYS.ARF.FTS ARSYS.ARF.FTS myServer:9998
The FTS plug-in is launched from the armonitor.cfg file located in the <ARInstallationFolder>\
conf folder. You can look for the following entry in the armonitor.cfg file by searching for the line
that includes the fts directory:
"C:\Program Files\Java\jre6\bin\java" -Xmx512m -Djava.net.preferIPv4Stack=true Djava.net.preferIPv6Addresses=false -classpath "C:\Program Files\BMC Software\ARSystem\

pluginsvr\fts;C:\Program Files\BMC Software\ARSystem\pluginsvr;C:\Program Files\BMC
Software\ARSystem\pluginsvr\arpluginsvr80_build001.jar"
Page 891 of 4705
Home
com.bmc.arsys.pluginsvr.ARPluginServerMain -x vw-sjc-bsm-dv12 -i "C:\Program Files\BMC

Software\ARSystem" -m
Related topic
Troubleshooting FTS plug-in issues
ITSM Util plug-in configuration

The ITSM Util plug-in is used to set the Knowledge Article field as an input parameter. This
plug-in is also used to create or delete an approval filter when a user defines a custom approval
chain.
Plug-in type
ITSM Util is a Java-based Filter API plug-in.

The ITSM Util plug-in connects to the AR System server when a workflow executes a filter.
This plug-in (ITSMUtil.jar) is installed in the <ARInstallationFolder>\pluginsvr\itsmutil folder.
The configuration information of the ITSM Util plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>REMEDY.ARF.ITSMUtil</name>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\itsmutil\ITSMUtil.jar</filename>
<classname>com.bmc.itsm.util.ITSMUtilPlugin</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\log4j-1.2.14.jar</
pathelement>
</plugin>
Server-Plugin-Alias: REMEDY.ARF.ITSMUtil REMEDY.ARF.ITSMUtil myServer:
9999
Related topic
Troubleshooting ITSM Util plug-in issues
Log Level Change plug-in configuration

The Log Level Change plug-in is used to change the log levels of the Remedy Knowledge
Management (RKM) plug-ins. The Log Level Change plug-in is used when a user modifies the
RKM:SystemConfig form.
Page 892 of 4705
Home
Plug-in type
Log Level Change is a Java-based Filter API plug-in.

The Log Level Change plug-in connects to the AR System server when the Filter Modify Event
occurs on the RKM:SystemConfig form.
The configuration information of the Log Level Change plug-in is available in the <
<plugin>
<name>RMDY.ITSM.RKM.LOGLEVEL.CHANGE</name>
<code>JAVA</code>
itsm-plugin-log-level-change.jar</filename>
<classname>com.bmc.itsm.common.utils.pluginloglevelchange.PluginLogLevelChange</
classname>
<pathelement type="path">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins<
/pathelement>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RKM.LOGLEVEL.CHANGE
RMDY.ITSM.RKM.LOGLEVEL.CHANGE myServer:9999
Related topic
Troubleshooting Log Level Change plug-in issues
NextId plug-in configuration

The NextId plug-in is used to merge new IDs on a form. The NextId plug-in creates a new entry,
adds a request ID, and then merges this entry on a specified form with the merge type as
AR_MERGE_ENTRY_DUP_MERGE, which updates the fields specified in the field list in the existing
entry.
Plug-in type
NextId is a Java-based Filter API plug-in.
Page 893 of 4705
Home

The NextId plug-in connects to the AR System server when an event occurs through a filter that is
related to this plug-in. The plug-in ( nextid.jar) is installed in the <ARInstallationFolder>\pluginsvr
\nid folder.
The configuration information of the NextID plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>NextId</name>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\nid\nextid.jar</filename>
<classname>com.bmc.itsm.nextid.filterapi.nextid.NextId</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\nid\nextid.jar</
pathelement>
</plugin>
Server-Plugin-Alias: NextId NextId myServer:9999
Related topic
Troubleshooting NextId plug-in issues
Registration plug-in configuration

The Registration plug-in provides the interface for the RKM user to register new knowledge sources
and to modify, remove, enable, and disable knowledge sources. Use the Registration Wizard to
select the knowledge source type that you want to modify. During the registration process, you can
select the following source types:
Searchable Item Register AR forms as knowledge sources that are searchable only. No
metadata or life cycle is saved or managed.
Knowledge Base Item Register external files or AR forms. Metadata is saved and
managed. Life cycle management is optional for AR forms.
Plug-in type
Registration is a Java-based Filter API plug-in.
Page 894 of 4705
Home

The Registration plug-in connects to the AR System server when a Filter API action or Service call
occurs. The Registration plug-in (rkm-registration.jar) is installed in the C:\BMC Software\
BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the Registration plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>RMDY.ITSM.RKM.REGISTRATION</name>
<code>JAVA</code>
rkm-registration.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.registration.RegistrationController</classname
>
<pathelement type="path">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\
plugins</pathelement>
</plugin>
server alias.
Server-Plugin-Alias: RMDY.ITSM.RKM.REGISTRATION
RMDY.ITSM.RKM.REGISTRATION myServer:9999
The log4j_pluginsvr.xml file contains the plug-in log level information.

</logger>
Related topic
Troubleshooting Registration plug-in issues
Page 895 of 4705
Home
Rule Engine plug-in configuration

The Rule Engine plug-in is a stand-alone BMC Remedy rules-driven engine with the Java engine
running in the back end. This plug-in provides the interface for defining and running rules, such as
getting data from a data source and updating or processing data in the data source. The Rule
Engine plug-in also facilitates asset management within the software license compliance
functionality.
Plug-in type
Rule Engine is a Java-based Filter API plug-in.

The Rule Engine plug-in connects to the AR System server when the user runs a job from the
Manage License Job form. The Rule Engine plug-in ( rle.jar) is installed in the <
ARInstallationFolder>\pluginsvr\rle folder.
The configuration information of the Rule Engine plug-in is available in the <ARInstallationFolder>
\pluginsvr\pluginsvr_config.xml file that includes the plug-in details in XML code as follows:
<plugin>
<name>RMDY.ITSM.RLE</name>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\rle\rle.jar</filename>
<classname>com.bmc.itsm.rle.RuleEngineFilterAPI</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\rle\lib\
JbcParser.jar</pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\rle\lib\cmdbapi77.
jar</pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\rle\lib\
aspectjrt.jar</pathelement>
<pathelement type="path">C:\BMC Software\ARSystem\pluginsvr\rle</pathelement>
<userDefined>
</userDefined>
</plugin>
Server-Plugin-Alias: RMDY.ITSM.RLE RMDY.ITSM.RLE myServer:9999
Related topic
Troubleshooting Rule Engine plug-in issues
Page 896 of 4705
Home
Adding a private queue port number for Software License Management

The Spreadsheet Data Generator (SDG) plug-in looks up the BMC Remedy AR System forms,
fields, and conditional dependency of fields and retrieves the field properties, such as the help text,
length, and label of these fields. The SDG plug-in then generates columns for each field in a
Microsoft Excel spreadsheet. The SDG plug-in reformats the data to the correct set, and eliminates
the possibility of data mismatch by generating spreadsheets directly from the AR System forms.
Plug-in type
SDG is a Java-based Filter API plug-in.

The AR System server interacts with the SDG plug-in when a filter API action occurs or a service is
executed on a BMC Remedy AR System form. The SDG plug-in is installed in the <
ARInstallationFolder>\pluginsvr\excelgenerator\lib\sdg.jar folder.

The configuration information of the SDG plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>ARSYS.ARF.SDG</name>
<code>JAVA</code>
<filename/>
<classname>com.bmc.arsys.plugins.sdg.StagingDataGenerator</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\excelgenerator\lib\
sdg.jar</pathelement>
arutil80_build001.jar</pathelement>
sdg.jar</pathelement>
commons-lang-2.2.jar</pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\excelgenerator\lib\dom4j
-1.6.1.jar</pathelement>
ooxml-schemas-1.0.jar</pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\excelgenerator\lib\poi-3
.5-FINAL-20090928.jar</pathelement>
poi-contrib-3.5-FINAL-20090928.jar</pathelement>
poi-ooxml-3.5-FINAL-20090928.jar</pathelement>
poi-scratchpad-3.5-FINAL-20090928.jar</pathelement>
Page 897 of 4705
Home

xmlbeans-2.3.0.jar</pathelement>
<pathelement type="path">C:\BMC Software\ARSystem\pluginsvr\excelgenerator\lib</
pathelement>
<userDefined>
<server_name>vw-pun-rem-dv37</server_name>
<max_params_retries>300</max_params_retries>
<params_retry_interval>100</params_retry_interval>
</userDefined>
</plugin>
server alias.
Server-Plugin-Alias: ARSYS.ARF.SDG ARSYS.ARF.SDG myServer:9999
The configuration data of knowledge sources is present in the following forms:
DMT:SpreadsheetColumnSelections
DMT:Spreadsheet
Related topic
Troubleshooting SDG plug-in issues
Twitter Alert Notification plug-in configuration

The Twitter Alert Notification plug-in provides a way to send an alert notification or a "tweet" to a
valid Twitter account.
BMC Remedy AR System permits you to send an alert notification to a valid Twitter account that is
registered with a given user. If an AR System user has already registered with a valid Twitter
Access Key and Token Secret and has set up Twitter as part of his alert notifications, this plug-in
helps send a tweet to the registered Twitter account when an Alert Notify action in a filter is called.
The following BMC Remedy AR System components are important in sending alert notifications:
AR System Alert Delivery Registration form Ensure that this form contains an entry for
Twitter with the plug-in name ARSYS.ALRT.TWITTER.
AR System Alert Twitter User Authorization form Use this form to map an AR System user
to a valid Twitter account. For more information about the registration process, see Twitter
User Registration plug-in configuration.
An AR Filter with Notify action to this AR System user invokes this plug-in to send a tweet.
Plug-in type
Twitter Alert Notification is a Java-based Filter API plug-in.
Page 898 of 4705
Home

The AR System server interacts with the Twitter Alert Notification plug-in when a filter makes a call
to send an alert by using the Notify action. The Twitter Alert Notification plug-in (aralerttwitter
VerNum.jar VerNum represents the version number of the release) is installed in the <
ARInstallationFolder>\pluginsvr folder.
The configuration information of the Twitter Alert Notification plug-in is available in the <
<plugin>
<name>ARSYS.ALRT.TWITTER</name>
aralerttwitter81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.alert.twitter.TwitterAlertDeliveryPlugin</classname>
</plugin>
The ar.cfg/ar.conf file includes the Server-Plugin-Alias setting, which points to the correct plug-in
server alias:
Server-Plugin-Alias: ARSYS.ALRT.TWITTER ARSYS.ALRT.TWITTER HOST:9999
Related topic
Troubleshooting Twitter plug-in issues
Twitter User Registration plug-in configuration

The Twitter User Registration plug-in provides a way to authorize a Twitter account and register a
mapping between BMC Remedy AR System user and Twitter user accounts.
BMC Remedy AR System permits you to send an alert notification to a valid Twitter account that is
registered with a given AR System user. A filter with Notify action can send only the given text as a
"tweet" to the specified user, if the AR user is authenticated in Twitter and is registered with Twitter
generated Access Key and Token Secret. This plug-in helps create the registration by means of a
form similar to AR System Alert Twitter User Authorization form. Use this form to:
Select an AR System user to register A browser asks you to provide valid Twitter
credentials. After authenticating the user, Twitter generates a unique PIN.
Enter the generated PIN and save this user so as to generate unique Access Key and Token
Secret. This entry is stored on the AR System Alert User Registration form.
Plug-in type
Twitter User Registration is a Java-based Filter API plug-in.
Page 899 of 4705
Home

The AR System server interacts with the Twitter User Registration plug-in when either of the
following events occurs:
An AR System user is selected to be registered with Twitter.
The user supplies a valid PIN and clicks Apply on the AR Alert Twitter User Authorization
form.
The Twitter user registration plug-in (aralerttwitterVerNum.jar VerNum represents the version
number of the release) is installed in the <ARInstallationFolder>\pluginsvr folder.
The configuration information of the Alert User Registration plug-in is available in the <
<name>ARSYS.ARF.TWITTER</name>
aralerttwitter81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.alert.twitter.TwitterAlertDeliveryPlugin</classname>
The ar.cfg/ar.conf file includes the Server-Plugin-Alias setting, which points to the correct plug-in
server alias.
Server-Plugin-Alias: ARSYS.ARF.TWITTER ARSYS.ARF.TWITTER HOST:9999
Related topic
Troubleshooting Twitter plug-in issues
Update KAM Mapping plug-in configuration

The Update KAM Mapping plug-in updates the Knowledge Article Manager (KAM) core fields (
Submit Date and Create Date) by using the Merge Entry call for the Unified Data Management (
UDM) use case, and also updates the KAM Mapping field.
Plug-in type
Update KAM Mapping is a Java-based Filter API plug-in.

The Update KAM Mapping plug-in connects to the AR System server by using the BMC Remedy
AR System Java API. The Update KAM Mapping plug-in ( rkm-operations.jar) is installed in the C:\
BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
Page 900 of 4705
Home
The configuration information of the Update KAM Mapping plug-in is available in the <
<plugin>
<name>RMDY.ITSM.RKM.UPDATEKAMMAPPINGS</name>
<code>JAVA</code>
rkm-operations.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.operations.UpdateKAMMappings</classname>
</pathelement>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RKM.UPDATEKAMMAPPINGS
RMDY.ITSM.RKM.UPDATEKAMMAPPINGS myServer:9999

</logger>
Related topic
Troubleshooting Update KAM Mapping plug-in issues
Web Service plug-in configuration

The Web Service plug-in provides a means to access external web services and obtain information
for use in a BMC Remedy AR System application. For more information, see Publishing the BMC
Remedy AR System functionality as a web service .
Plug-in type
Web Service is a Java-based AR Filter plug-in.
Page 901 of 4705
Home

The AR System server interacts with the Web Service plug-in by using the workflow filter's Set
Fields action. In the Set Fields action, you can configure Web Service as the source of data and
provide the WSDL URL for the web service that needs to be consumed. For more information, see
Creating a Set Fields web service filter action .
The Web Service plug-in (websvcjavaVerNum.jar VerNum represents the version number of
the release) is installed in the <ARInstallationFolder>\pluginsvr folder.
The configuration information of the Web Service plug-in is available in the <ARInstallationFolder
<plugin>
<plugin>
<name>ARSYS.ARF.WEBSERVICE</name>
<pathelement type="location">C:/BMC Software/ARSystem/pluginsvr/websvcjava81_
build001.jar</pathelement>
<classname>com.bmc.arsys.ws.plugin.WSPlugin</classname>
<userDefined>
<policyConfigDir>C:/BMC Software/ARSystem/pluginsvr</policyConfigDir>
<timeout>40</timeout>
</userDefined>
</plugin>
You can configure the timeout value for the Web Service plug-in. The final timeout value that is
considered is the minimum value of either the filter-api-timeout as defined in the ar.cfg/
ar.conf file or the timeout value as defined in the pluginsvr_config.xml file. The maximum value
for filter-api-timeout is 300 seconds.
server alias:
Server-Plugin-Alias: ARSYS.ARF.WEBSERVICE ARSYS.ARF.WEBSERVICE HOST:9999
Related topic
Troubleshooting Web Service plug-in issues
AREA plug-ins introduction

AR System External Authentication (AREA) provides a way to validate users by connecting BMC
Remedy AR System to a data source outside the AR System database. This can be done using the
AREA LDAP plug-in or by creating your own custom plug-in for authentication services such as
Kerberos. See Creating C plug-ins and AREA plug-in C API functions for details.
When users first log on to BMC Remedy AR System through a client or when a client issues an API
Page 902 of 4705
Home
call to BMC Remedy AR System, the AR System server verifies the user name and password.
If the server verifies that the user name and password are in the User form, it authenticates the
information and processes the login or API call.
If the user information is not in the User form or if the user password is blank in the User form, the
AR System server sends an authentication request to the plug-in server. The request passes from
the plug-in server through the AREA plug-in instance to the external authentication source. The
external authentication source sends authentication information back through the same path to the
AR System server.
Note
For the AR System server to use an AREA plug-in to authorize logins, the corresponding
entries in the User form must have blank passwords.
If the authentication source verifies that the user information is valid, the AR System server
processes the API call or allows the user to log in.
When the authentication information is not verified (that is, the information is incorrect, incomplete,
or cannot be found in the external data source), the AR System server returns an error message to
the client.
The plug-in can load only one AREA plug-in instance at a time. An AREA plug-in can be configured
to access one or more data sources.
AREA plug-ins can selectively override field values entered in the User form.
Note
The plug-in behavior depends on how you configure the plug-in, such as whether you
enable the Cross Reference Blank Password and the Authenticate Unregistered users
options.
External authentication architecture
Page 903 of 4705
Home
This section contains information on:

AREA plug-in C API functions
AREA plug-in Java API methods
Installing sample AREA implementations

These are the AREA plug-in API functions:
AREAFreeCallback
AREANeedToSyncCallback
AREAVerifyLoginCallback
For more information, see the BMC Remedy AR System C API functions .
Page 904 of 4705
Home
AREA plug-in Java API methods

The methods defined in the AREAPluggable interface and the AREAPlugin abstract class are
common to all plug-in types. For more information, see the Java plug-in API online documentation
located at ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
Installing sample AREA implementations

When you install BMC Remedy AR System, you can install a sample Java AREA LDAP
implementation, including an AREA LDAP plug-in. That plug-in provides you with an integration
point between BMC Remedy AR System and LDAP directory services.
You must create a custom plug-in to integrate BMC Remedy AR System with external
authentication services such as Kerberos. See Creating Java plug-ins and AREA plug-in Java API
methods for details.
Example flow of requests and data for an AREA plug-in
Page 905 of 4705
Home

AR System Database Connectivity (ARDBC) plug-ins provide access to data stored outside the AR
System database as if it were located in tables owned by BMC Remedy AR System. After an
ARDBC plug-in is installed, the AR System administrator can create a vendor form that references
the table and columns of the external data source. Views and workflow can then be built for vendor
forms just as if they were regular AR System forms. The source of data manipulated by the AR
System API client, such as the mid tier, is transparent to the user.
When users enter requests in the vendor form, the AR System server sends the requests to the
plug-in server, which sends the requests to the ARDBC plug-in instance. The plug-in retrieves the
data (if any) from the external data source and returns it in the opposite direction. The AR System
server maps the external data to fields in the vendor form, and the form displays the data. See
Page 906 of 4705
Home
Unlike AREA plug-ins, multiple ARDBC plug-ins can be loaded simultaneously by the plug-in server
.
The following figure shows the flow of requests and information for an ARDBC plug-in.
Flow of requests and information for the ARDBC plug-in

Calling AR System API from an ARDBC plug-in
ARDBC plug-in C API functions
Creating a vendor form for an ARDBC plug-in
ARDBC plug-in Java API methods
ARDBC plug-ins configuration
Calling AR System API from an ARDBC plug-in

You can make AR System C API calls to the AR System server with a C ARDBC plug-in. In pre-7.0
versions of BMC Remedy AR System, such calls had to be made with a known user account. Now,
you can make the calls as the same user whose operation led to the ARDBC plug-in call. This
ensures that any call from the ARDBC plug-in has the same permissions as the user who called the
ARDBC plug-in.
When a plug-in call is made, AR System server creates a globally unique ID (GUID) to identify the
Page 907 of 4705
Home
user instance calling the plug-in. The plug-in provides callback routines to fetch the user name,
authentication string, and GUID. Subsequently, when a plug-in makes an API call, it uses those
callback routines to fetch the information it needs to authenticate itself as the user that made the
original call to the plug-in.
The calling plug-in uses the following API calls to set the callback routines for the API to fetch the
user name, authentication string, and authenticating GUID:
ARSetUserNameSource
ARSetAuthStringSource
ARSetNativeAuthenticationSource
Pointers to the callback routines are made available to the plug-ins as members of a properties list (
ARPropList) passed as an argument to ARDBCPluginSetProperties (if implemented by the
plug-in) when the plug-in is loaded. The plug-in must save these pointers and use them later as
arguments to API calls. These API calls must be made immediately after the
ARIntitialization call before any other API calls.
Note
When using the GUID authentication feature from a plug-in, internal users (such as
ESCALATOR and ARCHIVE) encounter errors. The errors occur because these users are
not valid users for making API calls.
For more information, see AR System plug-in API functions.

A Java ARDBC plug-in can make AR System Java API calls to the AR System server. Use the
ARPluginContext object to create a ARServerUser object. See the Java plug-in server API
online documentation located at ARSystemServerInstallDir\ARserver\api\javaplugins\
arpluginsdocVerNum.jar.
ARDBC plug-in C API functions

An ARDBC plug-in API enables BMC Remedy AR System to:
Implement calls on an external data source that are analogous to set entry, get entry, create
entry, delete entry, and get list C API calls.
Use external data to implement Push Field and Set Field filter, escalation, and active link
actions.
Create, modify, and search for external data through API clients.
Construct query-style character menus.
Present forms, views, and active links on external data in the same manner as internal data.
The data source is transparent to the user.
Page 908 of 4705
Home
When you create an ARDBC plug-in, be sure to completely document the capabilities of your
plug-in. For example, you might create a read-only plug-in, which does not allow a user to create,
set, or delete entries.
If the data source with which you integrate does not support a particular functionality, do not
implement that function. Instead, let the default behavior occur. For example, if your data source
does not support transactions, do not define ARDBCCommitTransaction and
ARDBCRollbackTransaction functions.
These are the ARDBC plug-in API functions:
ARDBCCommitTransaction
ARDBCCreateEntry
ARDBCDeleteEntry
ARDBCGetEntry
ARDBCGetEntryBLOB
ARDBCGetEntryStatistics
ARDBCGetListEntryWithFields
ARDBCGetListSchemas
ARDBCGetMultipleFields
ARDBCRollbackTransaction
ARDBCSetEntry
For more information, see ARDBC plug-in API functions.
Creating a vendor form for an ARDBC plug-in

After you build and install an ARDBC plug-in and configure your server to recognize it, you can
create a vendor form. For information about configuring your server to recognize a plug-in, see the
Configuring after installation section.
Note
Creating a vendor form for an ARDBC LDAP plug-in is a special case. See Creating a
vendor form to represent a collection of LDAP objects .
Keep these issues in mind when creating a vendor form:

The plug-in can load more than one ARDBC plug-in at a time.
Full Text Search (FTS) operations are not available on vendor form fields.
You can add only those Required and Optional fields that correspond to actual columns in
the data source. In addition, you can add a Display Only field only when the column name
does not correspond to a column in the data source.
Page 909 of 4705
Home
For more information about vendor forms, see Creating vendor forms.
To create a vendor form for an ARDBC plug-in

1. In Developer Studio, choose File > New > Vendor Form.
2. In the New Vendor Form Wizard, select the server on which you want to create the vendor
form and click Next.
3. Select the ARDBC plug-in to use in the list of Available Vendor Names, and click Next.
4. Choose a table from the list of Available Vendor Tables, and click Next.
Alternatively, type a table name in the Table field, click Validate, then click Next.
5. (optional) On the Field Selection page, choose a key column in the Key Field list box.
6. In the Available Columns list on the Field Selection page, select columns to access in BMC
Remedy AR System. Use the arrow buttons to move them to the Selected Columns list.
New Vendor Form Wizard, Selected Columns
7. Click Finish to create the vendor form.

8. Use Developer Studio to edit the new form, then click File > Save.
ARDBC plug-in Java API methods

The methods defined in the ARDBCPluggable interface and the ARDBCPlugin abstract class are
common to all plug-in types. For more information, see the Java plug-in API online documentation
located at ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
ARDBC plug-ins configuration

AR System Database Connectivity (ARDBC) plug-ins provide access to data stored outside the AR
System database as if the data were located in tables owned by BMC Remedy AR System.
Page 910 of 4705
Home
The configuration information for the ARDBC plug-ins is available in the following configuration files
:
<ARInstallationFolder>\pluginsvr\pluginsvr_config.xml
(Windows) <ARInstallationFolder>\conf\ar.cfg
Log file configuration is available in the <ARInstallationFolder>\pluginsvr\log4j_pluginsvr.xml
file. For information about how to configure a server to use plug-ins, see Configuring a server to
use plug-ins.
Use the configuration files to:
Configure a plug-in server and port
Enable plug-in logging
Troubleshoot plug-in issues
The following topics describe the configuration information of the ARDBC plug-ins.
AppQuery plug-in configuration
Approval Server plug-in configuration
DSO Filter Configuration plug-in configuration
File System plug-in configuration
Pentaho plug-in configuration
RKM Group plug-in configuration
Rule Engine Configuration plug-in configuration
Server Administration plug-in configuration
Software Usage plug-in configuration
Related topic
AppQuery plug-in configuration

The AppQuery plug-in queries several BMC Remedy AR System forms and consolidates the
results, which you can display in the Overview console or in a table field. This plug-in supports only
read functionality.
Plug-in type
AppQuery is a Java-based ARDBC plug-in.

The AppQuery plug-in connects to the AR System server by using AR System Java API calls. This
plug-in (conquery.jar) is installed in the <ARInstallationFolder>\pluginsvr folder.
Page 911 of 4705
Home
The configuration information of the AppQuery plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>REMEDY.ARDBC.APPQUERY</name>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\qry\conquery.jar</filename>
<classname>com.bmc.itsm.conquery.ardbc.conquery.Query</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\qry\conquery.jar</
pathelement>
<pathelement type="path">C:\BMC Software\ARSystem\pluginsvr\qry</pathelement>
<userDefined>
<Plugin-Loopback-RPC-Socket>390622</Plugin-Loopback-RPC-Socket>
</userDefined>
</plugin>
server alias as follows:
Server-Plugin-Alias: REMEDY.ARDBC.APPQUERY REMEDY.ARDBC.APPQUERY myServer
:9999
Related topic
Troubleshooting AppQuery plug-in issues
Approval Server plug-in configuration

The Approval Server plug-in is a self-contained shared module that you can attach to any BMC
Remedy AR System application. The Approval Server plug-in is a flexible solution for automating
any approval or signature-driven process across any organization.
The approval server includes built-in contingency handling, which ensures that approvals are
completed quickly within the system. When a BMC Remedy AR System application triggers an
approval process, the approval server routes a request to collect signatures within a defined
approval process, handling all notifications and requests for more information as it collects each
response (approval or rejection). The approval server then reactivates the original application and
reports the result of the approval process.
You can run multiple instances of the approval server with multiple instances of AR System server
on one computer.
Page 912 of 4705
Home
Plug-in type
Approval Server is a Java-based ARDBC plug-in that runs as a part of Java plug-in server.

The Approval Server plug-in interacts with the AR System server through the application
commands. The plug-in (arasjVerNum.jar)* is installed in the <ARInstallationFolder>\ARSystem\
approval\bin folder. (VerNum represents the version number of the release.)
The Approval Server plug-in receives its configuration information from the ar.cfg/ar.conf file,
which contains information about the log file, related notifications, and their states (active or inactive
).
The ar.cfg/ar.conf file also has an entry for the Alternate-Approval-Reg configuration setting.
This setting indicates whether the approval server is notified by the dispatcher regarding commands
or picks them on its own from the Application Pending form. The default value of the
Alternate-Approval-Reg setting is T (True), which ensures that the approval server receives the
signals sent by the dispatcher. Change the value to F (False) only when the application dispatcher
is not working; this provides an alternative method to receive signals from the AR System server.
The AR System server installation creates this entry and sets the value to T. To change the setting,
use a text editor to edit the ar.cfg/ar.conf file.
The configuration information of the Approval Server plug-in is available in the <
<plugin>
<pathelement type="location">C:/BMC Software/ARSystem/approval/bin/arasj81_
<pathelement type="location">C:/BMC Software/ARSystem/arserver/api/lib/arcmnapp80_
<pathelement type="location">C:/BMC Software/ARSystem/arserver/api/lib/arutil81_
</plugin>
Server-Plugin-Alias: ARSYS.ARDBC.PREVIEW ARSYS.ARDBC.PREVIEW myServer:
9999
Page 913 of 4705
Home
By default, the log information is available in the <ARInstallationFolder>\ARSystem\db\

arapprove.log file. Using the Server Settings form, you can specify a different log file name and log
file path.
Related topic
Troubleshooting Approval Server plug-in issues
Configuring BMC Remedy Approval Server with a separate plug-in server instance
DSO Filter Configuration plug-in configuration

The DSO Filter Configuration plug-in adds or deletes a DSO action such as DSO Delete, DSO
Return, or DSO Transfer to or from a filter. This DSO action is then used as an event for DSO. The
filter list is provided in a configuration form, which is an input for the plug-in configuration.
Plug-in type
DSO Filter Configuration is a Java-based ARDBC plug-in.

The AR System server interacts with the DSO Filter Configuration plug-in by using the BMC
Remedy AR System Java APIs. This plug-in ( DSOConfigurationPlugin.jar) is installed in the <
ARInstallationFolder>\pluginsvr\dsoConfig folder.
The configuration information of the DSO Filter Configuration plug-in is available in the <
<plugin>
<name>DSO.FILTERCONFIGURATION</name>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\dsoconfig\
DSOConfigurationPlugin.jar</pathelement>
<classname>config.DSOFilterConfigurationPlugin</classname>
<userDefined>
<filter_configuration_form_name>HNS:UtilityCodeGenerator</
filter_configuration_form_name>
<filter_name_field_id>700001115</filter_name_field_id>
<mapping_name_field_id>700001114</mapping_name_field_id>
</userDefined>
</plugin>
The <filter_configuration_form_name> tag contains the name of the form that has fields
for filter name and mapping name.
The <filter_name_field_id> and <mapping_name_field_id> tags contain IDs of the fields
that contain the filter name and the mapping name, respectively.
Page 914 of 4705
Home
server alias:
Server-Plugin-Alias: DSO.FILTERCONFIGURATION DSO.FILTERCONFIGURATION
myServer:9999
Related topic
Troubleshooting DSO Filter Configuration plug-in issues
File System plug-in configuration

The File System plug-in provides a file search service in the Microsoft Windows file system and
mapped disks. The File System plug-in enables you to search any type of file in the file system,
based on search criteria. The File System plug-in receives the search parameters from the AR
Vendor form fields and returns the results to the same form.
The plug-in supports different file name qualifications, such as:
Simple qualification, such as the file extension (for example, .doc or .pdf file extensions)
Open qualification for a file name written by using a regular-expression syntax
For more information, see http://docs.oracle.com/javase/tutorial/essential/regex/intro.html .
The File System plug-in returns the file name, file path, the file, and the date of modification as
output. In addition, the plug-in returns document author, title, subject, and keywords as output
values for .doc and .pdf files.
Plug-in type
File System is a Java-based ARDBC plug-in.

The File System plug-in interacts with the AR System server through the AR Vendor form that
contains input fields for search parameters and output fields for viewing search results. The vendor
form that is used is RKM:VF_FileSystem. The File System plug-in ( file-system.jar) is installed in
the C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the File System plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>RMDY.ITSM.RKM.FILESYSTEM</name>
<type>ARDBC</type>
<code>JAVA</code>
file-system.jar</filename>
<classname>com.bmc.itsm.rkm.ardbc.filesystem.RkmFileSystemPlugin</classname>
Page 915 of 4705
Home

plugins\3rd_party\commons-io-1.4.jar</pathelement>
plugins\3rd_party\poi-3.5-FINAL-20090928.jar</pathelement>
plugins\3rd_party\iText-2.1.5.jar</pathelement>
plugins\3rd_party\dom4j-1.6.1.jar</pathelement>
plugins\3rd_party\poi-ooxml-3.5-FINAL-20090928.jar</pathelement>
<pathelement type="path">C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\
plugins</pathelement>
<userDefined>
<entry_id_length>500</entry_id_length>
</userDefined>
</plugin>
Server-Plugin-Alias: RMDY.ITSM.RKM.FILESYSTEM RMDY.ITSM.RKM.FILESYSTEM
myServer:9999
Related topic
Troubleshooting File System plug-in issues
Pentaho plug-in configuration

The Pentaho plug-in enables you to run and monitor Atrium Integrator jobs and transformations
from BMC Remedy AR vendor forms. This plug-in is designed specifically to enable a BMC
Remedy AR System or BMC Remedy IT Service Management application user to create a
comprehensive, AR form-based data management user interface.
Plug-in type
Pentaho is a Java-based ARDBC plug-in.

The Pentaho plug-in connects and interacts with AR System server by using the BMC Remedy AR
System Java APIs. This plug-in ( pentahoardbcVerNum.jar)* is installed in the <
ARInstallationFolder>\diserver\ardbc-plugin directory. (VerNum represents the version number
of the release.)
The configuration information of the Pentaho plug-in is available in the <ARInstallationFolder>\
Page 916 of 4705
Home
<plugin>
<name>ARSYS.ARDBC.PENTAHO</name>
<classname>com.bmc.arsys.pdi.ardbc.ARPentahoPlugin</classname>
<userDefined>
<pdiDirPath>C:/Program Files/BMC Software/ARSystem/diserver/data-integration</
pdiDirPath>
<kettleHome>C:/Program Files/BMC Software/ARSystem/diserver</kettleHome>
</userDefined>
<pathelement type="location">C:/Program Files/BMC Software/ARSystem/diserver/
ardbc-plugin/pentahoardbc80_build001.jar</pathelement>
ardbc-plugin/arcmnapp80_build001.jar</pathelement>
data-integration/lib/kettle-core.jar</pathelement>
data-integration/lib/kettle-db.jar</pathelement>
data-integration/lib/kettle-engine.jar</pathelement>
data-integration/libext/cmdbapi80.jar</pathelement>
data-integration/libext/arpdi-utils80_build001.jar</pathelement>
data-integration/libext/arpdirepository80_build001.jar</pathelement>
data-integration/libext/JDBC/LucidDbClient-minimal.jar</pathelement>
data-integration/libext/JDBC/asjava.zip</pathelement>
data-integration/libext/JDBC/db2jcc.jar</pathelement>
data-integration/libext/JDBC/db2jcc_license_cu.jar</pathelement>
data-integration/libext/JDBC/derby.jar</pathelement>
data-integration/libext/JDBC/derbyclient.jar</pathelement>
data-integration/libext/JDBC/h2.jar</pathelement>
data-integration/libext/JDBC/hive-jdbc-0.5.0-pentaho-1.0.0.jar</pathelement>
data-integration/libext/JDBC/hsqldb.jar</pathelement>
data-integration/libext/JDBC/ifxjdbc.jar</pathelement>
data-integration/libext/JDBC/iijdbc.jar</pathelement>
data-integration/libext/JDBC/infobright-core-3.3.jar</pathelement>
data-integration/libext/JDBC/interclient.jar</pathelement>
data-integration/libext/JDBC/jaybird-full-2.1.0.jar</pathelement>
Page 917 of 4705
Home

data-integration/libext/JDBC/jt400.jar</pathelement>
data-integration/libext/JDBC/jtds-1.2.5.jar</pathelement>
data-integration/libext/JDBC/kingbasejdbc.jar</pathelement>
data-integration/libext/JDBC/monetdb-1.7-jdbc.jar</pathelement>
data-integration/libext/JDBC/mysql-connector-java-3.1.14-bin.jar</pathelement>
data-integration/libext/JDBC/ojdbc14.jar</pathelement>
data-integration/libext/JDBC/orai18n.jar</pathelement>
data-integration/libext/JDBC/postgresql-8.3-603.jdbc3.jar</pathelement>
data-integration/libext/JDBC/rdbthin.jar</pathelement>
data-integration/libext/JDBC/sapdbc.jar</pathelement>
data-integration/libext/JDBC/sqlitejdbc-v037-nested.jar</pathelement>
data-integration/libext/JDBC/unijdbc.jar</pathelement>
data-integration/libext/JDBC/vertica_3.5_jdk_5.jar</pathelement>
data-integration/libext/JDBC/xdbjdbc.jar</pathelement>
data-integration/libext/commons/commons-beanutils-1.7.0.jar</pathelement>
data-integration/libext/commons/commons-codec-1.3.jar</pathelement>
data-integration/libext/commons/commons-collections-3.1.jar</pathelement>
data-integration/libext/commons/commons-dbcp-1.2.1.jar</pathelement>
data-integration/libext/commons/commons-digester-1.8.jar</pathelement>
data-integration/libext/commons/commons-fileupload-1.0.jar</pathelement>
data-integration/libext/commons/commons-httpclient-3.0.1.jar</pathelement>
data-integration/libext/commons/commons-io-1.4.jar</pathelement>
data-integration/libext/commons/commons-lang-2.4.jar</pathelement>
data-integration/libext/commons/commons-logging-1.1.jar</pathelement>
data-integration/libext/commons/commons-net-1.4.1.jar</pathelement>
data-integration/libext/commons/commons-pool-1.3.jar</pathelement>
data-integration/libext/commons/commons-validator-1.3.1.jar</pathelement>
Page 918 of 4705
Home

data-integration/libext/feeds/feed4j.jar</pathelement>
data-integration/libext/feeds/georss-rome-0.9.8.jar</pathelement>
data-integration/libext/feeds/jdom.jar</pathelement>
data-integration/libext/feeds/nekohtml.jar</pathelement>
data-integration/libext/feeds/rome-1.0.jar</pathelement>
data-integration/libext/feeds/xml-apis.jar</pathelement>
data-integration/libext/hive/hadoop-core-0.20.0.jar</pathelement>
data-integration/libext/hive/hive-exec-0.5.0-pentaho-1.0.0.jar</pathelement>
data-integration/libext/hive/hive-metastore-0.5.0-pentaho-1.0.0.jar</pathelement>
data-integration/libext/hive/hive-service-0.5.0-pentaho-1.0.0.jar</pathelement>
data-integration/libext/hive/libfb303.jar</pathelement>
data-integration/libext/hive/libthrift.jar</pathelement>
data-integration/libext/jfree/jcommon-1.0.14.jar</pathelement>
data-integration/libext/jfree/jfreechart-1.0.1.jar</pathelement>
data-integration/libext/mondrian/config/mondrian.properties</pathelement>
data-integration/libext/mondrian/commons-math-1.1.jar</pathelement>
data-integration/libext/mondrian/eigenbase-properties-1.1.0.10924.jar</pathelement>
data-integration/libext/mondrian/eigenbase-resgen-1.3.0.13768.jar</pathelement>
data-integration/libext/mondrian/eigenbase-xom-1.3.0.13768.jar</pathelement>
data-integration/libext/mondrian/javacup-10k.jar</pathelement>
data-integration/libext/mondrian/mondrian-3.2.1.13885.jar</pathelement>
data-integration/libext/mondrian/saxon8-xom.jar</pathelement>
data-integration/libext/pentaho/hadoop-core-0.20.2.jar</pathelement>
data-integration/libext/pentaho/jets3t-0.7.4.jar</pathelement>
data-integration/libext/pentaho/kettle-vfs-20100924.jar</pathelement>
data-integration/libext/pentaho/libbase-1.2.1.jar</pathelement>
data-integration/libext/pentaho/libformula-1.2.1.jar</pathelement>
Page 919 of 4705
Home

data-integration/libext/pentaho/olap4j-0.9.8.340.jar</pathelement>
data-integration/libext/pentaho/pentaho-database-4.0.5.jar</pathelement>
data-integration/libext/pentaho/pentaho-formula-editor-0.0.1.jar</pathelement>
data-integration/libext/pentaho/pentaho-hdfs-vfs-1.0.0.jar</pathelement>
data-integration/libext/pentaho/pentaho-s3-vfs-1.0.1.jar</pathelement>
data-integration/libext/pentaho/pentaho-vfs-browser-2.0.2.jar</pathelement>
data-integration/libext/pentaho/pentaho-xul-core-3.2.1.jar</pathelement>
data-integration/libext/pentaho/pentaho-xul-swt-3.2.1.jar</pathelement>
data-integration/libext/pentaho/sqleonardo-swt-wrapper.jar</pathelement>
data-integration/libext/pentaho/sqleonardo.jar</pathelement>
data-integration/libext/rules/antlr-runtime-3.1.1.jar</pathelement>
data-integration/libext/rules/core-3.4.2.v_883_R34x.jar</pathelement>
data-integration/libext/rules/drools-api-5.0.1.jar</pathelement>
data-integration/libext/rules/drools-compiler-5.0.1.jar</pathelement>
data-integration/libext/rules/drools-core-5.0.1.jar</pathelement>
data-integration/libext/rules/mvel2-2.0.10.jar</pathelement>
data-integration/libext/salesforce/axis.jar</pathelement>
data-integration/libext/salesforce/commons-discovery-0.2.jar</pathelement>
data-integration/libext/salesforce/jaxrpc.jar</pathelement>
data-integration/libext/salesforce/saaj.jar</pathelement>
data-integration/libext/salesforce/salesforce20.0.jar</pathelement>
data-integration/libext/spring/spring-beans-2.5.6.jar</pathelement>
data-integration/libext/spring/spring-context-2.5.6.jar</pathelement>
data-integration/libext/spring/spring-context-support-2.5.6.jar</pathelement>
data-integration/libext/spring/spring-core-2.5.6.jar</pathelement>
data-integration/libext/web/activation.jar</pathelement>
data-integration/libext/web/jetty-6.1.21.jar</pathelement>
Page 920 of 4705
Home

data-integration/libext/web/jetty-plus-6.1.21.jar</pathelement>
data-integration/libext/web/jetty-util-6.1.21.jar</pathelement>
data-integration/libext/web/servlet-api-2.5-6.1.9.jar</pathelement>
data-integration/libext/web/simple-jndi-0.11.1.jar</pathelement>
data-integration/libext/webservices/jsr173_api.jar</pathelement>
data-integration/libext/webservices/qname.jar</pathelement>
data-integration/libext/webservices/wsdl4j.jar</pathelement>
data-integration/libext/webservices/wstx-asl-3.2.9.jar</pathelement>
data-integration/libext/webservices/xalan-2.4.1.jar</pathelement>
data-integration/libext/SNMP4J.jar</pathelement>
data-integration/libext/ascsapjco3wrp.jar</pathelement>
data-integration/libext/dom4j-1.6.1.jar</pathelement>
data-integration/libext/edtftpj2.1.jar</pathelement>
data-integration/libext/ftp4che-0.7.1.jar</pathelement>
data-integration/libext/ini4j-0.5.1.jar</pathelement>
data-integration/libext/jackcess-1.2.1.jar</pathelement>
data-integration/libext/jakarta-oro-2.0.8.jar</pathelement>
data-integration/libext/janino.jar</pathelement>
data-integration/libext/javadbf.jar</pathelement>
data-integration/libext/javassist.jar</pathelement>
data-integration/libext/jaxen-1.1.1.jar</pathelement>
data-integration/libext/jcifs-1.3.3.jar</pathelement>
data-integration/libext/js.jar</pathelement>
data-integration/libext/jsch-0.1.42.jar</pathelement>
data-integration/libext/json_simple-1.1.jar</pathelement>
data-integration/libext/jsonpath.jar</pathelement>
data-integration/libext/jug-lgpl-2.0.0.jar</pathelement>
Page 921 of 4705
Home

data-integration/libext/junit-4.7.jar</pathelement>
data-integration/libext/jxl.jar</pathelement>
data-integration/libext/ldapjdk.jar</pathelement>
data-integration/libext/livetribe-jsr223-2.0.6.jar</pathelement>
data-integration/libext/log4j-1.2.14.jar</pathelement>
data-integration/libext/mail.jar</pathelement>
data-integration/libext/odfdom.jar</pathelement>
data-integration/libext/ognl-2.6.9.jar</pathelement>
data-integration/libext/palo-core.jar</pathelement>
data-integration/libext/poi-3.6-20091214.jar</pathelement>
data-integration/libext/poi-ooxml-3.6-20091214.jar</pathelement>
data-integration/libext/poi-ooxml-schemas-3.6-20091214.jar</pathelement>
data-integration/libext/saxon8.jar</pathelement>
data-integration/libext/scannotation-1.0.2.jar</pathelement>
data-integration/libext/secondstring.jar</pathelement>
data-integration/libext/slf4j-api-1.5.8.jar</pathelement>
data-integration/libext/slf4j-jcl-1.5.8.jar</pathelement>
data-integration/libext/snakeyaml-1.7.jar</pathelement>
data-integration/libext/syslog4j-0.9.34.jar</pathelement>
data-integration/libext/trilead-ssh2-build213.jar</pathelement>
data-integration/libext/xbean.jar</pathelement>
data-integration/libext/xercesImpl-2.9.1.jar</pathelement>
</plugin>
Server-Plugin-Alias: ARSYS.ARDBC.PENTAHO ARSYS.ARDBC.PENTAHO myServer:
9999
Page 922 of 4705
Home
Related topic
Troubleshooting Pentaho plug-in issues
RKM Group plug-in configuration

The RKM Group plug-in gets group-related information from the Group form, because the BMC
Remedy Knowledge Management (RKM) user does not have permissions to use the Group form.
The RKM Group plug-in queries the data by logging on as a BMC Remedy Application Service user
and retrieving the read-only data from the form.
Plug-in type
RKM Group is a Java-based ARDBC plug-in.

The RKM Group plug-in connects to the AR System server by using the BMC Remedy AR System
Java API. This plug-in (rkm-group.jar) is installed in the C:\BMC Software\
BMCRemedyITSMSuite\Shared_Components\plugins folder.
The configuration information of the RKM Group plug-in is available in the <ARInstallationFolder>\
<plugin>
<name>RMDY.ITSM.RKM.GROUP</name>
<type>ARDBC</type>
<code>JAVA</code>
<filename>C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-group.jar<
/filename>
<classname>com.bmc.itsm.rkm.ardbc.group.GroupController</classname>
</pathelement>
</plugin>
Server-Plugin-Alias: RMDY.ITSM.RKM.GROUP RMDY.ITSM.RKM.GROUP myServer:
9999
Related topic
Troubleshooting RKM Group plug-in issues
Page 923 of 4705
Home
Rule Engine Configuration plug-in configuration

The Rule Engine Configuration plug-in configures the log level, log file path, and log file size of the
Rule Engine plug-in. This plug-in is also permits you to view the Rule Engine plug-in log file.
Plug-in type
Rule Engine Configuration is a Java-based ARDBC plug-in.

The Rule Engine Configuration plug-in connects to the AR System server when the user runs jobs
from the Manage License Job form. The plug-in ( rle_config.jar) is installed in the C:\BMC
Software\ARSystem\pluginsvr\rleconfig folder.
The configuration information of the Rule Engine Configuration plug-in is available in the <
<plugin>
<name>RMDY.ITSM.RLECONFIG</name>
<type>ARDBC</type>
<code>JAVA</code>
<filename>C:\BMC Software\ARSystem\pluginsvr\rleconfig\rle_config.jar</filename>
<classname>com.bmc.itsm.rleconfig.RuleEngineConfigPlugin</classname>
<pathelement type="path">C:\BMC Software\ARSystem\pluginsvr\rleconfig</pathelement>
<userDefined>
<log4j_pluginsvr_xml_path>C:\BMC Software\ARSystem\pluginsvr\log4j_pluginsvr.xml</
log4j_pluginsvr_xml_path>
</userDefined>
</plugin>
server alias:
Server-Plugin-Alias: RMDY.ITSM.RLECONFIG RMDY.ITSM.RLECONFIG myServer:
9999
Log file configuration is available in the log4j_pluginsvr.xml file. For example:
<appender class="org.apache.log4j.RollingFileAppender" name="SWLMLog">

<param name="File" value="C:/BMC Software/ARSystem/ARServer/Db/SWLMFilter.log"/>
<param name="MaxFileSize" value="999KB"/>
<param name="MaxBackupIndex" value="5"/>
<layout class="org.apache.log4j.PatternLayout">
<param name="ConversionPattern" value=""%d %-5p [%t] %C (%F:%L) - %m%n"/>
</layout>
Page 924 of 4705
Home
</appender>
<root>
<logger additivity="false" name="com.bmc.itsm.rleconfig">
<appender-ref ref="SWLMLog"/>
</logger>
Related topic
Troubleshooting Rule Engine Configuration plug-in issues
Server Administration plug-in configuration

The Server Administration plug-in provides an interface to the Administrator user for configuring
BMC Remedy AR System server settings. Using the Server Administration plug-in, you can
configure how the server works and how it interacts with users. Use this plug-in to display
information about the selected server and to set server options (configuration settings are specific
to each server). In addition, you can configure license information, enforce password changes, and
configure passwords used between the AR System server and its external subsystems.
The Server Administration plug-in implements the following forms:
AR System Administration:License Review
AR System Administration:Server Information
AR System Administration:Support Form
This plug-in is installed during BMC Remedy AR System installation. The plug-in consists of a
library file and a deployable application.
Plug-in type
Server Administration is a C-based ARDBC plug-in.
The Server Administration plug-in is installed in the following path:
(Microsoft Windows) <ARInstallationFolder>\ServerAdmin.dll

(UNIX) <ARInstallationFolder>/bin/ServerAdmin.so
The Server Administration plug-in is configured in the following files:
(Microsoft Windows) <ARInstallationFolder>\conf\ar.cfg

For example, the ar.cfg file on Windows includes the name of the plug-in as follows:
Plugin: ServerAdmin.dll
Related topic
Troubleshooting Server Administration plug-in issues
Page 925 of 4705
Home
Software Usage plug-in configuration

The Software Usage plug-in enables you to gather product usage information. By querying the
usage information, you can identify products that are tied to a certificate or multiple certificates that
might be approaching expiration or a breach of compliance. The usage information can also be
checked against a product in the product catalog, such as Adobe Acrobat that requires a contract.
This produces a list of configuration items (CIs) that have usage information. The purpose of the
plug-in is to help the IT asset managers understand what software instances are used or not used,
so that they can make harvesting decisions.
Plug-in type
Software Usage is a Java-based ARDBC plug-in.

The Software Usage plug-in connects to the AR System server by using the BMC Remedy AR
System Java API. This plug-in ( AstSoftUsagePlugin.jar) is installed in the C:\BMC Software\
ARSystem\pluginsvr\swu folder.
The configuration information of the Software Usage plug-in is available in the <
<plugin>
<name>RMDY.ITSM.ASSET.SOFTWAREUSAGE</name>
<code>JAVA</code>
<filename/>
<classname>com.bmc.itsm.asset.swusage.plugin.AssetSoftwareUsagePlugin</classname>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\swu\
AstSoftUsagePlugin.jar</pathelement>
<userDefined>
</userDefined>
</plugin>
server alias.
Server-Plugin-Alias: RMDY.ITSM.ASSET.SOFTWAREUSAGE
RMDY.ITSM.ASSET.SOFTWAREUSAGE myServer:9999
Related topic
Troubleshooting Software Usage plug-in issues
Page 926 of 4705
Home
Installed plug-in components

Before you can create AR System plug-ins, you must install these components:
AR System plug-in servers Automatically installed with BMC Remedy AR System.
API component of the AR System server Includes the plug-in APIs. You must select
this option during the BMC Remedy AR System installation. The API component includes:
The header files you use to compile C plug-ins and create the shared libraries. See
the arplugin.h file for C plug-in definitions and declarations.
The files you need to write Java plug-ins.
Note
In addition to the BMC Remedy AR System 8.1 Java plug-in server and its API, the C
plug-in server, arplugin, and its API are installed.
Installed plug-in files

The plug-in server and Java plug-in API files are typically installed in the following directories:
UNIX /usr/ar/<serverName>/pluginsvr
Windows C:\Program Files\AR System\<serverName>\pluginsvr
Component
Description
arapiVerNum.jar*
Includes the AR System Java API, Java utilities, and AR System server communications
This file is called by Java plug-ins.
arplugin.log
Plug-in server log file

This file is generated when the Java plug-in server starts.
arpluginjniVerNum.dll*
(Windows) C plug-in server interface for C plug-ins
arpluginsvrVerNum.jar*
Java plug-in server and plug-in interfaces

This file is called by the Java plug-in server.
log4j_pluginsvr.xml
Java plug-in server logging configuration file
log4j-1.2.14.jar
Java logging utility
Java plug-in server configuration file
pluginsvrstartup.bat
Java plug-in server start-up file for Windows
pluginsvrstartup.sh
Java plug-in server start-up file for UNIX
* VerNum represents the release version number.

The arplugin.h file is installed with the other C API include files in the include subdirectory.
Page 927 of 4705
Home
Creating C plug-ins
You must create a separate plug-in for each of the three types of plug-ins. For example, you cannot
create one plug-in that supports both AREA and ARDBC.
Note
On Windows platforms, plug-ins created for pre-7.0 servers must be recompiled with
Microsoft Visual Studio .NET 2003 to be used successfully in the BMC Remedy AR
System 7.0 environment.
To create a C plug-in
1. Write a C or C++ program that includes these elements:
A reference to the arplugin.h file for plug-in definitions and declarations.
Plug-in API calls for initialization, termination, object creation, and object deletion (see
Common plug-in C functions and Java methods ).
One of these type-specific API calls:
AREA (see AREA plug-in C API functions)
ARDBC (see ARDBC plug-in C API functions)
AR Filter (see AR filter API plug-ins introduction)
Code to implement the calls. Use sample Microsoft Developer Studio projects (
Windows) or makefiles (UNIX), which you install with BMC Remedy AR System, to
build your program into your DLL or shared object library.
For examples and templates for C plug-ins, see the ardbc, area, and arfilterapi
subdirectories of the Api directory in your BMC Remedy AR System server
installation.
C plug-in call sequence shows the general structure of a plug-in program.
2. Compile and link your plug-in as follows:
On Windows platforms, compile your plug-in using Microsoft Visual Studio .NET 2003.
On Linux, you must use the -malign-double option when compiling plug-ins to make
sure that your plug-in library is correctly aligned for the plug-in server. If you do not,
the plug-in might produce unexpected results.
If you compile and link your plug-in on HP-UX using aCC and enable exception
handling, your plug-in will have dependencies on libraries that are not standard C/C++
libraries, for example libCsup_v2 and libstd_v2. If your plug-in has dependencies on
any libraries like these, you must explicitly link to them and make sure they are
available at run time in the shared library path for the plug-in server to find them.
3. Put your plug-in DLL or shared library file in the directory that contains the BMC Remedy AR
System server and plug-in server executable files or any other directory listed in you PATH
environment variable.
4.
Page 928 of 4705
Home
4. Add an entry for the plug-in to the plug-in server configuration file. See Configuring the Java
plug-in server.
At run time, the plug-in server reads the configuration file and loads the specified plug-ins.
C plug-in naming conventions

When you create a C plug-in, use the following naming conventions and memory management
recommendations.
Managing memory
Do not free memory that the plug-in passes to your functions as arguments or that you return to the
plug-in. Plug-ins can allocate and deallocate memory associated with the object argument for each
call. The plug-in does not deallocate this memory.
Specifying input and return values

In a C API program, developers specify input values for the functions and receive return values. In
a plug-in program, the plug-in provides the input values to the plug-ins, and the plug-ins provide
return values.
If the AR System server returns AR_RETURN_WARN or AR_RETURN_OK to the arplugin log file
after a call is issued, the plug-in considers that call successful. The plug-in considers the call
unsuccessful if the server returns AR_RETURN_ERROR or AR_RETURN_FATAL.
If you do not implement a call, the plug-in performs a default action. The default action might be to
proceed or to return an error message.
Protecting global information

To ensure thread safety, you must protect any global information or resources that you access
through plug-in API calls with appropriate mutual exclusion locks. Global information and resource
protection applies to all plug-in calls except ARPluginIdentify, ARPluginInitialization,
ARPluginSetProperties, and ARPluginTermination, which are always called by one thread at a
time.
At run time, the plug-in server reads the configuration file and creates the plug-ins that the file
specifies. After the plug-in server creates the plug-ins, they remain active until a system failure or
until you modify the plug-in configuration information and restart the plug-in server. For information
about restarting the plug-in server, see Restarting the plug-in server using the Set Server Info
command.
Configuring the Java plug-in server

Configure the Java plug-in server in the pluginsvr_config.xml file in the pluginsvr subdirectory of
your AR System server installation directory. This file should be in the same directory as the plug-in
server JAR files and startup script. (It must be in the class path for the plug-in server.) When you
add a plug-in to the plug-in server configuration in the pluginsvr_config.xml file and save the file,
Page 929 of 4705
Home
the plug-in server loads the new plug-in after a configured delay. If you remove a plug-in server or
make other configuration changes, you must use armonitor to stop and restart the plug-in server
for it to process the changes.
In BMC Remedy AR System 7.5.00, the file encoding of the pluginsvr_config.xml file was
changed from ISO 8859-1 to UTF-8. This change enables you to use localized plug-in names in the
configuration file. If you modify the pluginsvr_config.xml file, save it as a Unicode file. Some text
editors, such as Windows Notepad, save files as single-byte ANSI (ASCII) by default.
Tip
Install critical plug-ins, such as an LDAP plug-in that performs LDAP authentication, in
separate plug-in servers. If multiple plug-ins are installed on a single server, problems with
one plug-in might affect the use of the other plug-ins.
See the sample configuration file, pluginsvr_config.xml, for descriptions, valid values, and default
values for the Java plug-in server configuration options.
Note
See the Configuring after installation section for configuration of the C-based plug-in
server, arplugin.

Using multithreading in the Java plug-in server
Using dynamic plug-in loading
Using the Java plug-in server for dynamic plug-in loading
Using the C plug-in server for dynamic plug-in loading
Using plug-in naming conventions
Restarting the plug-in server using the Set Server Info command
Overriding values from ar.cfg or ar.conf
Using multithreading in the Java plug-in server

In previous releases, the Java plug-in server created a thread to handle each RPC connection as it
was received from the AR System server, often creating many threads. If a connection failed, the
plug-in server programmatically shut down the plug-in instances associated with the thread for that
connection, often losing data in the process.
Page 930 of 4705
Home
To improve performance, the Java plug-in server now uses a configurable pool of worker threads to
handle RPC calls. The pool and its associated plug-in instances are created at startup, rather than
as RPC calls are received. If a connection fails, the plug-in instances associated with the thread
remain instantiated and can still process calls from other connections.
Note
Do not send any requests to the Java plug-in server before the plug-ins are loaded and
instantiated. (If the plug-in log level is Warn or higher, a message is recorded in the log
file when the plug-in server is ready to receive RPC calls.)
When an RPC call is received from the AR Server, a selector thread adds the call to the worker
thread task queue. By default, the system uses two selector threads. To prevent bottlenecks, you
can increase the number of selector threads by using the numSelectorThreads tag in the sample
Whenever a worker thread is free, it starts processing the next request in the task queue. By default
, the pool contains five worker threads. To prevent bottlenecks, you can increase the number of
worker threads by using the numCoreThreads tag in the sample pluginsvr_config.xml file.
An unlimited number of tasks can be added to the worker thread task queue. To be notified when
too many tasks accumulate in the queue, you can specify a task threshold. When the threshold is
exceeded, a message is logged in the arjavaplugin.log file. This enables you to avoid potential
queue bottlenecks by creating more worker threads in a timely fashion.
To specify the task threshold, use the workQueueTaskThreshold tag in the sample
To specify how frequently the system checks to see whether the task threshold has been exceeded
, use the workQueueMonitorLogInterval tag in the sample pluginsvr_config.xml file.
See the plug-in server configuration file ( pluginsvr_config.xml).
Using dynamic plug-in loading

Dynamic plug-in loading is adding or loading a new plug-in definition in the plug-in server without
stopping and restarting the AR System server. In previous releases, most changes made to the
pluginsvr_config.xml file required a plug-in server restart to take effect.
Using the Java plug-in server for dynamic plug-in loading

To enable dynamic plug-in loading, you must specify a reload delay before starting the plug-in
server (use the reloadDelay tag in the sample pluginsvr_config.xml file). When a delay is
specified, the system automatically loads plug-ins and initiates them for all worker threads after the
Page 931 of 4705
Home
delay period without requiring a plug-in server restart. During the delay period, you can modify the
new plug-in configuration if necessary. (If you modify it after the delay, you must restart the plug-in
server to make your changes take effect.) For information about restarting the plug-in server, see
Restarting the plug-in server using the Set Server Info command .
See the plug-in server configuration file ( pluginsvr_config.xml).
To configure the Atrium SSO plug-in using only the Java plug-in server
1. Make the following changes in the ar.cfg file:
a. Comment out the Plugin: areaatriumsso.dll entry (if it exists) and also comment out
all the native area plug-in related entries.
b. Modify the Server-Plugin-Alias entry for Atrium SSO (if it exists), from
Server-Plugin-Alias: ARSYS.AREA.ATRIUMSSO ARSYS.AREA.ATRIUMSSO
myServer:9999 to Server-Plugin-Alias: AREA AREA myServer:9999.
Note
Add the entry for Server-Plugin-Alias entry if it does not exist for Atrium
SSO.
2. Make the following changes in the pluginsvr_config.xml file:

a. Change the Atrium SSO plug-in entry from <name>ARSYS.AREA.ATRIUMSSO</
name> to <name>AREA</name>.
3. Restart the AR System server and the Java plug-in server.
Note
For more information about Atrium SSO integration, see Configuring BMC Atrium
SSO integration.
Using the C plug-in server for dynamic plug-in loading

Plug-ins are configured in the ar.cfg file. A new plug-in is added to the plug-in server through the
AR System server. Previously, adding a new plug-in definition required that you stop and restart the
AR System server. An API interface in the plug-in server can add the new plug-in definitions
dynamically, without stopping and restarting the AR System server.
See the plug-in server configuration file ( ar.cfg or ar.conf).
Page 932 of 4705
Home
To add the plug-in information to the C plug-in server configuration file

1. Double-click the driver.exe file.
The default location of this file is C:\Program Files\BMC Software\ARSystem\Arserver\api
\driver.
2. Enter the required login and server information.
3. Enter the gsi (Get Server Info) command to get the current plug-in information.
4. Enter the following details:
Number of server info operations--The number of servers for which you want the
current plug-in information.
Operation--The operation number for getting the current plug-in information that is
present in the ar.cfg file.
A list of current plug-ins is displayed.
5. Enter the ssi(Set Server Info) command to add the new plug-ins.
Note
If you enter the ssi command without entering the gsi command first, the old
plug-in entries are overwritten and only the new entries are recorded.
6. Enter the following details:

Number of server info operations--The number of servers for which the new plug-ins
are to be added.
Operation--The operation number for adding the new plug-ins.
Datatype--The number for the type of data.
A list of new plug-ins that are added is displayed. The value for the ReturnCode must
be OK.
The plug-in information is now updated in the ar.cfg file.
Using plug-in naming conventions

Plug-in names must be unique. BMC recommends the following naming format:
companyName.pluginType.uniquePluginIdentifierName
For example, if your company name is ACME , the type of plug-in is ARDBC , and the unique
plug-in identifier is pluginexample1, your plug-in name could be this:
ACME.ARDBC.pluginexample1
Page 933 of 4705
Home
Plug-in names cannot include spaces or tab characters. In addition, uniquePluginIdentifierName

cannot contain the word AREA by itself because that word is reserved for AREA plug-ins. However,
you can use the word AREA as the pluginType value.
Restarting the plug-in server using the Set Server Info command
When any changes such as C plug-in or Java plug-in-related changes, binary updates that take
place during installation, plug-in related updates to the ar.conf file, or changes to the
pluginsvr_config.xml file are done to the C plug-in or Java plug-in files, you are able to restart
only the plug-in server instead of restarting the AR System server.
To restart the plug-in server using the Set Server Info command
1. Double-click the driver.exe file. The file is located in the following path:
(Windows) <ARInstallationFolder>\Arserver\api\driver
(UNIX) <ARInstallationFolder>/bin
Note
On UNIX, set the LD_LIBRARY_PATH environment variable to the directory
where the arserver.exe is located. For example, export
LD_LIBRARY_PATH=/C:/Program Files/BMC Software/ARSystem/
bin.
2. To initialize, enter the init command.

3. To log on, enter the log command and provide details such as user name, password, and
server name. For more information about the driver.exe commands, see Using the driver
program from the command line.
4. If you are not using the port mapper, enter the ssp (Set Server Port) command and then
enter the server port number.
5. Enter 0 or a blank for Using private socket.
6. Enter the ver command to verify the login information.
7. Enter the ssi(Set Server Info) command and perform the following:
a. Enter 1 for the Number of server info operations that you want to perform.
b. Enter 348 as the Operation number to forcefully shut down the plug-in server.
c. Enter 2 for integer as the Datatype.
d. Enter 0 or 1 as the Integer Value.
Page 934 of 4705
Home
When the AR monitor detects that the plug-in server is down, it checks if any changes are made to
the ar.cfg file. If the changes are detected, the recent ar.cfg is loaded before the stopped plug-in
server is automatically restarted.
Overriding values from ar.cfg or ar.conf

In 7.6.04 and later installations, if a plug-in calls a load balancer (or another server) but you want
the plug-in to call a specific BMC Remedy AR System server, you can override values from the
ar.cfg (ar.conf) file. To do this, add values to the following options in the pluginsvr_config.xml file
.
<override_ar_server_host></override_ar_server_host>
<override_ar_server_port></override_ar_server_port>
<override_ar_system_user></override_ar_system_user>
<override_ar_system_password></override_ar_system_password>
For example, you might want the plug-in server to use MachineA on port 3814 and log in as
JoeUser with a password of pword123. Change the options as follows:
<override_ar_server_host>MachineA</override_ar_server_host>
<override_ar_server_port>3814</override_ar_server_port>
<override_ar_system_user>JoeUser</override_ar_system_user>
<override_ar_system_password>pword123</override_ar_system_password>
You might need only the host name and port numbers. (The user name and password
options are not always required.)
Creating Java plug-ins

The Java plug-in API includes an interface and an abstract class for each plug-in type. Your Java
plug-in program must implement one of the interfaces or extend one of the abstract classes.
Interface
Extends
ARDBCPluggable
ARPluggable
AREAPluggable
ARPluggable
Page 935 of 4705
Home
Interface
Extends
ARFilterAPIPluggable
ARPluggable
Abstract class
Extends
Implements
ARDBCPlugin
ARPlugin
ARDBCPluggable
AREAPlugin
ARPlugin
AREAPluggable
ARFilterAPIPlugin
ARPlugin
ARFilterAPIPluggable
The interfaces and classes are described in detail in the Javadoc-generated online documentation
in the arpluginsdoc.jar file. This file is located in the javaplugins subdirectory of the Api (or api )
directory in your AR System server installation directory. To access the Java plug-in API
documentation, unzip the contents of the file. (To unzip a JAR file, use a zip utility or the Java jar
executable, which is in the bin directory of the Java JRE is installation. For example, jar -xvf
arpluginsdoc.jar.) Then, navigate to the javadoc folder, and open the index.html file to see an
overview of the entire AR System Java plug-in API documentation.
About classes, instances, and shared data
Writing a Java plug-in
About classes, instances, and shared data

Two or more Java plug-in classes can be configured in a plug-in set or group as described in the
comments in the pluginsvr_config.xml file. When the Java plug-in server starts, it loads each
configured plug-in class or group in a separate class loader and any static initialization in the
classes is executed. It also initializes an instance of each plug-in class listed in the
pluginsvr_config.xml file for each worker thread in its worker thread pool. Each time the AR
System server makes a connection to the Java plug-in server, a selector thread adds the request
associated with the connection to a task queue. As soon as a worker thread is free, it processes the
next request in the task queue.
Different instances of a class can share data in the static class variables. To be thread safe,
however, the class implementation must protect this static data.
The class can use instance variables to store data that is not shared. Because each thread has a
separate instance, this data is thread safe.
Writing a Java plug-in

This topic explains how to write a Java plug-in.
To write a Java plug-in

1. Make sure your programming environment is set up correctly. You need:
Page 936 of 4705
1.
Home
Java Development Kit (JDK) 6 Update 17.

AR System Java plug-in API files. (See Installed plug-in components for installation
and verification.)
AR System Java API files. (See Installed plug-in components for installation and
verification.)
2. Create a Java project in your IDE.
3. Include the arpluginsvrVerNum.jar file in the AR System API library directory in the
CLASSPATH. (For the directory location, see Installed plug-in components.)
4. Create a new class that will implement one of the interfaces listed in Creating Java plug-ins,
or extend one of the abstract classes listed in that section.
5. Import the com.bmc.arsys.pluginsvr.plugins and com.bmc.arsys.api.* packages and
other packages, such as java.util.List, into your program.
6. Implement the methods of the interface or abstract class you are using. See the Java plug-in
API online documentation located at ARSystemServerInstallDir\ARserver\api\javaplugins
\arpluginsdocVerNum.jar for details, and consider these tips:
When implementing the init() and initialize() methods, do not put the plug-in into a
long loop to wait to connect to the AR System server or another server. Such loops
prevent the Java plug-in server from finishing its initialization. To determine whether
the plug-in has been instantiated inside the plug-in server, the plug-in server must
receive either a return from init() or initialize(), or an exception. If the plug-in server
learns that the method failed to instantiate the plug-in, it can still instantiate its other
plug-ins and complete its initialization. The failed plug-in, however, will be unable to
receive calls.
If a plug-in must perform a long process, such as establishing a database connection,
before the plug-in can accept a call, create a separate thread for the process so that
the init() and initialize() methods are not blocked. If the plug-in receives any call
other than init() and initialize() before it completes the process, the plug-in can
generate an ARException to notify the caller that it is not ready and to tell the caller
its current state. When it is ready, it can process the call.
To enable the Java plug-in server to load and instantiate all plug-ins inside the plug-in
server, a plug-in should not throw a runtime exception or an ARException from the
init() and initialize() methods for non-fatal errors.
7. Add an entry that identifies the plug-in to the plug-in server configuration file. See
Configuring the Java plug-in server.
8. If the Java plug-in uses native libraries:
Include the native libraries in the PATH variable. On UNIX only, include the native
libraries in the LD_LIBRARY_PATH (Solaris and Linux) or LIBPATH (AIX)
environment variable.
If the libraries need to know the remote host character set, call the
getRemoteHostCharSet() method of the ARPluginContext object. For details, see
the Java plug-in API online documentation located at ARSystemServerInstallDir\
ARserver\api\javaplugins\arpluginsdocVerNum.jar.
Page 937 of 4705
Home
Configuring the AR System server to access a plug-in server

To access a plug-in server, the AR System server needs its host name and port number. The
server searches for the host name and port number in this order:
1. The plug-in alias, if any.
2. The plug-in server entry on the Connection Setting tab of the AR System Administration:
Server Information form. (This entry is also required to set a password for a plug-in server.)
3. The local host and the port number specified by the Plugin-Port setting in the ar.cfg or
ar.conf file. (See Setting server passwords, RPC options, and plug-in timeouts .)
4. The port number that the plug-in server registered with the portmapper.
To access one C or Java plug-in server with no password running on the same computer as the AR
System server, only the Plugin-Port option in the ar.cfg or ar.conf file is required. To specify a
password for a plug-in server, an entry on the Connection Setting tab of the AR System
Administration: Server Information form is required.
To access two or more plug-in servers, for example, to access both the C and Java plug-in servers
or to access plug-in servers on two or more computers, define aliases for all plug-ins other than
those loaded by the primary plug-in server that is set up as described in the previous paragraph.
Defining plug-in aliases
Plug-in aliases scenarios
Defining plug-in aliases

You define plug-in aliases in the ar.cfg or ar.conf configuration file. Use this format:
Server-Plugin-Alias: aliasName realName hostName[:portNumber]
Parameter
Description
aliasName
Name referenced in BMC Remedy AR System applications. AR Filter API calls and vendor forms reference this
alias name. This is an arbitrary string, but it cannot include semicolons or blank-space characters, such as spaces,
tabs, or new lines.
realName
Actual name that the plug-in exposes to the plug-in server.
hostName
Name of the host the AR System server accesses to find the associated plug-in server.
portNumber
Port number the AR System server connects with when accessing the associated plug-in server. This is optional. If
you do not specify a port number, the Plugin-Port is used.
Plug-in aliases scenarios

Following are scenarios of how aliases affect the behavior of the AR System server when it
accesses plug-ins.
Page 938 of 4705
Home
In this topic:
Vendor form accessing the ARDBC plug-in scenario
Workflow accessing the ARF plug-in scenario
AR System server accessing the AREA plug-in scenario

Server-Plugin-Alias: RMDY.ARDBC.XML RMDY.ARDBC.XML myhost
A vendor form that accesses the ARDBC plug-in named RMDY.ARDBC.XML is redirected to the
plug-in by the same name on the plug-in server running on myhost.
Workflow accessing the ARF plug-in scenario

Server-Plugin-Alias: RMDY.ARF.PERL.myhost RMDY.ARF.PERL myhost
Workflow that accesses the ARF plug-in named RMDY.ARF.PERL.myhost is redirected to the
RMDY.ARF.PERL plug-in on the plug-in server running on myhost.

Server-Plugin-Alias: RMDY.ARDBC.LDAP.fred RMDY.ARDBC.LDAP
myhost:11001
A vendor form that accesses the ARDBC plug-in named RMDY.ARDBC.LDAP.myhost.1 is

redirected to the RMDY.ARDBC.LDAP plug-in on the plug-in server running on myhost and
listening at port number 11001.
AR System server accessing the AREA plug-in scenario

Server-Plugin-Alias: AREA AREA myhost
When the AR System server accesses the AREA plug-in, it connects to the plug-in on the plug-in
server that is running on myhost. Only one AREA plug-in can exist, so use the reserved name
AREA for the alias.
Running the plug-in server

The plug-in server is set up in the armonitor configuration to start automatically at system startup.
It stops and restarts with the rest of the AR System services controlled by armonitor, the AR
System UNIX daemon, or the Windows service.
Page 939 of 4705
Home
To start the plug-in server manually, run the pluginsvrstartup command in the pluginsvr directory
. This command file (pluginsvrstartup.sh for UNIX or pluginsvrstartup.bat for Windows) is
customized for your installation. To change command-line options, see Configuring the Java plug-in
server.
In this topic:
Logging plug-in information
Logging exceptions for calls to Java plug-ins
About C plug-in exception handling
Logging plug-in information

Plug-ins can write information to the plug-in server log file. C plug-ins can use the
ARPluginSetProperties function to call the plug-in log function:
typedef int (*AR_PLUGIN_LOG_FUNCTION)(
ARPluginIdentification asdfasdfasdfas *id,
int asdfasdfasdfasdfasdfaassdfasdfasdfasdfa logLevel,
char asdfasdfasdfasdfasdfaasdfasdfasdfasdfa *text);
Argument
Description
id
The plug-in type, name, and version.
logLevel
The log level to which the information applies:

AR_PLUGIN_LOG_OFF (10000) No plug-in messages are logged. (Some plug-ins may ignore this setting.
)
AR_PLUGIN_LOG_SEVERE (1000) Messages that report fundamental problems that prevent a plug-in
from working (for example, the inability to open a required resource during plug-in initialization).
AR_PLUGIN_LOG_WARNING (900) Messages that might be precursors to severe problems or identify
incorrect configuration settings (for example, for a bad configuration setting, a plug-in might log a warning and
reverts to a default value).
AR_PLUGIN_LOG_INFO (800) Messages that identify intermittent milestones or events that do not have
negative repercussions. This should not be used for information that is likely to occur frequently.
AR_PLUGIN_LOG_CONFIG (700) Messages that describe the current configuration settings of the plug-in.
AR_PLUGIN_LOG_FINE (600) Messages that identify the result of every decision made throughout
processing. This level, along with the FINER and FINEST log levels, is primarily used while resolving
problems.
AR_PLUGIN_LOG_FINER (500) Supporting data that supplements FINE messages.
AR_PLUGIN_LOG_FINEST (400) Messages that contain information to help users who have plug-in
source code in front of them. At this level, messages can reference internal function names or structures. (All
messages logged at higher levels should have meaning for users who might not have access to the source
code.)
AR_PLUGIN_LOG_ALL (100) All plug-in messages are logged.
You can specify a log level for each situation. This enables the plug-in to write different information to the log
file depending on the log level configured for the plug-in server The information is not written to the log file
unless the plug-in server log level is equal to or lower than the value of logLevel.
text
The message that is written to the plug-in server log file.
Page 940 of 4705
Home
The C plug-in log function has no return value.

Set the log level for the C-based plug-in server using the Plugin_Log_Level option in the ar.cfg or
ar.conf file or on the Log Files tab of the AR System Administration: Server Information form. For
more information, see Setting log files options.
Java plug-ins can log messages using the logMessage method of their ARPluginContext object.
See the Java plug-in API online documentation located at ARSystemServerInstallDir\ARserver\
api\javaplugins\arpluginsdocVerNum.jar for details.
The Java plug-in server uses the log4j utility. Set the log level and other logging configuration in the
log4j_pluginsvr.xml file. Comments in the sample file describe the log configuration options.
Logging exceptions for calls to Java plug-ins

When a run-time exception or an ARException class error occurs during a Java plug-in server call
to a Java plug-in, the following information is now recorded in the ARServerInstallDir\Arserver\Db\
arjavaplugin.log file:
The name of the plug-in
This name matches the name of the corresponding plug-in library registered in the Java
plug-in configuration file, pluginsvr_config.xml. For example, if the library is registered as <
name>ARSYS.ARF.WEBSERVICE</name>, the plug-in name in the log file is
ARSYS.ARF.WEBSERVICE.
The method that the server tried to call in the plug-in
(Runtime exceptions only) The exception stack trace
In addition, when a run-time exception occurs, users receive Error 8753: Error in plugin:
pluginName.
When an ARException occurs, users receive the usual message associated with the exception.
Note
When you restart the AR System server, the arjavaplugin.log might log warnings that look
similar to this:
2009-10-14 11:07:12,573 WARN pool-2-thread-1
com.bmc.arsys.pluginsvr.plugins.ARPluginContext (?:?) <ARSYS.ARF.REGISTRY>Null registry location
You can safely ignore these messages. If you want to use the Registry, then enter the
Registry location in the AR System Administration Console. For more information, see
Registering a web service.
Page 941 of 4705
Home
About C plug-in exception handling

Exception handling in the C plug-in server now produces a stack trace. The stack trace includes the
names of the operation, vendor, and plug-in library. It is written to the arerror.log file.

This section describes the calls or methods common to all plug-in types including:
Common C plug-in functions
Common Java plug-in methods
Warning
Plug-in operations run synchronously; that is, BMC Remedy AR System waits for a plug-in
to complete its processing before the server continues its processing. Thus, a badly
written plug-in can adversely impact BMC Remedy AR System performance and stability.
Plug-in developers must:
Maintain thread safety
Use minimal processing logic for optimal code execution
Implement only callback methods that are required or that have custom logic for a
given plug-in
Allocate or free resources appropriately to prevent resource leaks
Optimize any costly operation that must be performed (or data structures that must
be built) by employing a meaningful caching strategy.
Common C plug-in functions

The following C API functions are common to every type of plug-in:
ARPluginCreateInstance
ARPluginDeleteInstance
ARPluginEvent
ARPluginIdentify
ARPluginInitialization
ARPluginSetProperties
ARPluginTermination
In general, these functions use the same structure as other AR System C API functions. The
plug-in server calls the functions and provides the necessary input data. The plug-in accepts the
data, processes it, and returns the appropriate response data to the plug-in server.
Page 942 of 4705
Home
The following figure shows a typical sequence of calls that the plug-in server makes on a C plug-in.
C plug-in call sequence
For more information, see AR System plug-in API functions.
Common Java plug-in methods

The methods defined in the ARPluggable interface and the ARPlugin abstract class are common
to all plug-in types. For more information, see the Java plug-in API online documentation located at
ARSystemServerInstallDir\ARserver\api\javaplugins\arpluginsdocVerNum.jar.
Opening Knowledge Management System Configuration form

You can set the plug-in log level using the Knowledge Management System Configuration form.
To open the Knowledge Management System Configuration form

1. Select AR System Administrator Console > Application Administration Console >
Custom Configuration > Knowledge Management > Knowledge Management
Configuration > System Configuration.
2. Click Open. The System Configuration form appears.
Page 943 of 4705
2.
Home
Integrating with a directory service

This section describes how to configure and use the ARDBC and AREA LDAP plug-ins to integrate
BMC Remedy AR System with a directory service.
LDAP plug-ins in BMC Remedy AR System
Using the ARDBC LDAP plug-in
Configuring the ARDBC LDAP plug-in
Building BMC Remedy AR System forms for directory services
Using the AREA LDAP plug-in
ARDBC LDAP example - Accessing inetorgperson data
LDAP plug-ins in BMC Remedy AR System

Lightweight Directory Access Protocol (LDAP) provides a standard method for accessing
information from a central directory. A common use for LDAP is user authentication. After a user is
set up in the LDAP directory, he or she can use the same user name and password to log in to any
application that supports the LDAP protocol.
BMC Remedy AR System provides these LDAP plug-ins:
AR System Database Connectivity (ARDBC) LDAP Accesses data objects stored in a
directory service as if they were entries stored in a typical AR System form. You can search
for, modify, and create data in a directory service using this plug-in. You can also use the
data in workflow and to populate character menus and table fields. See Using the ARDBC
LDAP plug-in.
AR External Authentication (AREA) LDAP Authenticates AR System users against
external LDAP directory services. See Using the AREA LDAP plug-in.
Page 944 of 4705
Home
Using the ARDBC LDAP plug-in

The AR System Database Connectivity (ARDBC) LDAP plug-in enables you to access data from an
external LDAP system through vendor forms.
Vendor forms are BMC Remedy AR System objects that present external data as entries in an AR
System form. Using vendor forms and the ARDBC LDAP plug-in, you can view and manipulate
external LDAP data as if it were stored in the AR System database. See Integration considerations.
ARDBC LDAP plug-in requirements

When using the ARDBC LDAP plug-in, remember these facts:
The ARDBC LDAP plug-in uses the LDAP v3 protocol to issue requests to directory services
.
Attributes of directory service objects consist of either character data, integer data, or time
stamps. Attachments are not supported.
By default, all attributes have one value. Multivalued attributes are supported by a special
notation. See Specifying multivalued attributes.
LDAP does not support transactions. Consequently, when an object is created, modified, or
deleted, the change does not roll back if subsequent workflow in the AR System server
detects an error condition.
The distinguished name and password specified in the ARDBC LDAP configuration are used
to connect to any directory service referenced in LDAP search URLs.
Only server-based certificates are supported.
Configuring the ARDBC LDAP plug-in

You must configure the ARDBC LDAP plug-in before you create the vendor form used to access
user information in your particular LDAP server.
You configure ARDBC through parameters in the ar.cfg file and the properties of the vendor form.
To make configuration easier, the installation of the ARDBC LDAP plug-in adds these forms:
ARDBC LDAP Configuration A vendor form, using a separate plug-in, that reads and
writes to the ar.cfg file.
Configuration ARDBC A display-only form that uses filters to push values to the
Configuration ARDBC Form and, as a result, to the ar.cfg file.
Page 945 of 4705
Home
To configure the ARDBC LDAP plug-in

1. In the AR System Administration Console, click System > LDAP > ARDBC Configuration.
The ARDBC LDAP Configuration form opens in New mode.
ARDBC LDAP configuration form
2. In the Host Name field, enter one or more host names of the directory service from which
you want information for the vendor form. You can specify a space-separated list of host
names up to 255 characters long. Starting with the first host name in the list, BMC Remedy
AR System tries to connect to each server until it is successful.
If you use Secure Socket Layer (SSL), this host name should match the name for which the
server's certificate was issued.
3. In the Port Number field, enter a port number for this directory service. The default port
number is 389. (For an SSL connection, the default is 636.)
4. In the Bind User field, enter the distinguished name of the user account that the ARDBC
LDAP plug-in uses to log in to the directory service. The administrator who set up the LDAP
service designated this name. With the vendor form, some LDAP servers allow you to make
an anonymous connection. If you plan to use an anonymous connection, leave the Bind
User and Bind Password fields blank.
Otherwise, use a standard distinguished name such as cn=manager, dc=remedy, dc=com.
5. In the Bind Password field, enter the password for the user account. (For security, asterisks
replace the characters you enter for the password.)
If you leave the Bind Name and Password fields blank, you are connected anonymously.
6. To use a Secure Socket Layer (SSL) connection, select Yes in the Using Secure Socket
Layer field; otherwise, accept the default value No. If you select Yes, the Certificate
Database field becomes active, and you can enter a certificate database as described in
step 7. Because SSL requires additional setup in this form and outside BMC Remedy AR
System, you might first want to experiment without SSL and then add this option later.
7. In the Certificate Database field, enter the path to the directory containing the certificate
database file. Do not include the file name in the path.
To create a certificate database, see Enabling LDAP plug-ins to establish SSL connections
with LDAP servers.
8.
Page 946 of 4705
Home
8. In the LDAP Date-Time Formatfield, select the format to use to represent date and time to
LDAP servers.
Format
Value
Description
Example: 6 a.m. Sept

. 28, 2001
Generalized
Time
YYYYMMDDHHMMSSZ This format is recognized by all LDAP servers

, and it is recommended.
20010928060000Z
AD
Generalized
Time
YYYYMMDDHHMMSS.0Z This format is recognized only by Microsoft

Active Directory servers.
20010928060000.0Z
UTC Time
YYMMDDHHMMSSZ This is a historical format and does not indicate

the century. It is not recommended.
010928060000Z
For more information, see Configuring after installation.

9. In the Failover Timeout field, specify the number of seconds in which the directory service
must respond to the plug-in server before an error is returned. The minimum value is 0 (
which means the connection must be made immediately). The failover time-out cannot be
set higher than the value of the Server-Plugin-Default-Timeout parameter.
10. In the Directory Page Sizefield, enter the number of entries to return in a single page to the
client from the external directory server when a search request is processed.
Tip
Setting the Directory Page Size to 1000 can help improve your system's
performance while you design and create vendor forms.
11. In the Base DN For Discoveryfield, enter a base distinguished name to use instead of the
root distinguished name as the basis for obtaining the list of vendor tables.
Tip
Specifying a value in the Base DN For Discovery field can help improve your
system's performance while you design and create vendor forms.
12. In the ARDBC Plugin Cachebox, specify this ARDBC plug-in caching information:
a. In the Enable field, select Yes to enable ARDBC plug-in caching.
b. In the Time To Live field, specify how long data should be kept in the ARDBC plug-in
cache.
c. In the Maximum Sizefield, specify the maximum size of the cache.
Tip
Page 947 of 4705
c.
Home
Enabling the ARDBC plug-in cache can help improve your system's
performance at runtime.
13. Click Save.

The system updates the ar.cfg (ar.conf ) file with the parameters you specified in this form.
For more information, see Configuring after installation.
Building BMC Remedy AR System forms for directory services

This section describes the concepts and generic procedures involved in building vendor forms and
workflow in BMC Remedy AR System to access data stored in a directory service.
Organizing data in a directory service
Creating a vendor form to represent a collection of LDAP objects
Identifying objects uniquely
Supporting object creation
Improving ARDBC LDAP runtime performance
Organizing data in a directory service

Data in a directory service is organized differently from traditional database applications. Traditional
database applications organize data in tables that have a fixed number of columns. Each row in a
table represents a single entity and contains a value for each column in the table.
A directory service organizes data as a collection of objects. Each object is characterized by one or
more object classes that define the values, or attributes, that the object defines. In addition, objects
might be grouped into organizational units.
Because of these differences, there is no one-to-one mapping between rows/columns/tables and
objects/attributes/object classes. The following table shows relationships among directory service,
AR System, and typical database concepts.
Directory service
AR System
Database
Object class
Form
Table
Attributes
Field
Column
Object
Entry
Row
Page 948 of 4705
Home
Creating a vendor form to represent a collection of LDAP objects

A table in a database can be described as a collection of rows. The data associated with an AR
System form is described as a collection of entries.
A collection of objects in a directory service is similar to entries in a form or a collection of rows in a
table. When working with a directory service, you can use a standard LDAP search URL to
describe a collection of objects. An LDAP search URL looks something like this:
ldap://orangina/o=remedy.com??sub?(objectclass=inetorgperson)
This URL contains the components described in the following table.

URL
component
Description
ldap://
LDAP protocol
orangina
Directory service host name
o=
remedy.com
Search base name
sub
Search scope
In this case, sub indicates that the search applies to the entire subtree under the base name.
(objectclass=
Filter that selects the objects
inetorgperson
)
Note
Define the search URL to retrieve objects that inherit from a particular object class. Do not mix
unrelated objects (for example, people and computers). They might have different sets of attributes,
making the search difficult to manage and administer.
Note
The LDAP URL standard enables you to specify a list of attributes to be returned by the
search. This attribute list would ordinarily fall between the base name and search scope in
the URL. In the previous example, no attributes are listed because the LDAP plug-in
ignores the attribute list. Instead, you identify attributes in the field properties. See
Alternative method of adding a field to represent the uid attribute .
Each object selected by the LDAP search can be represented as an entry in a vendor form. You
use Developer Studio to create a vendor form and add fields to which you attach LDAP data.
By default, the AR System server returns the Short Description field (field ID 8) in a results list.
Page 949 of 4705
Home
Because vendor forms do not have a Short Description field, so you must define the fields that will
appear in the results list. Include the vendor form's key field in the results list so that each record is
uniquely identified. For more information, see Defining search results.
For general information about creating vendor forms, see Creating vendor forms.
For an example of how to create a vendor form for LDAP data, see ARDBC LDAP example Accessing inetorgperson data.
Identifying objects uniquely

BMC Remedy AR System uniquely identifies entries in a form through the Request ID field.
Objects in a directory service have an attribute called the distinguished name ( dn), which uniquely
identifies each object. An object's distinguished name often consists of one attribute or multiple
concatenated attributes. For example:
uid=abarnes,ou=People,o=remedy.com
BMC Remedy AR System Request IDs are 15 bytes maximum in length and are assigned by AR
System when the entry is created. Distinguished names, on the other hand, are often longer than
15 bytes. However, you can map distinguished names longer than 15 bytes to AR System Request
IDs.
When designing an BMC Remedy AR System form to access data stored in a directory service, you
must determine what attribute to use to distinguish one object from another.
Note
If you specify an attribute for the Request ID that resolves to an empty value for an object
in the directory service, you receive an ARERR (100) Entry ID list is empty message,
and no records are displayed in the client. If more than one record has the same value,
you retrieve data only for the first matching entry.
For example, in a typical system the dn attribute uniquely identifies objects defined by the
inetorgperson object class. You would create a field for User ID and associate both the Request
ID field and the User ID field with the dn attribute.
Note
Page 950 of 4705
Home
This is the only case where you should associate one attribute with more than one BMC
Remedy AR System field. Associating an attribute with more than one field might lead to
run-time errors or incorrect behavior.
Supporting object creation

This topic describes how to use the ARDBC LDAP plug-in to create objects in the directory service.
In this topic:
Creating an objectclass field
Specifying multivalued attributes
Generating and assigning a distinguished name
To support the creation of objects by using the ARDBC LDAP plug-in, you must perform the
following tasks:
Create an BMC Remedy AR System field that is associated with the objectclass attribute.
The objectclass attribute is a multivalue attribute.
Create a field (other than Request ID) associated with dn, and define workflow that assigns
a value to it. Although entries in AR System are uniquely identified by the Request ID,
objects in a directory service are uniquely identified by the dn (distinguished name) attribute.
Add any attributes that are required to your AR System form. Many object classes require
that you specify values for certain attributes. These are similar to required fields in AR
System.
Creating an objectclass field

objectclass is a multivalued attribute that describes all object classes from which an object inherits
. Each object class defines a set of attributes. If an object inherits from an object class, it can have
values for those attributes. An object can inherit from more than one object class; therefore, an
object can have values for all combined attributes.
When you create an object, you must specify all the object classes from which the object inherits.
You must add a character field to your form, attach this field to the objectclass attribute, and use
the multivalue attribute notation (see Specifying multivalued attributes).
Because all objects associated with an AR System form belong to the same object classes, you
can easily set the default value of the field to the object class list. For example, the default value for
the object class field associated with an inetorgperson object class is this:
top,person,organizationalperson,inetorgperson
Page 951 of 4705
Home
The inetorgperson class inherits from the top, person, and organizationalperson classes.
Because the value does not change for this field, you should make this field Read Only. You might
also want to make the field Hidden.
Specifying multivalued attributes

Most attributes in an object class are defined to support one value. Some attributes, however, can
have many values. For example, a "person" object includes a "telephone number" attribute that
allows you to specify many phone numbers. When this attribute is retrieved, the directory service
can return any number of telephone numbers as atomic values.
This differs from typical database applications and AR System, in which a column or field stores
only one value. To store two phone numbers in such applications, you must add a new column or
field to accommodate the additional data.
To resolve this difference between the two data models, use a special notation when specifying the
attribute name in the Field Properties window:
attributeName[*separatorString]
Values associated with attributeName are concatenated into a single value in AR System but
separated with separatorString. For example, to concatenate all values associated with the
telephoneNumber attribute and separate each value with a comma you would enter the following
as the attribute name in the Form Properties window:
telephoneNumber[*,]
You could then define workflow to extract, add, or modify values in the comma-separated list of
telephone numbers.
Generating and assigning a distinguished name

The distinguished name (dn) attribute is generally assigned a value through workflow. The
workflow takes one or more values and assembles the values for the dn attribute. After the dn is
assigned at creation, it typically does not change just as the Request ID does not change in an
entry under an AR System form.
This is done using a filter that executes on a submit operation. You define the filter to perform a Set
Fields operation. For more information about creating filters, see the Developing section.
Improving ARDBC LDAP runtime performance

You can improve your ARDBC LDAP runtime performance by using time-based queries and
caching.
Page 952 of 4705
Home
Using time-based queries

Time-based queries reduce the time it takes to search your directory service.
BMC Remedy AR System retrieves modifyTimestamp and whenChanged attributes from the
directory service. When creating a vendor form, add one of these fields to store a time stamp. In the
Advanced Search Bar, enter a query for records that meet your time-stamp criteria. For example,
use modifyTimeStamp >= "8/9/2007 4:00:00 PM" to consider only records modified after 4
:00 PM on 8/9/07.
This query is evaluated by the plug-in, which uses it to query the directory server so that it returns
only records modified after a specified time.
Using caching
The ARDBC LDAP plug-in uses client-side caching. Before a search request is sent to the directory
server, BMC Remedy AR System checks the cache to determine whether the same request was
made before. If an earlier request was cached, the search results are retrieved from the cache to
avoid running a new search on the server.
Use the ARDBC LDAP Configuration form to enable caching and to control caching by specifying
the maximum size of the cache and the maximum amount of time to keep an item in the cache.
Troubleshooting the ARDBC LDAP vendor form

If you have problems with your ARDBC LDAP vendor form, consider these tips:
Any field (except display-only fields) on the vendor form must reference an LDAP attribute
that exists in the specified context. For example, if you use MS Active Directories, the uid
attribute does not exist by default and should not be referenced in your vendor form. If you
specify invalid attributes, you might receive unexpected results on your searches.
If data is not being returned correctly, create a vendor form with only a Request ID and one
other field (referring to valid LDAP attributes). Test a search. If it works, continue adding
fields until you identify the one that does not work.
If any values are NULL, you receive ARERR (100) Entry ID list is empty, and no
records are displayed in the client.
If more than one record has the same value, you retrieve data only for the first
matching entry.
For most LDAP servers, dn is the attribute of choice for the Request ID. For MS
Active Directories, sAMAccountName is usually a good choice.
For optimal performance, set the Directory Page Size field to 1000.
If you configure the Base DN For Discovery field, the plug-in searches from this Base DN
rather than from the root DN. This offers better performance.
Page 953 of 4705
Home
Using the AREA LDAP plug-in

The AR System External Authentication (AREA) LDAP plug-in enables you to authenticate BMC
Remedy AR System users against external LDAP directory services. This section describes how to
configure the AREA LDAP plug-in and your AR System server to use LDAP authentication.
After you configure your AR System server, you configure AR System to use external
authentication processing. See Configuring authentication processing.
Configuring the AREA LDAP plug-in
Configuring AREA LDAP group search
Configuring AR System servers to use the AREA LDAP plug-in
Configuring the AREA LDAP plug-in

To configure the AREA LDAP plug-in, use the AREA LDAP Configuration form in the AR System
Administration Console. The settings you specify in the form are saved in the ar.cfg or ar.conf file.
BMC Remedy AR System supports multiple AREA LDAP configurations.
Note
The form is added to your system when you install the plug-in. If you did not install the
plug-in during installation of the AR System server, you can install it by rerunning the AR
System server installer and selecting the AREA LDAP plug-in installation option. See the
Installing section.
Before configuring the AREA LDAP plug-in, set up user and group information in an LDAP directory
service. Then, use the following procedure to enter the settings into the AREA LDAP Configuration
form.
To configure settings for the AREA LDAP plug-in

1. In the AR System Administration Console, click System > LDAP > AREA Configuration.
The AREA LDAP Configuration form appears.
AREA LDAP configuration form
Page 954 of 4705
Home
If any AREA LDAP adapters are configured for your AR System server, they are displayed in
the Configuration List at the top of the form. When BMC Remedy AR System attempts to
authenticate a user, it searches each LDAP adapter configuration in the list.
2. In the Configuration List, perform one of these actions:
To create a configuration, click Clear Fields. All fields in the form are cleared.
To modify a configuration, select it in the list. The fields in the form are populated with
data from that configuration.
3. In the Directory Service Informationsection, fill in (for new configuration) or change (for
modified configuration) the values in these fields:
Host Name Name of one or more servers on which the directory service is hosted*
.* You can specify a space-separated list of host names up to 255 characters long.
Starting with the first host name in the list, BMC Remedy AR System tries to connect
to each server until it is successful.
Port Number Number of the port on which the directory service is listening.
Bind User
Distinguished name for this configuration. The distinguished name is the name for
a user account that has read permissions and can search the directory service for
user objects.
Bind Password Password for the distinguished name specified for the Bind user.
Use Secure Socket Layer? Yes/No toggle field. To specify an SSL connection to
the directory service, select Yes to enable the Certificate Database field.
Certificate Database Name of the directory containing the certificate database file.
Failover Timeout Number of seconds in which the directory service must respond
to the plug-in server before an error is returned. Minimum value is 0 (connection must
be made immediately). This value cannot be higher than the value of the
External-Authenticaion-RPC-Timeout parameter.
Page 955 of 4705
Home
Chase Referral Yes/No toggle field. When the AREA LDAP plug-in sends a
request to a directory server, the server might return a referral to the plug-in if some
or all of the requested information is stored in another server. Attempting to chase the
referral by connecting to the other server can cause authentication problems. By
default, referrals are not chased. Yes enables automatic referral chasing by the LDAP
client. Noprevents referral chasing.
Note
This option is only for Microsoft Active Directory servers. Select No for all
other directory servers.
Important
BMC Remedy AR System does not support referrals that use a domain
name rather than a host name as a reference. When Active Directory
automatically configures referrals (such as when a trust or parent/child
domain relationship is created), it uses a domain name in the referral.
Therefore, such referrals do not work in BMC Remedy AR System even
when Chase Referral is set to Yes.
4. In the User and Group Informationsection, fill in or change the values in these fields:
User Base Base name of the search for users in the directory service (for example
, o=remedy.com ).
User Search Filter Search criteria for locating user authentication information. You
can enter the following keywords in this field. At run time, the keywords are replaced
by the values they represent.
$\USER$ Name of the user logging in (for example, uid=$\USER$ ).
$\DN$ Distinguished name of the user logging in.
$\AUTHSTRING$ Value users enter in the Authentication String field when they
log in.
$\NETWORKADDR$ IP address of the AR System client accessing the AR
System server.
Group Membership If this user belongs to a group, select Group Container;
otherwise, select None. When None is selected, the Group Base, Group Search Filter
, and Default Group(s) fields are disabled.
Group Base Base name of the search for groups in the directory service that
includes the user who is logging in
(for example, ou=Groups ).
BMC Remedy AR System performs a subtree search within the group you specify.
Page 956 of 4705
Home
Group Search Filter Search criteria for locating the groups to which the user
belongs. For the user's distinguished name, enter the keyword $\DN$ (for example,
uniqueMember=$\DN$ ). At run time, $\DN$ is replaced with the distinguished name.
Default Group(s) If the search finds no matching groups, the group specified in
this field is used.
5. In the Defaults and Mapping Attributes to User Information section, perform these actions
:
a. In the LDAP Attribute Name column, enter the corresponding LDAP attribute names
for the following AR System fields.
b. In the Default Value If Not Found In LDAP column, select or enter a default value for
each field if no value is found in the directory service.
License Mask Number for the license mask. The license mask specifies
whether the AREA plug-in overrides existing information from the User form for
write and reserved licenses. It also specifies which license types are
overridden by the value returned by the plug-in. Use a number from the
following table. An X in a license type column means that the value returned
from the plug-in overrides that license in the User form for the specified user.
License mask number
Overridden license types

Application
FTS
Reserved
Write
10
11
12
13
14
15
Write License Type of AR System license assigned to the user (Fixed,

Read, Floating, or Restricted Read).
Full Text Search License Type of FTS license assigned to the user.
Page 957 of 4705
Home
Reserved License License type to select for a reserved license.

Application License Name of the application license granted to the user.
Email Address Default email address for notifications sent to the user.
Default Notification Mechanism Notification method used in your
environment (none, alert, email, or default).
Roles List Name of the LDAP attribute that lists the user roles. For example
, the roledn attribute contains role definitions for some LDAP systems. Add
any default roles to the Default Value If Not Found In LDAP field.
6. Click Save Current Configuration.
The system updates the ar.cfg or ar.conf files with the parameters you specified in this form
.
7. (optional) To change the order in which BMC Remedy AR System searches the listed
configurations when attempting to authenticate a user, do this:
a. In the Configuration List, select the appropriate configuration.
b. Click one of these buttons:
Decrease Order Moves the selected configuration down in the
authentication attempt order.
Increase Order Moves the selected configuration up in the authentication
attempt order.
Note
For the changes to take effect, restart your AR System server.
To delete configurations for the AREA LDAP plug-in

1. In the AR System Administration Console, click System > LDAP > AREA Configuration.
The AREA LDAP Configuration form appears.
2. In the Configuration List, select the configuration to delete.
3. Click Delete Configuration.
The system removes the corresponding parameters from the ar.cfg or ar.conffiles.
Note
For the changes to take effect, restart your AR System server.
Page 958 of 4705
Home
Configuring AREA LDAP group search

In releases previous to BMC Remedy AR System 7.0, external authentication required that every
LDAP group to which a user belonged have a matching AR System group. If a user belonged to an
LDAP group without a matching AR System group, external authentication failed. Hence,
administrators had to create an AR System group for each LDAP group, and BMC Remedy AR
System searched for groups at only one level in the defined base group. Now, you can map LDAP
groups to AR System groups and ignore excess LDAP groups.
Mapping LDAP groups to AR System groups

This section explains how to map LDAP groups to AR System groups.
Note
For maximum benefit, map LDAP groups to AR System groups and ignore excess LDAP
groups (see Ignoring excess LDAP groups).
To map LDAP groups to BMC Remedy AR System groups

1. Open the AR System Administration: Server Information form, and click the EA tab.
2. Click in the Group Mapping table to add a row, and enter the names of the LDAP and BMC
Remedy AR System groups to map. Enter only one group name in each column.
Note
You can map many LDAP groups to a single AR System group. If you map a single
LDAP group to many AR System groups, BMC Remedy AR System uses only the
first mapping.
LDAP Group Mapping table on EA tab

Page 959 of 4705
Home
Ignoring excess LDAP groups

Formerly, a user was authenticated only when each LDAP group to which the user belonged
matched an AR System group. Now, you can configure BMC Remedy AR System to authenticate a
user when any single LDAP group to which the user belongs matches an AR System group. You do
this by specifying that BMC Remedy AR System ignore excess LDAP groups.
Note
For maximum benefit, ignore excess LDAP groups and map LDAP groups to AR System
groups (see Mapping LDAP groups to AR System groups ).
To ignore excess groups

2. In the Group Mapping box, select the Ignore Excess Groups check box.
Configuring AR System servers to use the AREA LDAP plug-in

To configure AR System servers to work with the AREA LDAP plug-in, use the EA (external
authentication) tab in the AR System Administration: Server Information form. External
authentication (including chaining) works only if you do the following in the EA tab:
Set External Authentication Server RPC Program Number to 390695
Select either Authenticate Unregistered Users or Cross Reference Blank Password or
both.
For more information, see Configuring authentication processing.
After you configuring your AREA LDAP plug-in and your AR System server, you configure AR
System to use external authentication processing. See Configuring authentication processing.
ARDBC LDAP example - Accessing inetorgperson data

This section contains a scenario of how to create a vendor form associated with a collection of
objects (using the inetorgperson object class) in an LDAP directory service and how to attach data
to it.
Note
You must install and configure your ARDBC plug-in before you can create a vendor to use
the plug-in. See Creating C plug-ins and Configuring the ARDBC LDAP plug-in.
Page 960 of 4705
Home

Creating the inetorgperson vendor form
Attaching fields to represent inetorgperson data
Defining a filter to generate a DN
Creating the inetorgperson vendor form

The inetorgperson object class is often present by default on some LDAP directory services, such
as iPlanet and OpenLDAP. To use the example in this section if your LDAP service does not
contain the inetorgperson object class, replace the objectclass filter in the inetorgperson vendor
form. The data that corresponds to your new object class should contain the following attributes:
uid, sn, dn, cn, ou, and objectclass. Instructions about how and when to change the objectclass
file are presented later in this section. The form and workflow are provided with the LDAP plug-in
software distribution in the inetorgperson.def file, typically found in the <
ARSystemServerInstallDir>\Plugins\ARDBC folder.
Note
The inetorgperson vendor form, that is installed by default, is a sample vendor form with
default vendor information. The vendor information needs to be configured for a specific
environment before the form can be used. The default data is just a placeholder and will
not work.
To create a vendor form using the inetorgperson object class

1. Start Developer Studio and log in to an AR System server.
2. From the AR System Navigator list, expand All Objects.
3. Double-click Forms.
4. From the forms list, open the default sample form, inetorgperson, which is a Vendor form.
The Vendor Form and data are displayed.
5. Adjust any of the fields as needed to configure the vendor information for your
implementation.
Note
The corresponding URL for inetorgperson is:
ldap://LDAPDirectoryServiceHost/o=remedy.com??sub?(objectclass=
inetOrgPerson).
If you are using Microsoft Active Directory, then the URL for inetorgperson is:
ldap://LDAPDirectoryServiceHost:3268/DC=ad,DC=internal??sub?(objectclass=
user).
Page 961 of 4705
Home
If your LDAP server does not contain the inetorgperson object class, select a
comparable objectclass, such as person.
6. Click File > Save to save the vendor form.

7. To add or delete fields from a vendor form:
To add a field to the vendor form, select Form > Add Fields from tableName. Select
a field to add from the Add Fields dialog box, and click OK.
To delete a field from the vendor form, click a field and select Edit > Delete. Deleted
fields are returned to the Add Fields list for later access, if needed. This only deletes
the AR System field. It does not remove the column from the database table.
Attaching fields to represent inetorgperson data

After you create a vendor form, you populate the form with fields that contain data from your
inetorgperson data source. This section describes how to add a field to represent the uid (User ID)
in the inetorgperson example.
To add a field to represent the uid attribute in the inetorgperson scenario

1. In Developer Studio, open the vendor form you created earlier.
2. Right-click in the form and choose Add Fields from tableName.
The tableName variable is the object represented by ldap://LDAPDirectoryServiceHost/o=
remedy.com??sub?(objectclass= inetorgperson).
3. In the Add Fields dialog box, select a field to add and click OK.
4. Position the field on your form, as required.
5. Select the field to display its properties in the Properties tab.
6. In the Properties tab, expand the Vendor Information category (see the following figure).
Field Properties tab--vendor information
Page 962 of 4705
Home
7. Change the value of the Column property to uid.

8. Click File > Save.
You can also define an attribute to support more that one value. For more information on
multivalued attributes, see Specifying multivalued attributes.
Alternative method of adding a field to represent the uid attribute

1. Open the form where you want to add a field.
2. Add a character field to the form by choosing Form > Create a New Field > Character.
3. Select the field to display its properties in the Properties tab.
4. In the Properties tab, expand the Display category (see the following figure).
5. Change the value of the Label property to User ID.
Field Properties tab--display information
Page 963 of 4705
Home
6. In the Properties tab, expand the Database category.

7. Change the value of the Entry Mode property to Required.
8. In the Properties tab, expand the Vendor Information category.
9. Change the value of the Column property to uid.
10. Position the field on your form, as required.
Defining a filter to generate a DN

In the inetorgperson example, an object's distinguished name looks something like this:
*uid=abarnes, ou=People, o=remedy.com*
The following procedure shows how to create an AR System filter to assemble the distinguished
name using the inetorgperson example.
To define an AR System filter to construct the distinguished name using the inetorgperson
scenario
1. In Developer Studio, choose File > New > Filter.
2. Select the server where you want to create the filter, and click Finish.
3. Right-click the Associated Forms panel, then choose Expand All Panels.
4. In the Associated Forms panel, click Add.
5. In the Form Selector dialog box, select the inetorgperson form and click OK.
6. In the Execution Options panel, select the Submit check box.
7.
Page 964 of 4705
Home
7. Right-click the If Actions panel, then choose Add Action > Set Fields.
A Set Fields subpanel appears, which includes a field-value table (see the following figure).
8. Click the first cell in the Field column, then click the ellipsis button (...)
9. Use the Field Selector to choose the Distinguished Name field, then click OK.
10. In the corresponding Value cell, type the following expression:
"uid=" + $User ID$ +
", ou=People, o=remedy.com"
Creating the inetorgperson filter


12. Name your filter inetorgperson:create, then click OK.
Fields used in the inetorgperson scenario

In the inetorgperson scenario, the following fields are needed:
Field
Field properties
Distinguished
Name
Entry Mode: Optional Read/Write Default Value: none Vendor Information Column: dn
Object Class
Entry Mode: Required Read Only Default Value: top, person, organizationalPerson, inetorgperson Vendor
Information Column: objectclass[,]*
Last Name
Entry Mode: Required Read/Write Default Value: none Vendor Information Column: sn
Common
Name
Entry Mode: Required Read/Write Default Value: none Vendor Information Column: cn
Organization
Unit
Entry Mode: Required Read/Write Default Value: People Vendor Information Column: ou[,]*
In this scenario, the form looks like the form in the following figure.
The inetorgperson form
Page 965 of 4705
Home
AR System external authentication

You can use plug-ins and the AR System External Authentication (AREA) API to integrate BMC
Remedy AR System with external user authentication services. In addition, you can configure BMC
Remedy AR System to use a combination of internal and external authentication, including
OS-based authentication.
Enabling AREA authentication
Configuring authentication processing
Setting up the AREA hub
Enabling FIPS support for BMC Atrium SSO
Enabling AREA authentication

You use the AREA API to create an AREA server, which mediates between the data source and
BMC Remedy AR System. (The AREA API is installed with the AR System C API.) The AR System
server provides the name, password, and IP address in a remote call to the AREA server, which
validates the name and password and then passes the account information back to the AR System
server. The AR System server combines the account and user schema information.
Page 966 of 4705
Home
Implementing AREA authentication

1. Create a library (.dll or .so) to handle AREA API calls. See these sections:
Creating C plug-ins
2. Link to the AREA library.
3. Install the AREA library on the computer or computers that contain the AR System server.
4. Configure the AR System server to use external authentication. See Configuring
authentication processing.
Installing the sample AREA LDAP plug-in

BMC Remedy AR System includes a sample AREA LDAP plug-in. It is installed during installation,
if you select the AR System Server option.
For information about configuring the plug-in, see Configuring the AREA LDAP plug-in .
Specifying AREA plug-in server settings

For information about configuring your AR System server to work with the AREA LDAP plug-in, see
Configuring AR System servers to use the AREA LDAP plug-in .
Configuring authentication processing

To authenticate users, BMC Remedy AR System can use internal (User form) authentication,
external authentication, or a combination of the two. If you use a combination, you can specify the
order in which each type of authentication is attempted.
Specifying internal and external authentication
Authenticating unregistered users
Cross-referencing blank passwords
Specifying authentication chaining mode
Determining AREA behavior
Specifying internal and external authentication

By default, BMC Remedy AR System attempts to authenticate users internally. In all cases, if the
user and password match a record in the User form, authentication succeeds. Similarly, in all cases
, if the user and password do not match a record in the form, authentication fails.
To use external authentication, select one of the following options in the EA tab in the AR System
Administration: Server Information form:
Page 967 of 4705
Home
Authenticate Unregistered Users If a user is not in the User form, BMC Remedy AR
System tries external authentication. See Authenticating unregistered users.
Note
If the user group information is returned through external authentication, you
cannot be a part of any administrator group. You can be a part of the administrator
group only from the User form.
Cross Reference Blank Password If a user does not provide a password, BMC Remedy
AR System tries to cross-reference the user with an external source. See Cross-referencing
blank passwords.
Important
To use external authentication, you must set the External Authentication Server RPC
Program Number field to 390695.
Authenticating unregistered users

When the Authenticate Unregistered Users option is selected, BMC Remedy AR System first
attempts to find the user in the User form. If the user exists in the User form, BMC Remedy AR
System attempts authentication through that form. If the user does not exist in the User form, BMC
Remedy AR System attempts authentication through the AREA plug-in.
Note
You cannot get admin group information from the user's group list if the user is returned
through external authentication. You can get admin group information only from the User
form.
To authenticate unregistered users

2. In the External Authentication Server RPC Program Number field, enter 390695.
3. Select the Authenticate Unregistered Users check box.
Page 968 of 4705
Home
Cross-referencing blank passwords

When the Cross Reference Blank Password option is selected, BMC Remedy AR System attempts
to authenticate through the User form if the user provides a password. If the user and password
match a record in the User form, the user passes authentication. If the user does not provide a
password, BMC Remedy AR System attempts to cross-reference the user with an external system
through the AREA plug-in.
To cross-reference blank passwords

2. In the External Authentication Server RPC Program Number field, enter 390695. For
information about authentication behavior for 390695 RPC program number, see AREA
behavior when the RPC program number is 390695 .
3. Select the Cross Reference Blank Password check box.
Specifying authentication chaining mode

You can specify the order in which internal and external authentication methods are attempted by
specifying a value for the Authentication Chaining Mode field.
When Authentication Chaining is enabled, all authentication methods in the chain are attempted in
the specified order until either authentication succeeds or all the methods in the chain fail.
To set the authentication chaining mode

2. In the External Authentication Server RPC Program Number field, enter 390695.
3. Select Authenticate Unregistered Users, Cross Reference Blank Password, or both.
4. From the Authentication Chaining Mode list, select one of these values:
Mode
Description
Off
Disables authentication chaining.
ARS - AREA
BMC Remedy AR System attempts to authenticate the user by using the User form and then the AREA
plug-in.
AREA - ARS
BMC Remedy AR System attempts to authenticate the user by using the AREA plug-in and then the
User form.
ARS - OS -
BMC Remedy AR System attempts to authenticate the user by using the User form, then Windows or
UNIX authentication, and then the AREA plug-in.
AREA
ARS - AREA
- OS
BMC Remedy AR System attempts to authenticate the user by using the User form, then the AREA
plug-in, and then Windows or UNIX authentication.
Note
Page 969 of 4705
Home
Ensure that you configure the Pluggable Authentication Module (PAM)

configuration file on the UNIX system for OS authentication to work. Create a file
auth in the /etc/pam.d folder. The file contains the authentication parameters and
security settings specific for UNIX system, for example:
#%PAM-1.0
auth required pam_unix.so
Note
BMC Remedy AR System behaves differently depending on the authentication
chaining mode you choose and other external authentication parameters you
specify. See Determining AREA behavior.
Note
If you use the AREA hub, the authentication chaining mode treats it like a single
plug-in, and plug-ins installed in the AREA hub are considered in sequence until a
valid response is returned. See Setting up the AREA hub.
Determining AREA behavior

Several factors affect how BMC Remedy AR System authenticates users, including these:
Whether Authenticate Unregistered Users is selected
Whether Cross Reference Blank Password is selected
The value of the External Authentication Server RPC Program Number field
Whether the user exists in the User form and, if so, whether a password exists for the user
The following sections describe BMC Remedy AR System authentication behavior for given
configurations.
AREA behavior when the RPC program number is 390695

These tables show BMC Remedy AR System authentication behavior for this configuration:
Authenticate Unregistered Users is selected
Cross Reference Blank Password is selected
Page 970 of 4705
Home
External Authentication Server RPC Program Number is 390695
User does not exist in User form

Authentication
chaining mode
Authentication behavior
Off
Authentication is performed using AREA LDAP. User information is retrieved from AREA LDAP.
ARS - AREA
Authentication is not performed using BMC Remedy AR System because the user does not exist in
the User form.
Authentication is performed using AREA LDAP. If successful, user information is retrieved from AREA
LDAP.
AREA - ARS
Authentication is performed using AREA LDAP. If successful user information is retrieved from AREA
LDAP.
the User form.
ARS - OS - AREA
the User form.
Authentication is performed using OS authentication. If successful, user information is retrieved from
the OS.
If OS authentication fails, user authentication is performed using AREA LDAP. If AREA LDAP
authentication is successful, user information is retrieved from AREA LDAP.
ARS - AREA - OS
the User form.
LDAP.
If AREA LDAP authentication fails, the user is authenticated using OS authentication. If OS
authentication is successful, user information is retrieved from the OS.
User exists with no password in User form

Authentication
chaining
mode
Off
Authentication is performed using AREA LDAP password. User information is retrieved from the User
form.
Authentication process stops when it fails using AREA LDAP.
ARS - AREA
Authentication is performed using AREA LDAP password. User information is retrieved from User form.
Authentication process stops when it fails using AREA LDAP.
AREA - ARS
Page 971 of 4705
Home
Authentication
chaining
mode
LDAP. If AREA LDAP configuration does not contain all the information in the form, missing information
is retrieved from the User_Cache.
If AREA LDAP authentication fails, authentication processing stops.
ARS - OS AREA
User authentication is performed using AREA LDAP. If successful, user information is retrieved from
authentication is successful, user information is retrieved from BMC Remedy AR System.
The user is never authenticated using User form.
ARS - AREA OS
User authentication is performed using AREA LDAP. If successful, user information is retrieved from
authentication is successful, user information is retrieved from BMC Remedy AR System.
The user is never authenticated using User form.
User exists with password in User form

Authentication
chaining mode
Off
Authentication is performed using the AR System User Form. If successful, user information is
retrieved from the User form.
If User form authentication fails, authentication is not attempted using AREA LDAP.
ARS - AREA
Authentication is performed using the AR System User form. If successful, user information is retrieved
from the User form.
If User form authentication fails, AREA LDAP authentication is attempted. If AREA LDAP authentication
is successful, user information is retrieved from AREA LDAP.
AREA - ARS
LDAP.
If AREA LDAP authentication fails, authentication is attempted using User form. If User form
authentication is successful, user information is retrieved from the User form.
ARS - OS AREA
from the User form.
If BMC Remedy AR System authentication fails, OS authentication is attempted. If OS authentication is
successful, user information is retrieved from the OS.
If OS authentication fails, AREA LDAP authentication is attempted. If AREA LDAP authentication is
successful, user information is retrieved from AREA LDAP.
ARS - AREA OS
Page 972 of 4705
Home
Authentication
chaining mode
from the User form.
If BMC Remedy AR System authentication fails, AREA LDAP authentication is attempted. If AREA
LDAP authentication is successful, user information is retrieved from AREA LDAP.
If AREA LDAP authentication fails, OS authentication is attempted. If OS authentication is successful,
user information is retrieved from the OS.

These tables show BMC Remedy AR System authentication behavior for this configuration:
Authenticate Unregistered Users is selected
Cross Reference Blank Password is selected
External Authentication Server RPC Program Number is 0
User does not exist in User form

Authentication chaining
mode
All Authentication chaining
modes
Authentication is performed using OS authentication. If successful, user information is

retrieved from the OS.
If OS authentication fails, authentication processing stops.
User exists with no password in User form

Authentication chaining
mode
All Authentication chaining
modes
Authentication is performed using OS authentication. If successful, user information is

retrieved from the User form.
If OS authentication fails, authentication processing stops.
User exists with password in User form

Authentication
chaining mode
Off
from the User form.
If BMC Remedy AR System authentication fails, authentication processing stops.
ARS - AREA
from the User form.
If BMC Remedy AR System authentication fails, OS authentication is attempted. If OS authentication
is successful, user information is retrieved from the OS.
Page 973 of 4705
Home
Authentication
chaining mode
AREA - ARS
Authentication is performed using OS authentication. If successful, user information is retrieved from
the OS.
If OS authentication fails, User form authentication is attempted. If BMC Remedy AR System
authentication is successful, user information is retrieved from the User form.
ARS - OS Authentication is performed using the AR System User form. If successful, user information is retrieved
AREA
from the User form.

ARS - AREA Authentication is performed using the AR System User form. If successful, user information is retrieved
from the User form.
OS

Setting up the AREA hub

The BMC Remedy AR System plug-in server supports only one AREA plug-in directly. You can,
however, add a single AREA Hub plug-in to the plug-in server and then add multiple AREA plug-ins
to the AREA Hub plug-in. Plug-ins you add to the AREA Hub are referred to as Hub-plug-ins. The
AREA Hub propagates the calls it receives from the Hub-plug-ins to the Plug-in server.
The AREA Hub loads the Hub-plug-ins in the order in which they appear in the ar.cfg or ar.conf file
. That is, the first entry the AREA Hub finds in the ar.cfg file is the first plug-in loaded, the second
entry the second, and so on.
Notes
You do not need to configure the AREA Hub manually to use multiple AREA LDAP
plug-ins. See Configuring the AREA LDAP plug-in .
The AREA hub works only with DLLs. Java plug-in server has an inbuilt capability
to chain across multiple Java AREA plug-ins. So, you do not need AREA hub for
Java. You can configure multiple AREA Java plug-ins in pluginsvr_config.xml
To set up the AREA hub plug-in

1. Create the following entry for the AREA hub in the ar.cfg file:
Plugin: areahub.dll
Page 974 of 4705
1.
Home
Note
Make sure this is the only entry for an AREA plug-in in your ar.cfg file.
2. Create an entry for the first AREA plug-in as follows:
AREA-Hub-Plugin: my_area_plug-in.dll
3. If necessary, create entries for subsequent AREA plug-ins as follows:
AREA-Hub-Plugin: my_area_plug-in_1.dll
4. Restart the AR System plug-in server.
Note
For information about restarting the plug-in server, see Restarting the plug-in
server using the Set Server Info command .
Enabling FIPS support for BMC Atrium SSO

BMC Atrium Single Sign-On (SSO) integration is Federal Information Processing Standards (FIPS140) compliant. When you have integrated BMC Atrium SSO with BMC Remedy AR System and
you have enabled FIPS-140 mode in BMC Atrium SSO, you must follow the steps provided in this
topic for completing the integration successfully.
To provide FIPS support

1. In a text editor, open the armonitor.cfg file (Windows) or the armonitor.conf file (UNIX).
Windows: ARSystemServerInstallDir\Conf\armonitor.cfg
UNIX: /etc/arsystem/serverName/armonitor.conf
2. Update the following line
D:\Program Files\Java\jre6\bin\java" -Xmx512m -classpath

"D:\ARSystem\pluginsvr;D:\ARSystem\pluginsvr\arpluginsvr7604_build
002.jar" com.bmc.arsys.pluginsvr.ARPluginServerMain -x iBMC-66R37BS -i
"D:\ARSystem" -m
Page 975 of 4705
Home
and add the -Datsso.sdk.in.fips140.mode=true parameter as follows:
D:\Program Files\Java\jre6\bin\java"
-Datsso.sdk.in.fips140.mode=true -Xmx512m -classpath
"D:\ARSystem\pluginsvr;D:\ARSystem\pluginsvr\arpluginsvr81_build
002.jar" com.bmc.arsys.pluginsvr.ARPluginServerMain -x iBMC-66R37BS -i
"D:\ARSystem" -m
3. Save the file and close it.

You can now proceed with the integration of BMC Atrium SSO and BMC Remedy AR System. For
steps of integration, see Running the SSOARIntegration utility on the AR System server .
Data and database integrations

This section contains information about data and database integrations:
Creating vendor forms
View forms
SQL database access
ODBC database access introduction
Creating vendor forms

In this topic:
Vendor forms introduction
To create a vendor form using an ARDBC plug-in
Vendor forms introduction

Vendor forms are BMC Remedy AR System objects that let you view and process external data
using BMC Remedy AR System processes and workflow.
Vendor forms allow AR System to present data from external sources as entries in an AR System
form. When you create a vendor form, you can request a list of candidate forms or fields (preferred
method) or you can enter the information yourself.
Vendor forms require you to have an ARDBC plug-in installed and configured. The ARDBC plug-in
and the plug-in server handle data exchange between BMC Remedy AR System and the external
data source. The AR System server maps the external data to fields in the vendor form, and the
form displays the data. See ARDBC plug-ins introduction.
You can use vendor forms to do the following tasks:
Page 976 of 4705
Home
Implement workflow on creation and modification of external data.

Execute escalations on external data.
Access external data to populate search style character menus or table fields.
You can create a vendor form after you have built and installed your ARDBC plug-in, and
configured your server to recognize it. For information about configuring your server to recognize a
plug-in, see the Configuring after installation section.
Note
Creating a vendor form for an ARDBC LDAP plug-in is a special case. See Creating a
vendor form to represent a collection of LDAP objects .
The vendor form can be manipulated as a regular form type with the following exceptions:
You can add only Required and Optional fields that correspond to actual columns in the data
source. In addition, you can add a Display Only field only when the column name does not
correspond to a column in the data source.
To create a vendor form using an ARDBC plug-in

1. In BMC Remedy Developer Studio, choose File > New > Vendor Form.
The New Vendor Form Wizard appears.
2. Select the server on which you want to create the vendor form, and click Next.
3. Select the ARDBC plug-in to use in the list of Available Vendor Names, and click Next.
4. Choose a table from the list of Available Vendor Tables and click Next.
Alternatively, type a table name in the Table field, click Validate, then click Next.
5. (optional) On the Field Selection page, choose a key column in the Key Field list box.
The key column uniquely identifies the entries in your vendor form. Key values are mapped
to the Request ID field on the Vendor Form.
6. In the Available Columns list on the Field Selection page, select columns to access in BMC
Remedy AR System. Use the arrow buttons to move them to the Selected Columns list.
New Vendor Form Wizard, Field Selection page
Page 977 of 4705
Home
7. Click Finish to create the vendor form.

8. Use Developer Studio to edit the new form, then click File > Save.
Note
For information on creating a join form using a vendor form, see Requirements for
creating a join form using a vendor form .
View forms
View forms enable BMC Remedy AR System to point to and access data in relational database
tables outside BMC Remedy AR System. The table can be located on the same database instance
or in any other database accessible from the current AR System database.
Page 978 of 4705
Home
Because view forms access data outside of BMC Remedy AR System, the developer must
understand the database data types and must have access to the external database table
containing the data. This section describes the requirements for using view forms and the data
types supported for each database.
Creating and modifying view forms
Database data types for view forms
Database requirements for view forms
Field properties on view forms
Setting up a remote database for view forms
Creating and modifying view forms

Use BMC Remedy Developer Studio to create and modify view forms.
In this topic:
Mapping an alternative AR System field type
Modifying view forms
The following procedure explains how to create a view form to connect to a database table.
To create a view form

1. If the database is remote, set it up as described in Setting up a remote database for view
forms.
2. In Developer Studio, choose File > New > View Form.
3. In the New View Form wizard, select the server on which you want to create the view form,
and click Next.
4. Enter the name of an existing database table to be associated with the view form (see the
following figure).
The formats for table names are as follows. Where two formats are given, the first is for a
table in the local database and the second for a table in a remote database:
DB2 TABLENAME
Use all capital letters when entering the table name because DB2 defaults to all
capital letters for the data in its system tables.
Oracle TABLENAME or OWNER.TABLENAME
Oracle defaults to all capital letters for data in its system tables. If the table name
uses lower case, make sure that the capitalization for the name is entered correctly.
Microsoft SQL Server TABLENAME or
LINKNAME.DATABASENAME.OWNER.TABLENAME
Sybase TABLENAME or DATABASENAME.OWNER.TABLENAME
Specify the owner as dbo if the current user is the owner of the table.
5.
Page 979 of 4705
Home
5. Click Load.
The Available Columns list box is populated with the database column names and default
AR System field type mappings for the supported data types.
New View Form wizard, View Form Properties page
6. In the Key Field list box, choose a column to designate as the key field.
You must choose either a character column with a name that contains 6 through 15
characters, or an integer column.
Warning
The selected column must be unique and non-null.
7.
Page 980 of 4705
Home
7. In the Available Columns list, select the columns to appear on the AR System form, and
use the arrow buttons to move them to the Selected Columns list.
This method maps the default AR System field type to the database data type. To use a
different AR System field type for a database column, do not select the column from the list
as described in this step. Instead, follow the steps in Mapping an alternative AR System field
type below.
8. Click Finish.
9. Use Developer Studio to make any additional changes to the new form, and then click File >
Save.
Mapping an alternative AR System field type

If necessary, you can map an AR System field type that is different than the default type to a
column in the external database.
To map an alternate field type to a database column in a view form

1. Create the view form as described in To create a view form, but in step 7, do not select the
column to which you want to map an alternate field type.
2. After saving the form, add a field of the appropriate type to the form.
3. In the field properties tab, expand the View Information properties.
4. Click the Columnproperty and type the database column name.
Warning
Do not create a form with multiple fields referring to a single column. Such a form
will produce adverse results and may generate SQL errors.
Modifying view forms

Use BMC Remedy Developer Studio to modify and delete fields from view forms.
To add a new field to a view form using the default field type
1. Choose Form > Add Fields From externalDBName from the menu.
2. Select the field to add from the Add Field dialog box, and click OK.
To delete a field from a view form

1. Click the field and choose Edit > Delete.
Deleted fields return to the Available Columns list box. This action does not remove the
column from the database table.
Page 981 of 4705
Home
Database data types for view forms

The following sections list the data types supported by each database for BMC Remedy AR System
field types in view forms. Developer Studio automatically maps the field types to corresponding
data types.
In this topic:
DB2 data type mapping for view forms
SQL Server data type mappings for view forms
Oracle data type mappings for view forms
Sybase data type mappings for view forms
Beginning with release 7.6.02, view forms support additional data types. This includes blobs (DB2
and Oracle) and images (Microsoft SQL Server and Sybase), which map to an attachment field,
and several date and time data types, which map to the Date, Time, or Date/Time field types as
shown in this section. (For view forms created in previous releases of AR System, Date/Time fields
that were mapped to an integer column are still supported.)
In some cases, you can map a different field type to a column type if appropriate for the data. See
Mapping an alternative AR System field type .
Note
When the data types nchar, nvarchar, or ntext are supported, they are used on Unicode
servers, and the char, varchar, and text data types are used on non-Unicode servers.
For information about the database column types used for AR System fields in regular forms, see
Database column types used for AR System fields .
DB2 data type mapping for view forms

The following data types are supported for view forms based on a DB2 database table:
DB2 data types
AR System field type
varchar, varchar2, char, nchar
Character (limited length)
clob
Character (unlimited length)
integer, smallint, decimal
Integer
real, double
Real
decimal
Decimal
date, Date
timestamp
Date/Time
Page 982 of 4705
Home
DB2 data types
time
Time
blob
Attachment field in attachment pool
SQL Server data type mappings for view forms

The following data types are supported for view forms based on a Microsoft SQL Server database
table:
Microsoft SQL Server data types
AR System field types
nchar,char, varchar
ntext,text
int, tinyint, smallint
Integer
real, float
Real
decimal
Decimal
datetime, smalldatetime
Date/Time (default), Date, Time
image
Oracle data type mappings for view forms

The following data types are supported for view forms based on an Oracle database table:
Oracle data types
varchar, varchar2, char, nchar
clob
number
Integer
float
Real
number
Decimal
date
Date/Time (default), Date, Time
blob
Sybase data type mappings for view forms

The following data types are supported for view forms based on a Sybase database table:
Sybase data types
varchar, char
text
int, tinyint, smallint
Integer
float, smallfloat
Real
Page 983 of 4705
Home
Sybase data types
decimal
Decimal
date
Date
datetime, smalldatetime
Date/Time
time
Time
image
attachment field in attachment pool
Database requirements for view forms

In this topic:
DB2 considerations for view forms
AR System requirements for view forms
Before creating a view form, identify the database table to use and verify that the following
requirements are met:
The database table must reside on, or be accessible to, the database that AR System is
using.
The ARAdmin user must have read and write access privileges on the database table.
The database table must have a column (field) that enforces non-null and unique values.
This column acts as the Request ID. If the administrator chooses a column that is not unique
or that allows nulls, data corruption might occur. The Request ID field must be an integer or
character field with 6-15 characters. Otherwise, the Key Field list is empty, and you cannot
create the view form. If the administrator chooses a character column for the Request ID,
then the field length must be the same as the column length.
You can use a view form to access BLOBs on a remote database, but not CLOBs.
Long columns (that is, text or clob ) must allow null values.
There are additional configuration requirements if the table to be used with the view form is on a
remote database. See Setting up a remote database for view forms .
DB2 considerations for view forms

For DB2 databases, you can connect only to database tables in the same DB2 database as the AR
System database.
To use view forms on a DB2 database, you must add the database's user name to the ar.conf (
ar.cfg ) file by using the Db-user option. For example, if the DB2 administrator's name is
db2admin, add the following line to the ar.conf (ar.cfg ) file:
Db-user: db2admin
For more information about the ar.conf (ar.cfg ) file, see the Configuring after installation section.
Page 984 of 4705
Home
AR System requirements for view forms

A view form can be manipulated as a regular form type with these exceptions:
You can add only Required and Optional fields that correspond to actual columns in the data
source. You can add a Display Only field only when the column name does not correspond
to a column in the data source.
After you attach an AR System field to a column in the database table, you cannot reattach
the field to a different column, but you can change other field properties.
Status history, diary, currency, and attachment fields are not supported on view forms.
You cannot change the type of a text field or change the length of any field after initial
creation.
BCE dates are not supported in date fields in a view form.
Field properties on view forms

Field properties on view forms are the same as the field properties of a regular form, with the
following exceptions:
The View Information category includes the following properties:
Table Indicates the link to the external database table. This field cannot be
modified.
Column Displays the column name on which the field was created. This field can
be modified, but it must be 254 characters or less.
If the column name does not represent a column in the data source, the field must be
display-only.
For example, assume you add a character field to a view form. The Column property shows
the column name as Character Field, which does not exist in the data source. To save the
form, you must change the Column property to match a column in the data source, or set the
Entry Mode property to Display.
If the column name represents a column in the data source, the field cannot be display-only.
You cannot change the data type of a character field on a view form. You can decrease the
input length of a character field, but this action does not alter the corresponding column in
the database. The input length should never be increased beyond its initial value.
Setting up a remote database for view forms

If the database table is in a remote database, you must perform the required database
configuration steps described in this section and use the correct table name syntax to access the
remote table. For databases that require you to create a database link or proxy database, refer to
your database documentation and work with the database administrator to configure access to the
remote database table.
DB2 Remote view forms are not supported for DB2.
Page 985 of 4705
Home
Oracle Set up a link between the AR System database and the Oracle database. Create
a view in the database user's schema which accesses this link (the user is ARADMIN by
default).
For example:
CREATE VIEW view_name AS (SELECT * FROM ownername.tablename@link)

Create the View Form on the view created above.
To enable the support of multiple remote Oracle databases with different character sets, you
must add the Oracle-Dblink-Character-Set parameter to your ar.cfg (ar.conf ) file. For
more information, see the Configuring after installation section.
Microsoft SQL Server Complete the following tasks:
Create a link to the remote database and either give the user ARAdmin an account
on the remote database or use the proper login credentials.
Turn on the Distributed Transaction Coordinator for both the local and the remote
databases.
Specify the following server configuration setting in the ar.conf (ar.cfg ) file:
SQL-Server-Set-ANSI-Defaults: T
This setting enables the DB-Library connection that AR System uses to use
ANSI-NULLs and ANSI warnings. There should be no impact on the performance of
the database. For more information about the ar.conf (ar.cfg ) file, see the
Configuring after installation section.
The format for the table name is:
LINKNAME.DATABASENAME.OWNER.TABLENAME
Sybase Create a proxy database. This is a Sybase database type that copies all the
metadata about a remote database to the local database but still allows queries to be
redirected to the remote database. For information about how to create a proxy database,
see the Sybase documentation.
The format to access the database table is:
DATABASENAME.OWNER.TABLENAME
SQL database access

Using SQL, third-party applications can read data from the BMC Remedy AR System database.
Similarly, both AR System client and server processes can read and write to external databases
using SQL.
Accessing BMC Remedy AR System data externally
Pulling data into BMC Remedy AR System with SQL
Pushing data from BMC Remedy AR System with SQL
SQL database considerations
Page 986 of 4705
Home
Accessing BMC Remedy AR System data externally

Any process that has permission to query the database engine can read BMC Remedy AR System
data. A third-party application writing to the BMC Remedy AR System database is not supported
because there is no way to ensure data integrity. In addition, external applications reading BMC
Remedy AR System data directly from the database are not subject to BMC Remedy AR System
permissions, nor do they trigger any BMC Remedy AR System workflow. If this is not acceptable,
data should be read through the BMC Remedy AR System API.
For more information about the AR System database, see Understanding the AR System database.
Pulling data into BMC Remedy AR System with SQL

To pull information from external tables, you can use the Set Fields action with the Read Value for
Field From field set to SQL. This allows you to send an SQL SELECT command to the database
and assign the return values to AR System fields.
Observe the following general rules for using SQL commands:
You need not use every value that is returned from the SQL command, but you must use at
least one.
You can use the same value in more than one field.
You can issue only one SQL command per action. You cannot enter two commands
separated by a semicolon and have both commands run. To run a set of commands, create
separate actions, or create a stored procedure and run that. (Stored procedures do not
return values.)
Turn on AR System server SQL logging to resolve problems with the SQL syntax if it returns
unexpected values or results. A good strategy is to start an SQL interpreter (for example, isql
for Sybase, SQL*Plus for Oracle, Command Center for DB2, or Query Analyzer for Microsoft
SQL Server) and to enter the same SQL command directly into the database to verify its
validity.
Because there is no error checking on the SQL statement, run the SQL statement directly
against the database (as a test) before you enter it into the SQL Command field. You can
then copy and paste the tested SQL command directly into the SQL Command field.
If the SQL operation fails, an AR System error message and the underlying database error
message appear.
For more information, see Set Fields action and structures.
Pushing data from BMC Remedy AR System with SQL

All three BMC Remedy AR System workflow components-active links, filters, and escalations-can
send data to external tables and even external databases using the Direct SQL action. The SQL
command must be created by the administrator and entered into the SQL Command field on the If
Action or Else Action tab. The AR System server performs no pre- or post-processing on the SQL
command or the results. The administrator must make sure that the command is correct. When the
Page 987 of 4705
Home
action is triggered, the AR System server passes the SQL command directly to the SQL database
server on which it is running. For more information about the Direct SQL action, see Direct SQL
action.
SQL database considerations

Consider the following issues when working directly with an SQL database:
The AR System server typically has full administrator access to the database for reading and
writing any data. AR System users have permissions to read and write specific data using an
AR System client, and these permissions are managed by the AR System server. If users
access the database directly through a database client, they are bypassing the AR System
security model.
BMC Remedy AR System stores some data in the database in formats that can cause
third-party applications to become confused. For example, AR System date/time fields store
values as timeticks, which are the number of seconds from 1 January 1970 at midnight until
the current time. These numbers are stored as integer numbers, and typically need to be
converted by the third-party application.
All SQL commands are sent to the database server that holds the AR System database. To
access databases that are external to this DB server, you must have the appropriate conduit
installed and issue the SQL commands needed to use the conduit for your SELECT
statement.
ODBC database access introduction

The Open Database Connectivity (ODBC) standard is a connectivity solution that enables ODBC
clients to communicate with BMC Remedy AR System. The AR System ODBC driver provides
read-only access to data defined in AR System forms. This section discusses the use of the AR
System Open Database Connectivity (ODBC) driver to provide additional functionality with other
programs.
ODBC is an SQL-based communication standard developed by Microsoft. The ODBC standard
represents a connectivity solution that enables ODBC clients to communicate with BMC Remedy
AR System. The AR System ODBC driver provides read-only access to data defined in AR System
forms.
The interface provided by the ODBC driver ( arodbc70.dll) is similar to that provided by the AR
System API. Like the API, the driver does not provide access to the underlying relational database.
Instead, as shown in the following figure, the driver communicates with the AR System server,
which in turn communicates with the database server. When using the ODBC driver, the AR
System access control model (user and group permissions) is maintained, and server-side workflow
is still triggered.
ODBC integration
Page 988 of 4705
Home
Many ODBC clients are available. The AR System ODBC driver provides extended functionality
with BusinessObjects Crystal Reports. In addition, the driver provides basic functionality with
Microsoft Access, Microsoft Excel, and other ODBC clients. See Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation for additional information about supported ODBC
clients.
BMC Remedy AR System ODBC considerations
Compatibility with ODBC clients
Creating an unqualified search in Microsoft Excel with BMC Remedy AR System
Creating multiple data sources
Integrating Crystal Reports with BMC Remedy AR System
Tips for using Microsoft Access with BMC Remedy AR System
BMC Remedy AR System ODBC considerations

Consider these issues when working with BMC Remedy AR System ODBC:
The BMC Remedy AR System ODBC driver is read-only. ODBC clients that create, modify,
or delete entries or tables do not function correctly with the AR System driver.
The BMC Remedy AR System ODBC presents BMC Remedy AR System join forms as a
single table, enabling you to search AR System join forms easily. However, in third-party
ODBC clients, such as Crystal Reports, you cannot run an SQL search that performs a join
directly through the SQL statement.
If you cannot create a BMC Remedy AR System join form for the data you need, it is
possible to create multiple BMC Remedy AR System data sources, connect to one AR
System table per data source, and then perform the join in your ODBC client.
Hidden form permissions are not enforced in the ODBC driver. Forms that are hidden from
the Mid Tier Object List are accessible for reporting to other tools using the BMC Remedy
ODBC driver.
If you use the BMC Remedy AR System ODBC Driver in MS Access to link tables, you might
encounter the following error: Cannot define field more than once. As a workaround,
select the Use Underscores during the DSN configuration. This option makes form and field
names adhere to SQL standards by removing spaces and other nonstandard characters.
To determine which fields are in conflict, you can enable ODBC Tracing and look through the
logs, or you can navigate through the Fields list in Developer Studio to see if there are fields
that meet the preceding conditions.
Page 989 of 4705
Home
When the ODBC driver accesses a currency field, it generates four or more column names
for the field by adding suffixes to the field name. The suffixes are:
_Date
_Type
_Value
_functional_currency_code
The driver creates one column for each functional currency code 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 will report "Cannot define field more than once" and fail 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.
Compatibility with ODBC clients

Many ODBC clients are available. The BMC Remedy AR System ODBC driver provides:
Multi thread-safe operation
Compatibility with ODBC version 3.5
Support for Unicode
Extended functionality with Crystal Reports 10.0 and XI, which enables you to create custom
reports with wide-ranging capabilities and provides additional flexibility in report design.
Basic functionality with Microsoft Access.
Basic functionality with Microsoft Excel.
For additional information about supported ODBC clients, see Compatibility matrix in the BMC
Remedy ITSM Deployment online documentation.
Creating an unqualified search in Microsoft Excel with BMC Remedy AR System

When you create an unqualified search for a diary field in Microsoft Excel, the data appears with
small control characters that appear as small boxes.
To remove the control characters

1. Highlight the cells and choose Data > Text to Columns.
2. Select the Delimited option, and click Next.
3. Click Treat Consecutive Delimiters as One.
4. Select Finish.
The diary field text data (not the time stamp) is removed with the control characters.
Note
Microsoft Excel has a date system that begins January 1, 1900. If your date field
contains a BC date, Microsoft Excel does not support it.
Page 990 of 4705
Home
Creating multiple data sources

By default, when you install the mid tier, or the ARWebReportViewer, the AR System ODBC driver (
arodbc70.dll ) is installed. The BMC Remedy AR System ODBC data source is configured with
your BMC Remedy AR System user name and password, and it accesses AR System with your
permissions. You can designate multiple data sources for one third-party tool; conversely, you can
use a single data source for several third-party tools.
For example, to run Crystal Reports with a browser, you must have the BMC Remedy AR System
ODBC driver on your machine. You could create a data source called Report User to access BMC
Remedy AR System through Crystal Reports. When you create this data source, you might specify
Joe User as the AR System user and supply Joe's password. When you use the Report User data
source to access BMC Remedy AR System through Crystal Reports, the BMC Remedy AR System
permissions are granted to Joe User. This enables you to set up data sources with multiple levels
of permissions.
To create additional ODBC data sources

1. Open the ODBC Data Source Administrator.
This utility is in different locations based on the version of Windows you use.
2. On the System DSN tab, select AR System ODBC Data Source, and click Add.
The Create New Data Source dialog box appears.
3. Select AR System ODBC Driver, and click Finish.
AR System ODBC Setup dialog box
4.
Page 991 of 4705
Home
4. In the Data Source Name field, enter a unique name for the data source.
5. In the AR Server field, enter the name of the AR System server to access with this data
source.
6. Enter a user name whose permissions will be used to access the report data.
7. Enter the user's password.
8. Select the Descending Diary Fields check box to designate reverse calendar order.
9. (Mid tier only) If the field or form names in your reports contain special characters, such as a
dot (.), hyphen (-), plus sign
, and semicolon (;) , select the Use Underscores check box
to replace the special characters with underscores.
Note
If you use Microsoft Access, spaces and hyphens are not allowed in object names.
10. To use field labels based on the locale you specify in the Report Locale field, select the Use
Labels check box. See Using field labels or database names in Crystal Reports .
Note
If the Verify On First Refresh option in Crystal Reports is selected, you must
match the state of the Use Labels option when you create the report and at run
time. For example, if you select the Use Labels option when you create the report,
you must select it when you run the report. If you clear the Use Labels option
when you create the report, you must clear it when you run the report. To avoid
problems caused by mismatched Use Labels options, it is recommended that you
clear the Verify On First Refresh report option in Crystal Reports.
11. (Mid tier only) In the Report Locale field, enter the locale for the language in which to
display the report.
Note
If you install two localized views (for example, German and French) and you use
the German localized view and the report locale setting is set to the French locale,
the data is returned in French, though the static report text is in German.
12. (Mid tier only) In the VUI Type field, enter 3 to specify that a web view should be used to
display reports for this data source.
13. Click OK.
Page 992 of 4705
13.
Home
Note
To modify an existing data source, select it in the ODBC Data Source
Administrator dialog box, and click Configure. The dialog box in the following
figure is displayed.
Integrating Crystal Reports with BMC Remedy AR System

The following procedure describes how to get started designing reports. See your Crystal Reports
documentation for complete instructions about using the design wizard to create reports.
Note
Before you start creating reports based on BMC Remedy AR System forms, make sure
that you follow the SQL standard for naming objects such as forms. For example, start the
form name with an alphabetic or underscore character. You should especially avoid using
a number (such as 2) for the name of a form. Otherwise you might see an error message,
such as ODBC error: Unexpected extra token: formName.

Using field labels or database names in Crystal Reports
Verifying fields defined in a Crystal Report
Changing the AR System ODBC configuration
Selecting report fields in Crystal Reports
Generating tables from multiple tables
Crystal Reports considerations
To create a report by logging on to BMC Remedy AR System from Crystal Reports

1. Open Crystal Reports and create a report.
2. In the Crystal Reports Gallery, select a wizard such as Standard.
3. In the Available Data Sources, select ODBC (RDO).
4. When the ODBC (RDO) dialog box appears, select the Data Source to log in to.
For example, select AR System ODBC Data Source as the default data source.
AR System ODBC Setup dialog box
Page 993 of 4705
Home
5. Enter the user's password.

6. To designate reverse calendar order, select the Descending Diary Fields check box.
7. Select the Use Underscores check box.
8. Specify whether to use field labels or database names to represent AR System fields.
Select the Use Labels check box to use field labels.
Clear the Use Labels check box to use database names.
See Using field labels or database names in Crystal Reports .
Note
Field labels are based on the locale specified in the Report Locale field.
9. Click OK to log in.

The AR System forms appear in the Standard Report Creation Wizard as data sources.
Selecting data sources in Standard Report Creation Wizard
Page 994 of 4705
Home
10. Select the form to include in your report, and click Next.
11. Click Next.
The wizard lists all fields in the underlying form.
Page 995 of 4705
Home
Selecting fields in wizard
Note
The content of the list of fields depends on whether you selected Use Labels in the
AR System ODBC Setup or AR System ODBC Login dialog box. See Using field
labels or database names in Crystal Reports .
When you select report fields, some fields might not be listed that are in your form. This
occurs when the field's database name is different from its display label. For example, a field
called Last Name in your form is not shown in the Database Fields list box in Crystal
Reports (the Database Fields list box appears in the following figure). Instead, the field
name Surname might appear. Each field in a form is identified by a unique database name,
not by the display label that appears in the form.
To identify a field's database name, open the form in Developer Studio, and open the Field
Properties dialog box for the field. The Name field of the Database tab in the Field
Properties dialog box shows the field's database name.
12. Optionally, select the fields to display in the report, and click Next.
The wizard now lets you specify how to group the information to display on your report.
13.
Page 996 of 4705
Home
13. Optionally, group the information, and click Next.

The wizard now lets you specify a subsection of the information to display on your report.
14. Optionally, select a subsection of information, and click Next.
The wizard now lets you specify a report template. To preview your report, click an available
template.
15. Select a template, and click Finish.
For more information about designing reports, see your Crystal Reports documentation.
Using field labels or database names in Crystal Reports

When you create a report in Crystal Reports, you select the AR System fields on which to report
from a list displayed by Crystal Report Designer. The AR System fields in the list are represented
by field labels (generated at the AR System view level) or database names (generated at the AR
System database level). You specify how to represent AR System fields in Crystal Report Designer
and your reports when you:
Set up the AR System ODBC as a data source for your report. See To create additional
ODBC data sources.
Important
BMC recommends that you use the same setting for setting up your AR System
ODBC and for creating your Crystal Report.
Create a report in Crystal Reports. See To create a report by logging in to AR System from
Crystal Reports.
Warning
If you report on two AR System fields that have the same label or two fields where
one field's database name matches another field's label, your report might contain
incorrect data.
If you specify using field labels, the list of fields in Crystal Report Designer displays field labels, if
any exist. If a field does not have a label, the list displays the database name for that field.
If you do not specify using field labels, the list of fields in Crystal Report Designer displays database
names for the fields.
Tip
Page 997 of 4705
Home
To identify a field's database name, open the form in Developer Studio, and then open the
Field Properties dialog box for the field. The Name field of the Database tab in the
FieldProperties dialog box shows the field's database name.
Verifying fields defined in a Crystal Report

When you create a report in Crystal Reports, you can select the Verify on Refresh option. When
this option is selected, Crystal Reports verifies fields defined in a report, which can be either AR
System field labels or database names, against the data source as it is configured at run time. If
you use this type of verification, Crystal Reports reports only on field names for which there are
matches between the report definition and the data source as it is configured at run time.
Changing the AR System ODBC configuration

If you change your AR System ODBC configuration (that is, toggle the Use Labels check box)
between the time you design the report and the time you run it and you verify report fields against
the AR System ODBC data source, your report might not contain the data you expect, and you
might receive a columns-not-found error.
Selecting report fields in Crystal Reports

When using an ODBC client to view BMC Remedy AR System data, some fields that are in your
form might not be listed. This occurs when the field's database name is different from its display
label.
Suppose, for example, a field in your form called Last Name is not shown in the Database Fields
list box in Crystal Reports. Instead, the field name Surname might appear. Each field in a form is
identified by a unique database name, not by the display label that appears in the form.
Tip
To identify a field's database name, open the form in Developer Studio. Select the field,
then expand the Database category on the Properties tab. The Name property displays
the database name.
To select the field

1. In the Create Report Expert dialog box, click the Fields tab.
2. From the Database Fields list, select the fields to include in your report, and click Add.
Alternatively, you can click Add All to include all the fields. To remove a field or all fields,
click Remove or Remove All, respectively.
3. Click Preview Report to view your report.
For information about designing reports, see your Crystal Reports documentation.
Page 998 of 4705
Home
Generating tables from multiple tables

Crystal Reports allows users to generate reports from multiple tables by joining the tables together
in an SQL statement external to BMC Remedy AR System. AR System ODBC Driver does not
support this capability. You can, however, achieve the same goal by creating an AR System join
form. After creating the join form, generate a report from it.
If you add two fields that have the same database name (such as Submitter) to a join form, one
field's database name appears as a field ID in Crystal Reports.
Crystal Reports considerations

Be aware of the following considerations and limitations when using Crystal Reports:
Converting Date/Time Strings to Date Strings In Crystal Reports, you can specify how
Date/Time strings are handled in your report. If you select the Convert to Date option in the
Reporting tab of the File Options dialog box, Date/Time strings from BMC Remedy AR
System are converted to Date strings in Crystal Reports.
However, if you set this option to convert Date/Time strings to Date strings, you cannot use
the select condition is equal (in the Select tab of the Create Report Expert dialog box in
Crystal Reports). The AR System Date/Time field works only with the Convert to String or
Keep Date-Time Type options.
List Sorting Selection fields from BMC Remedy AR System are treated as character
types. List sorting in Crystal Reports is based on display values (New, Assigned, Closed),
rather than numeric values (0, 1, 2) associated with an enumerated field. This occurs
because selection fields with AR_DATA_TYPE_ENUM data types are mapped to
SQL_CHAR data types when the BMC Remedy AR System ODBC driver is used. ODBC
does not have an equivalent data type.
Browsing Data The Browse Data button in the Fields tab of the Create Report Expert
dialog box in Crystal Reports does not display the Request ID (or other data) for all the
requests. (Do not select the Select Expert option because it attempts to perform an
unqualified search for all values in a field.)
Date Crystal Reports follows the calendar type from your operating system, typically the
Gregorian calendar starting from October 15, 1582. If the date field contains a BC date,
Crystal Reports does not support it.
Tips for using Microsoft Access with BMC Remedy AR System

This section includes tips for using Microsoft Access with BMC Remedy AR System.
Avoid using special characters (such as brackets, decimal points, hyphens, and spaces)
when naming tables and columns.
When you set up an ODBC driver for use with Microsoft Access, select the Use Underscores
check box. This check box is shown in AR System ODBC Setup dialog box .
Page 999 of 4705
Home
Table names that are nearly identical, such as My.Table and My Table (names that include
decimal points, hyphens, and spaces), are not differentiated by the driver.
Searching for data in these tables might produce unexpected results. Rename table and field
names that are nearly identical.
Maximum size of an entry or data set in Microsoft Access is 2K.
If you encounter the errors Record too large when using the Import Table option or This
form or report is based on a query that exceeds the limit for data in a single record
when using the Link Table option, you must exclude unnecessary fields from the search or
report. See your Microsoft Access documentation for additional information about excluding
fields.
Your Microsoft Access authorized signature and your AR System user name and password
might conflict.
If you notice that the tables or fields disappear (although you have access permissions)
when you work on reports, it is caused by a login identification conflict. To resolve this
problem:
Select the same user name and password that you use to log in to AR System.
Turn off the following flag in the Registry and set the value to 0:
HKEY_LOCAL_MACHINE\Software\Microsoft\Jet\3.5\Engines\ ODBC\TryJetAuth
When using Microsoft Access to link tables from an AR System ODBC data source, you
enter information into several dialog boxes. Do not select any options from the Select Unique
Record Identifier dialog box. Click OK to close that dialog box.
Extending BMC Remedy Developer Studio

Developer Studio is composed of Eclipse plug-ins, which are modules of code that perform various
functions. Some of these plug-ins have public extension points, which are ports through which they
expose their functionality to other plug-ins and indicate which class or method to call to use that
functionality. To add functionality to Developer Studio, you can create custom plug-ins with
extensions that hook into these extension points. Through these connections, custom plug-ins can
exchange API calls with Developer Studio and the AR System server.
Important
To create plug-ins for Developer Studio, you must be familiar with Eclipse plug-in
development (see http://www.eclipse.org) and Java (see http://www.oracle.com/
technetwork/java/index.html). Although BMC Customer Support is available to answer
questions about BMC plug-ins and APIs, it cannot provide help with general Eclipse and
Java issues that you encounter while developing custom plug-ins.
This section contains information about adding custom functionality to BMC Remedy Developer
Studio:
Page 1000 of 4705
Home
Creating plug-ins to extend BMC Remedy Developer Studio

Prerequisites for creating plug-ins
Extension points for BMC Remedy Developer Studio
Developer Studio Java API
Installation directory for the BMC Remedy Developer Studio plug-ins
Note
This feature does not apply to BMC Remedy AR System release 7.5.00 or earlier.
Creating plug-ins to extend BMC Remedy Developer Studio

Using the public Developer Studio plug-in extension points, you can create plug-ins that extend its
user interface as follows:
Add custom server object types to the All Objects list in AR System Navigator and to object
lists in the Object List tab. For example, the following figure shows an All Objects list that
contains a custom Hamburgers server object at the bottom of the list.
Customized All Objects list in AR System Navigator
When users double-click the custom object type, an object list for that type opens and
displays a list of objects supplied by the custom plug-in (see the following figure).
Customized object type in the Object List tab
Page 1001 of 4705
Home
To edit the custom objects, create a custom editor configured by the custom plug-in. In
Eclipse, register the editor for the custom object type.
Add custom items to context menus for servers in the AR System Navigator.
Customized server context menu in AR System Navigator
Add custom items to context menus for object lists. The items can appear on menus for a
specific object type or for all object types. For example, the following figure shows a context
menu for active links that contains the following custom actions: Enable Workflow, Disable
Workflow, and Set Execution Order.
Customized context menu for the Active Link object type
Add custom rules to Analyzer.

You can add rules for the Developer Studio Analyzer command by creating custom plug-ins
that connect to the Analyzer plug-in through its public extension point. (For general
information about Analyzer, see Using Analyzer to find problems in your applications .)
Page 1002 of 4705
Home
Prerequisites for creating plug-ins

To create plug-ins for BMC Remedy Developer Studio, you need the software and project
dependencies listed in this topic.
Software requirements for creating plug-ins

BMC Remedy Developer Studio release 7.6.02 or later
Java SE JDK 1.5 or later
Eclipse for RCP/Plug-in Developers (Ganymede 3.4 SR2 or later for Windows)
To download the Eclipse software, go to http://www.eclipse.org/downloads/packages/release
/ganymede/sr2.
Extract the downloaded ZIP file into C:\Eclipse3.4 (or later version).
Project dependencies for creating plug-ins

Add the following BMC Remedy Developer Studio plug-ins as dependencies to your custom plug-in
project:
com.bmc.arsys.studio.api (7.6.02 or higher)
com.bmc.arsys.studio.commonui (7.6.02 or higher)
com.bmc.arsys.studio.model (7.6.02 or higher)
com.bmc.arsys.studio.ui (7.6.02 or higher)
com.bmc.arsys.studio.analyzer.core (7.6.02 or higher)
To do this, extract the contents of the ARSystemServerInstallDir\ DeveloperStudio\files\
Plugins.zip file into your top-level Eclipse directory.
For example, if your top-level Eclipse directory is C:\eclipse, extract the contents into C:\eclipse.
Extension points for BMC Remedy Developer Studio

The BMC Remedy Developer Studio plug-ins provide these extension points:
Plug-in
Description
com.bmc.arsys.studio.model.modeltype
Registers new server object types with the AR System

Navigator. Examples of server object types are active links,
filters, and forms.
com.bmc.arsys.studio.model.modelprovider
Registers providers for new object types. For example, list

providers supply a list of objects and object providers supply
actual objects for editing. The providers can supply items to
both the AR System Navigator and the Object List tab.
com.bmc.arsys.studio.commonui.typeaction
Adds actions to context menus in the Object List tab for a

single object type. For example, see Customized context
menu for the Active Link object type.
com.bmc.arsys.studio.commonui.genericaction
Page 1003 of 4705
Home
Plug-in
Description
Adds actions to context menus in the Object List tab. The
actions can appear on menus for one or more object types.
com.bmc.arsys.studio.commonui.typeinformation
Registers new server object types with the user interface to

add the types to the AR System Navigator (see Customized
All Objects list in AR System Navigator) and the Object List
tab (see Customized object type in the Object List tab). It also
provides the name of the object type to display in the AR
System Navigator.
com.bmc.arsys.studio.analyzer.core.analyzerRules
Adds rules for the Developer Studio Analyzer command.
Developer Studio Java API

To incorporate additional functionality--such as information about AR System objects and workflow-into custom plug-ins, use the public Java API calls in the com.bmc.arsys.studio.model plug-in.
These calls are described in the Developer Studio Java API online documentation, which is in the
DevStudioInstallDir\files\DevStudioAPIdoc.zip file.
To access the documentation, unzip the file, and open the index.html file.
Installation directory for the BMC Remedy Developer Studio

plug-ins
To integrate a custom plug-in with BMC Remedy Developer Studio, put the plug-in's .jar file in the
ARSystemInstallDir\DeveloperStudio\plugins directory.
BMC Atrium Orchestrator integration

BMC Atrium Orchestrator (Atrium Orchestrator) enables IT organizations to automate tasks and
processes, such as trouble ticketing, fault management, performance monitoring, virtualization
management, and so on.
This section describes how to configure BMC Remedy AR System for integration with Atrium
Orchestrator. To use the information in this chapter, you should be familiar with creating forms and
workflow in BMC Remedy AR System, and you should understand how to use the Set Fields action
in a filter or escalation. You must also be familiar with Atrium Orchestrator processes and
operations.
Note
Page 1004 of 4705
Home
To integrate BMC Remedy AR System with Atrium Orchestrator, you must use BMC
Atrium Orchestrator 7.5 or later. For a list of the compatible web application servers, see
Compatibility matrix in the BMC Remedy ITSM Deployment online documentation. For
more information about Atrium Orchestrator processes and operations, see your Atrium
Orchestrator documentation.
Application developers can integrate AR System applications with Atrium Orchestrator. This
integration requires the AR System Web Services plug-in, which uses the Java plug-in server, to be
installed with the AR System server. BMC Remedy AR System acts as a consumer of the Atrium
Orchestrator web service.
To integrate an AR System application with an Atrium Orchestrator web service, you must complete
these two main tasks:
Create an entry in the AR System Orchestrator Configuration form. Each entry in this form
defines the configuration for a specific Atrium Orchestrator web service.
Create workflow to integrate the application with Atrium Orchestrator, including:
A form containing the fields that will hold input and output values for data exchanged
with Atrium Orchestrator.
A filter or escalation associated with this form. The filter or escalation must include
one or more Set Fields actions that use the BMC ATRIUM OCHESTRATOR data
source.
Note
The tools you use to create AR System workflow and applications and to
create and customize Atrium Orchestrator processes have very similar
names. This section describes using Developer Studio to create AR System
workflow that integrates with Atrium Orchestrator. Atrium Orchestrator
includes the workflow modeling tool Atrium Orchestrator Development
Studio (Development Studio). For information about using Developer Studio
with BMC Remedy AR System, see Developing an application. For
information about using Development Studio with Atrium Orchestrator
processes, see the Atrium Orchestrator documentation.

Defining BMC Atrium Orchestrator web services
Modifying entries in the AR System Orchestrator Configuration form
BMC Remedy AR System workflow for BMC Atrium Orchestrator integration
Obtaining job status for asynchronous execution operations
Page 1005 of 4705
Home
Defining BMC Atrium Orchestrator web services

The AR System Orchestrator Configuration form allows you to define the list of Atrium Orchestrator
web services available. Each entry in the form represents the configuration information for an
Atrium Orchestrator service and contains all the information required to connect to that service.
The configuration settings that you enter in this form are used when you design the associated filter
or escalation. All information required at run time is stored in the filter or escalation.
To define the Atrium Orchestrator web service for BMC Remedy AR System
1. Log in to BMC Remedy AR System as a user with administrator privileges, using the mid tier
interface.
2. On the home page, select AR System Administration Console > System > General >
Orchestrator Configuration.
3. In the AR System Orchestrator Configuration form, complete the following fields:
Configuration Name A unique name that identifies this entry. This is a required
field. The name must be unique, and BMC Remedy AR System assigns a GUID to
the field.
When you create the associated filter or escalation, Developer Studio uses this field
to display a list of all the entries in this form.
Grid name The grid name for the web service. This is a required field.
When you create the associated filter or escalation, Developer Studio uses the value
in this field along with the service URL to obtain the list of Atrium Orchestrator
processes. Developer Studio stores the grid name within the workflow action for use
when the service is consumed.
Description A description of this web service. This is not a required field.
Service URL The URL for the web service on the Atrium Orchestrator server, in
the format http://serverName:port/orchContextPath/orchEndPoint . This is a required
field. Obtain the Atrium Orchestrator context path and end point from the Atrium
Orchestrator administrator. When you create the associated workflow, Developer
Studio uses the value in this field along with the grid name to obtain the list of
processes for the service. It also stores the Service URL in the workflow action for
use when the service is consumed.
Username The user name to use when connecting to the web service. This is a
required field.
Password The password to use when connecting to the web service. This is a
required field.
Developer Studio uses this user name and password at design time to connect to the
web service and obtain data about the service. It also stores this user name and
password in the workflow action for use when the service is consumed.
To override the design-time user name and password with the correct user name and
password at run time, you must use the Input Mapping table in the filter or escalation
to map these elements to fields in the associated form. See To define the filter or
Page 1006 of 4705
Home
escalation.
The following figure shows an example of a completed entry in the AR System
Orchestrator Configuration form.
Example AR System Orchestrator Configuration form entry
Modifying entries in the AR System Orchestrator Configuration

form
Information stored in the AR System Orchestrator Configuration form is used at design time when
you create filters and escalations to perform Atrium Orchestrator operations. When you save the
filter or escalation, information from the configuration form is stored in the workflow object.
If you change the information for a configuration entry after associating workflow to the
configuration, Developer Studio prompts you to confirm whether you want to override the
information stored in the filter with the new information from the configuration form.
Overwrite dialog box
As shown in the Overwrite from configuration form dialog box, the active fields are those that have
Page 1007 of 4705
Home
different values in the configuration form entry from those stored in the workflow. To override these
values in the workflow object with the values from the configuration form, select the appropriate
check boxes. (If the check box is inactive, that value has not changed.) When you save the filter or
escalation, the new values are saved with it.
Note
If you export the Atrium Orchestrator workflow and import it to another AR System server,
you should also export and import the associated entry in the AR System Orchestrator
Configuration form. This entry is needed if the filter or escalations that use it are to be
edited on the other server. If you do not export the configuration form entry, you can still
run the workflow on the other server.
BMC Remedy AR System workflow for BMC Atrium

Orchestrator integration
To integrate an AR System application with BMC Atrium Orchestrator, use Developer Studio to
create an AR System form or forms to hold the input and output data for each process, and a filter
or escalation to exchange information with BMC Atrium Orchestrator.
In the AR System filter or escalation, you select the BMC Atrium Orchestrator processes and the
operation to perform. The workflow can be designed to carry out either synchronous or
asynchronous BMC Atrium Orchestrator operations. With synchronous execution, BMC Remedy
AR System waits for the operation to complete before returning a result to the workflow action. With
asynchronous execution, the operation returns a job ID. In this case, you use the job ID in
subsequent workflow actions to determine the status of the operation, or to cancel it.
Note
You must use a separate Set Fields action for each BMC Atrium Orchestrator process.
To define the application form

1. Create a regular form, and add the appropriate fields to hold the input and output data for the
Set Fields action.
The input and output fields on the form depend on the operation and process type. You can
create one form that will hold the data for all process integrations, or separate forms for each
process.
2. Save the form and assign a form name.
Page 1008 of 4705
Home
To define the filter or escalation

1. Create a new filter or escalation.
2. In the Associated Forms panel, associate the form to the filter or escalation by selecting the
form you created in step 1.
3. Select the appropriate Execution Options and enter a Run If qualification that is appropriate
for the application.
4. In the If Actions panel, add a Set Fields action with the following settings:
a. As the Data Source, select BMC Atrium Orchestrator.
b. In the Configuration Name field, select a configuration from the list.
BMC Remedy Developer Studio obtains the list of available configurations from the
entries in the AR System Orchestrator Configuration form. When you select a
configuration, Developer Studio retrieves the values for the Service URL and Grid
Name, and populates those fields.
Note
If you override the values in the Service URL, Grid Name, Username, or
Password field, Developer Studio stores the overriding values in the filter or
escalation. In this case, whenever the Set Fields action is opened in the
future, Developer Studio warns you that the values in the filter do not match
the values in the configuration form. At that time you can select which values
to replace with those from the form, if necessary.
c. In the Operation field, select an operation from the list.

The available operation types are:
Synchronous Execution BMC Remedy AR System waits until the process
is complete, and then returns the process result. If the process fails to execute,
BMC Atrium Orchestrator returns a SOAP fault and the AR System server
reports an error in the filter or escalation.
Note
Processes that take longer than 40 seconds to complete cannot be
executed in Synchronous Execution mode. If this occurs, BMC
Remedy AR System reports error 8939: "The AR System Plug-In
server is not responding." For longer processes, use Asynchronous
Execution mode instead.
Page 1009 of 4705
Home
Asynchronous Execution BMC Remedy AR System returns without

waiting for the process to complete. An asynchronous execution operation
always returns the Job ID.
Cancel Execution Cancels the operation identified by the Job ID.
The time in which you can cancel an operation is limited, based on when the
operation started. This is configurable in BMC Atrium Orchestrator. See the
BMC Atrium Orchestrator documentation.
Valid input values for this operation are WITH_COMPENSATION and
WITHOUT_COMPENSATION. If you use WITHOUT_COMPENSATION,
Atrium Orchestrator returns the job status ABORTED. If you use
WITH_COMPENSATION, or if you use an invalid or empty input value, BMC
Atrium Orchestrator returns the job status COMPENSATED.
Get Job Status Returns the current status of the job identified by the Job ID
. See Obtaining job status for asynchronous execution operations .
5. To add a BMC Atrium Orchestrator process to the Process table, click Add.
6. In the Add Process dialog box, select a Module from the drop-down list in the Module field.
A list of BMC Atrium Orchestrator processes appears in the Process list of the Add Process
dialog box.
7. Scroll through the list of processes and select the appropriate one, then click OK.
Developer Studio enters the process in the Process table, and populates the Input Mapping
and Output Mapping tables with the appropriate BMC Atrium Orchestrator data elements.
8. In the Input Mapping table, map each BMC Atrium Orchestrator data element to a field or a
static value:
9. To map a field from the associated form, click in the Field/Value column, and then click the
ellipsis button. In the Field Selector dialog box, select the field to map to the BMC Atrium
Orchestrator data item, and then click OK.
To enter a static value, type the value in the Field/Value column.
To override the Username and Password stored in the configuration form, map these
elements to fields in the associated form, as shown in the following figure, or enter a
different static value.
When you enter a static password value, the plain text password appears in the Field/
Value cell until the cell loses focus. From then on, the password value is displayed as
a string of asterisks whether or not the cell has focus.
Note
The Username and Password from the configuration form are stored in
these elements as the default attribute, and will be used if the mapped fields
are NULL at run time. If you want to prevent this, delete them from the Field/
Value column before you map the fields. Also, Developer Studio
Page 1010 of 4705
Home
automatically sets the attributes arUsername: true and arPassword: true

in these elements. This causes the filter or escalation to use the current user
name and password at run time, if no other value is available. You cannot
change these attributes.
Mapping Username and Password to fields
10. In the Output Mapping table, map each BMC Atrium Orchestrator data element to a field on
the associated form.
Note
Output parameters returned to BMC Remedy AR System consist of the value only.
XML tags generated by BMC Atrium Orchestrator are stripped from the returned
value.
Obtaining job status for asynchronous execution operations

When the workflow uses asynchronous execution, BMC Atrium Orchestrator returns a job ID. You
can use the job ID in subsequent workflow actions to obtain the job status with the Get Job Status
operation, and then use the job status to trigger further workflow actions. The possible values for
the returned job status are:
READY
PENDING
ASSIGNED
IN_PROGRESS
PAUSED
COMPLETED
Page 1011 of 4705
Home
COMPENSATED
CANCELLED
PENDING_REASSIGNMENT
FAILED
ABORTED
Note
The COMPENSATED status indicates that an error occurred during execution of an
asynchronous process. For more information about BMC Atrium Orchestrator job status,
see the BMC Atrium Orchestrator documentation.
Atrium Integrator adapter for BMC Remedy AR

System
BMC Remedy Action Request System (BMC Remedy AR System) version 8.1 provides data
management services to enable the following:
Integration of external data with data residing in your BMC solution stack
Data migration, import, change, and export
Data integration
The Atrium data integration services are available for BMC Remedy AR System through the Atrium
Integrator adapter, an AR System Database Connectivity (ARDBC) plugin, the Atrium Integrator
Spoon client, and the Atrium Integrator engine forms all are installed with the AR System server.
These services enable you to:
Gather, or extract, data from a variety of sources
Change and transport, or transform, data
Store, or load, data in one or more target locations
You can rapidly extend the scope of your data management capabilities by adding Atrium Integrator
, the BMC Remedy ITSM suite of applications, and the BMC Atrium Configuration Management
Database (CMDB).
The following diagram illustrates the AR System interaction with the Atrium Integrator adapter, the
Spoon client, and the Atrium Integrator engine forms.
Atrium Integrator adapter and related components
Page 1012 of 4705
Home
Component
Description
Atrium
Integrator
adapter
An ARDBC plugin that receives requests for executing and monitoring jobs from the AR System server, sends
them to the Atrium Integrator Carte server, then returns the Carte server results to the AR System server. Installed
with your AR System server.
Atrium
Integrator
Spoon client
A GUI used to create and manage data integration jobs and transformations. Installed with your AR System server.
Atrium
Integrator
Carte server
A web server for data integration that allows remote job and transformation execution by accepting XML files that
contain the job's (or transformation's) execution configuration. Enables remote monitoring as well as starting and
stopping of jobs and transformations that run on the server. Installed with your AR System server.
Atrium
Integrator
AR and
CMDB
plugins
A plugin used to import data from and/or export data to an external data store to and/or from the AR System server
and/or the BMC Atrium CMDB. Installed with your AR System server and BMC Atrium Core installation. For more
information, see Installing a stand-alone Atrium Integrator server.
BMC
Remedy AR
System
server
The AR System server.
BMC
Remedy AR
System
repository
Forms that store jobs and transformation definitions and log files. The Spoon client can be used to access the
repository.
BMC
Remedy AR
System
forms
Forms that are shipped with AR System or are created by you.
Atrium
Integrator
engine
forms
Atrium Integrator ARDBC plugin front-end forms that allow job execution and monitoring on the Carte server.
Installed with your AR System server.
Page 1013 of 4705
Home
Component
Description
External
data
Flat files, spreadsheet files, database files, or other data that is imported or exported to or from your AR System
server for data migration.
AR System permissions scheme

Access to the Spoon client application and all base vendor forms for the ARDBC plug-in is
configured in the BMC Remedy AR System permissions interface. To use the Spoon client you
must connect to an Atrium Integrator repository, which resides on the AR System server. The
Spoon client requires an BMC Remedy AR System user with administrator permissions to connect.
To access the base vendor forms of the ARDBC plug-in, the user's role must be either an AR
System UDM administrator or an AR System UDM user.
Related topics
Atrium Integrator
Importing data with Atrium Integrator
Configuring Atrium Integrator for data import
Enhancements
Troubleshooting
Know Issues in 8.1
Know Issues in 8.1
BMC Remedy ITSM 8.1
Data Management
ETL in the Atrium Integrator adapter

The Atrium Integrator adapter data flow occurs in an Extraction, Transformation and Loading (ETL)
process, or a transformation. An individual unit of transformation is a step. The Atrium Integrator
adapter also supports jobs.
Transformations A transformation is combination of steps and hops that make integration
between source and target data stores possible. It reads data from the source data store,
transforms it according to the rules that you specify, and stores it in the target data store.
Transformation may be simple or complex. Transformations are saved with the .ktr filename
extension.
Page 1014 of 4705
Home
Jobs A job performs high-level data flow control. A job is composed of one or more
transformations and it executes transformations. Jobs are used to coordinate ETL activities
such as defining the flow and dependencies for what order transformations should run, or
prepare for execution by checking conditions such as, "Is my source file available?" or "Does
a table exists in my database?" Jobs are saved with the .kjb filename extension.
Steps A step is the basic unit of a transformation that performs an action such as data
loading. Groups of steps define input and output stores. As such, steps are organized into
categories such as Input steps or Output steps. Steps also exist in jobs.
Hops A hop shows data flowing from one step to another in a pictorial representation of a
transformation in the Spoon client. The data in a hop originates at an Input step and is
destined for an Output step.
Transformation in the Spoon client
BMC Remedy AR System repository

Transformations, jobs and their related components are stored in the BMC Remedy AR System
form repository, which can be accessed using the Spoon client.
Form repository
Page 1015 of 4705
Home
When you save a transformation, the form repository starts and commits the client-managed
transaction. If the transformation already exists, the data related to the transformation (such as,
transformation attributes) is cleared from all related transformation forms. In addition, it saves:
All database connection and database connection attributes information
All transformation hops
All transformation notes
All step and step attribute information
Error step information
Transformation:
setting information
parameter information
slave server information
cluster schema information
dependency information
When you save a job, the form repository starts and commits the client-managed transaction. If the
job already exists, the data related to the job (such as, job attributes) is cleared from all related job
forms. In addition, it saves:
Page 1016 of 4705
Home
All database connections

All job entries and job entry attributes
All job hops
All job notes
Job settings information
Slave server information
When you load a transformation into the Spoon client, the form repository reads all:
Step and step attributes
Transformation attributes
Transformation hops
Transformation notes
Transformation settings
Database connections, slave servers, cluster schemas, and partition schemas
When you load a form into the Spoon client, the form repository reads all:
Job attributes
Job entries and job entry attributes
Job hops
Job notes
Job parameters
Job settings
Database connections, slave servers, cluster schemas, and partition schemas
Input, output and file input steps

The Atrium Integrator adapter supports Input, Output and File Input steps. Each step type is
implemented in BMC Remedy AR System (AR System) as a Atrium Integrator adapter plug-in.
Input steps
Input steps in a transformation or job read data from a data source. To read AR System data and
export it into other formats such as .csv file or XML file, AR System includes the AR Reader
adapter plug-in, or ARInput step. For more information, see ARInput step.
Output steps
Output steps in a transformation or job write data to a data source. To import data into AR System
from an external source (such as a flat file, .csv file, XML file, or relational database tables), AR
System includes the AR Writer adapter plug-in, or AROutput step. For more information, see
AROutput step.
Page 1017 of 4705
Home
File input step

AR System includes an adapter plug-in for transformations and jobs, the ARX File Input step. Its
primary purpose is to read data from a AR System .arx file. For more information, see ARX File
Input step.
Variable input
The ARInput, AROutput, and ARX File Input adapter plug-ins, as well as the AR Connection
module, support variables as input.
The server name, port number, and RPC number can be defined as variables when defining an AR
System connection (or AR Connection) for an ARInput step or an AROutput step. The .arx filename
in the ARX File Input step can also be defined as a variable. For more information, see Variable
form.
ARInput step
The ARInput step allows data to be extracted from a BMC Remedy AR System form. It also:
Uses its connection input parameters to create an AR System server connection. The
connection is created once and reused as needed.
Substitutes chunk size and qualifications with real values, if variables are used.
Uses the GetListEntryWithFields (GLEWF) call on the form by providing the field IDs of
the user-selected fields and fetches data with the user-provided chunk size.
Converts each entry to an Atrium Integrator row format and sends it to the next step.
Supported conversions are from standard AR System data types to data types supported by
Atrium Integrator. Data types are listed below.
ARInput step in the Spoon client
Page 1018 of 4705
Home
General tab
The General tab contains three fields:
Connection Click the New button to create a new BMC Remedy AR System server connection.
Click the Edit button to modify an existing connection. You can select an existing connection from
the dropdown menu.
Form Name Name of the BMC Remedy AR System form from which data is extracted.
Chunk Size Number of records to be fetched from the AR System server at one time. This
number may be specified as a variable. If a variable is specified, the ARInput step will use the
variable value at runtime.
Qualification tab
The Qualification tab allows you to provide a qualification string to extract data from an AR System
form. If a qualification string is not provided, all data is extracted from the form using a 1=1
qualification. If variables are used in the qualification string, the ARInput step will use the variable
values at runtime.
Click the Configure Qualification button to open and configure the qualification.
Qualification tab in the ARInput step
Page 1019 of 4705
Home
Fields tab
The Fields tab allows you to specify a list of fields to be extracted from an AR System form. The
Get Fields button allows you to add all fields from a form to the list.
Fields tab in the ARInput step
Supported data types

Atrium Integrator supports the following data types:
Data type
Description
None
No type
Number
Java's Double object
String
Java's String object
Date
Java's date object
Page 1020 of 4705
Home
Data type
Description
Boolean
Java's Boolean value
Integer
Java's Long object
Bignumber
Java's BigDecimal object
Serializable
Any Java's object
Binary
Blob or clob data
The ARInput step data type conversions include:

ARInput data type conversions
AR System Data Type
Atrium Integrator Adapter Data Type
Null
None
Integer
Integer
Real
Number
Char
String
Diary
String
Time
Integer
Bitmask
Integer
Bytes
Binary
Decimal
Bignumber
Attach
Binary
Date
Date
Time of Day
Integer
Ulong
Integer
Display
String
View
String
Complex AR System data types such as Attachment, Currency, and Status History are handled in
the same way the AR System Import tool and ODBC driver handle data types. For example, the
Currency field is split into its separate parts, such as Date, Type and Value, and each is identified
separately in the field list. See Importing data into BMC Remedy AR System forms for more data
import information.
AROutput step
The AROutput step allows data to be inserted into a BMC Remedy AR System form. It also:
Connects to the AR System server using the connection input parameters. A connection is
created once and reused.
Page 1021 of 4705
Home
Substitutes commit size and qualifications with real values, if variables are used.
Checks if it should start a new batch based on the flag, if the commit size is provided. This
flag is true by default. After a transaction is started, it changes to false. Once the
transaction is committed, the flag is reset to true.
Retrieves the input row from the previous step using the Atrium Integrator get row API
function.
Converts the Atrium Integrator input row to an AR System form entry using the Mapping
Field list. The Atrium Integrator row data type is converted to the AR System data type. After
the value is converted to the corresponding AR System data type, a second-level conversion
is required if the field's data type does not match the converted value's data type. The data
type conversions are listed below.
Parses the matching qualifications and substitutes the values of stream fields from the input
row in the qualification object.
Prepares the merge type based on duplicate request action, requires any required fields,
and enforces pattern-matching flags.
Uses the Java ME API call by providing the AR System form name, qualification (optional-if
not present it passes a NULL), merge type, and multi-match option. If the server does not
support the new Java ME API with a qualification, then it explicitly gets the matching request
using a GLEWF call. Then it performs the merge based on the specified merge type.
Checks whether it is time to commit the transaction based on the record number if a bulk
transaction is started. If it is, then it calls the end bulk entry transaction API and sets the start
bulk entry transaction flag to true.
AROutput step in the Spoon client
Page 1022 of 4705
Home
General tab
The General tab contains three fields:
Connection Click the New button to create a new AR System server connection. Click the Edit
button to edit an existing connection. Select an existing connection from the dropdown menu.
Form Name Name of the AR System form used to import data.
Batch Commit Size (optional) If provided, data will be imported using bulk API, which may be
specified as a variable. If it is specified as a variable, the AROutput step will use the actual value
provided.
Checkbox An option to switch to a single-row commit if batch-commit fails.
General tab in the AROutput step
Page 1023 of 4705
Home
Duplicates tab
The Duplicates tab contains four fields:
Duplicate Request Action Select Error, Create New, Overwrite or Update for the duplicate
request ID action.
Match By Request ID Select to use the Request ID for a matching output row.
Multi Match Option Select when more than one record matches the matching qualification.
Matching Qualification String (optional) If a qualification string is not provided, matching occurs
with the Request ID. Variables may be used in the string. At runtime, variables are substituted for
actual values. Click the Configure Matching Qualification button to open the qualification helper
dialog and configure a matching qualification. Fields from previous steps are displayed here and
may be used inside the qualification.
Duplicates tab in the AROutput step
Page 1024 of 4705
Home
Data Handling tab

The Data Handling tab contains three options:
Require Required Fields Select this option to allow or disallow null values for required fields.
Enforce Pattern Matching Select this option to enforce pattern matching. For example, a pattern
may be configured such that a field's value is alphanumeric. Selecting this option will ensure that
this pattern is enforced.
Skip Workflow Processing Select this option to bypass workflow processing when this row is
written to the form. When selected, workflow defined on a merge action for this form will not be
executed.
Data Handling tab in the AROutput step
Field Mapping tab

The Field Mapping tab allows you to map the output fields from previous step(s), or stream fields,
to their respective AR System form fields.
Field Mapping tab in the AROutput step
Page 1025 of 4705
Home
The Edit Mapping button provides a helper dialog to map the fields.
Enter Mapping dialog from Field Mapping tab
AROutput data type conversions

AR System Data Type
None
Null
Number
Real
String
Char
Page 1026 of 4705
Home
AR System Data Type
Date
Date
Boolean
Enum
Integer
Ulong
Bignumber
Decimal
Binary
Attach
ARX File Input step

The ARXInput step allows you to read data from ARX files and import them into BMC Remedy AR
System forms (or any other output data source.)
Passes an ARX file to the AR System ARX parser which extracts schema info and data lines
.
Displays schema names in a list, which allows the user to select one schema at time.
Displays all fields for the selected schema in the Fields table when the Get Field button is
clicked.
During an execution of a transformation, the ARX parser reads the data line and converts it
into a token.
Converts tokens into the proper Atrium Integrator data types.
Handles multiple schemas in single file.
Treats multiple occurrences of same schemas as single schema and combines all data
together.
The data type conversion is same as that of the ARInput step, see ARInput data type conversions
for details on the ARInput data type conversions.
ARX File Input step in the Spoon client
Page 1027 of 4705
Home
The ARX File Input step dialog contains the following fields:
Step Name Unique label for the ARX File Input step in a transformation.
File Name ARX file name and path from which data will be read. The location can be
defined as a variable.
Chunk Size Number that specifies the size of the data to be read at one time from the
ARX file. The default value is 100. This value can be defined as a variable.
Schema Names Name of the AR System schema containing data to be read from the
ARX file.
Connection Click the New button to create a new AR System server connection. Click the
Edit button to edit an existing connection. Select an existing connection from dropdown
menu.
The Field Name column contains a list of fields to be extracted from the ARX file for a given
schema. If an AR System connection is provided, the field names are extracted from the AR
System form and not the ARX file.
If field names and field labels differ and you want to map ARX file Input step data to an AROutput
step, use the AR System connection. You can automatically map all fields to the AROutput step in
the Enter Mapping window of the Field mapping editor using the Auto Map button.
Auto Map button in the Enter Mapping dialog
Page 1028 of 4705
Home
AR Connection module
You can create AR System database connections for transformations in the Spoon client using the
AR Connection module. Once an AR System database connection is defined, it is available to all
ARInput and AROutput steps in a transformation.
1. From the Transformations folder, specify the server connection details.
2. Select Database connections > New. The Database Connection dialog box opens.
3. Select General > AR System, fill in the remaining settings.
4. Cick OK to establish the connection.
New database connection
Page 1029 of 4705
Home
Support for Client Managed Transactions

The Atrium Integrator adapter uses the AR System Client Managed Transaction feature to open a
database connection instance and share that connection with all transformation steps.
Transformations using ARInput, AROutput, and CMDB sources use this feature because the
sources operate on objects with relationships and make modifications on multiple forms and/or
tables based on data in other tables (as well as results from previous steps). For example, the
adapter might receive data from an LDAP server and place it in User forms. If a problem occurs,
rolling back changes is easy when the transformation runs in a single database connection.
To enable this feature, select the Make the transformation database transactional check box in
the Transformation properties dialog box.
Transformation properties dialog
Page 1030 of 4705
Home
Error handling
The ARInput, AROutput and ARX File Input steps throw an exception if they receive an error when
executing API calls. This halts the transformation execution. To implement out-of-the-box support
for skipping error rows and continuing execution of the subsequent input rows, you must define an
error handling step in the Spoon client for the related ARInput, AROutput or ARX File Input steps in
a transformation. The error handling step could be a text file Output step that writes the error
information to an error log file.
Error handling enabled for AROutput step
java.lang.OutOfMemoryError: Java heap space

A java.lang.OutOfMemoryError: Java heap space error may occur if multiple concurrent
jobs run on an Atrium Integrator server. To resolve this error, increase the Java heap space of
Atrium Integrator server process in the armonitor.cfg file.
Page 1031 of 4705
Home
Directory structure
When designing a file input step (such as ARX File Input or text file input) in a transformation, enter
the appropriate UNIX or Windows path available from the BMC Remedy AR System server in the
Filename field.
Example
Windows directory structure

D:\ARSFolder\subfolder\file.txt
UNIX directory structure
/ARSFolder/subfolder/file.txt
Filename field in the File tab

New Excel columns

If you add a new column to an Excel input file, add it at the end of the worksheet. If you add a new
column elsewhere in the worksheet, you must manually add its corresponding field number to the
Field tab in the Excel Input step. In addition, you must add all columns from the Excel spreadsheet.
The following error message displays if you use the Excel Input step, sort on any tab in the Fields
tab, save the transformation, and then 1) preview rows in the file or 2) run the transformation in
BMC Remedy AR System or with the Spoon client.
org.pentaho.di.core.exception.KettleValueException:
Unexpected conversion error while converting value [v String] to a Number
Log Files
Atrium Integrator adapter log files in Windows systems reside in <
AR_system_installation_directory>/ARserver/db. Unix log files reside in <

AR_system_installation_directory>/db. Carte server log files include:
Page 1032 of 4705
Home
arcarte.log All Execution Instance messages are recorded in this file according to the
logging level specified when you created the Execution Instance.
arcarte-stdout-<timestamp>.log All messages that the Carte server prints to the
console are recorded in this file.
arcarte-stderr-<timestamp>.log All error messages that the Carte server prints to the
console are recorded in this file.
The ARDBC plug-in log file is arjavaplugin.log. All ARDBC plug-in messages are recorded in this
file. By default the log level is warn. If you want to log info or debug messages:
1. Open <AR_system_installation_directory>/pluginsvr/log4j_pluginsvr.xml
2. Search for logger com.bmc.arsys.pdi.
3. Change the log level to info or debug.
4. Restart the AR System server.
Example
<logger name="com.bmc.arsys.pdi">
<level value="info" />
</logger>
AR System form log files

The Log field in the UDM:ExecutionStatus form shows the log file for a specific Execution Instance.
However, the log lines displayed are stored in the Carte server's memory, which has a maximum
buffer of 5000 lines to control memory usage. As new log file lines are added, the Carte server
deletes the older log file lines. However, this information is retained in the arcarte.log with all other
Carte server log file information. See the third-party documentation for more information about this
logging limitation.
To configure the Carte server to store more than 5000 log lines, set the
KETTLE_MAX_LOG_SIZE_IN_LINES parameter in the armonitor.cfg file for the Carte Java
process, and restart the AR System server.
A transformation or job can be configured to log the execution information to AR System logging
forms. Use these forms to configure logging:
UDM:TransformationLog Stores transformation instance log.
UDM:JobLog Stores job instance log.
UDM:JobEntryLog Stores job entries log for a specific job instance.
UDM:StepLog Stores steps log for a specific transformation instance.
To enable form-level logging for a transformation or job:
Page 1033 of 4705
Home
1. Open the transformation or job in the Spoon client.

2. Right-click on the transformation or job name.
3. Click the Logging tab.
4. Add the AR Server connection and the corresponding AR form name for the log table name.
For example, use UDM:TransformationLog for the transformation and UDM:StepLog for the
step.
5. Save the transformation or job.
Spoon client log files

When you run a transformation or job in the Spoon client, the log information is displayed in the
Logging tab of the Execution results panel.
Spoon client log information
Error message descriptions

This section describes runtime, design, and plug-in error messages for the Atrium Integrator
adapter. For related BMC Remedy AR System error messages, see BMC Remedy AR System
error messages.
Runtime error messages
Message
Description
You need to specify a BMC

Remedy AR System
connection.
A connection to AR system is missing from a transformation step.

Open the transformation from the Spoon client. Configure a new or existing AR System
connection for the ARInput or AROutput step by using the New and Edit buttons on the General
tab. Save and re-run the transformation.
Error Connecting to
ARSystem.
Page 1034 of 4705
Home
An ARInput or AROutput step in your transformation cannot connect to BMC Remedy AR System
.
Ensure that 1) the AR System server is running when you run the transformation, 2) the
connection parameters are specified correctly, and 3) the correct variable values are specified
correctly for the AR System connection.
Error parsing the qualification
The ARInput step failed to parse the specified qualification.
Error while fetching status

field enum values
The ARInput step failed to fetch the string enum values for the Status field (AR Core field ID 7).
Error while fetching next set of
The ARInput step failed to fetch the next chunk of records from the AR System server.
records
Error while converting AR
The ARInput step failed to convert the BMC Remedy AR System data type value to an Atrium
value to Pentaho value
Integrator value.
Ensure that the source and target data types are compatible.
Error while fetching status

history
The ARInput step failed to fetch the Status History field value for a row.
Error while fetching

attachment for field: {0}
The ARInput step failed to fetch the Attachment value for a row.
Field {0} couldn't be found on

form {1}
The AROutput step cannot find an AR System field contained in the field mapping.
Check the mapping to ensure that the field names are used correctly. To avoid this error, use the
mapping editor provided in the AROutput step. To access the editor, press the Edit Mapping
button on Field Mapping tab of the AROutput step dialog to access the editor.
Field {0} couldn't be found in

the input stream!
The AROutput step cannot locate the stream field (fields from previous steps) and defined in the
field mapping.
Check if the hop between the previous step and the AROutput step is disabled. If it is disabled,
enable the hop and save the transformation. Also check if a field was removed from a previous
step but not removed from the AROutput step field mapping. If it was removed, remove it from
the field mapping and save the transformation. In addition, check if the field is defined as an error
handling parameter in a previous step. If the hop between the previous step and the AROutput
step is not defined as a normal hop or as an error hop, change the hop type from a normal hop to
an error hop. Save the transformation.
Error in AROutput Step
The AROutput step failed to send the output to BMC Remedy AR System.
Error in BULK ENTRY

Transaction: {0}
The AROutput step failed to commit the bulk entry transaction.
More than one entry matched
Review the qualification and modify it to ensure that it matches one entry, or change the
the qualification and the multi

match option is set to ERROR
multi-match option to update first or update all.
Error while parsing matching

qualification
The AROutput step failed to parse the specified matching qualification.
No or Empty Currency Code
The AROutput step cannot find the currency code for the currency field value.
for Currency value for field {0}

Map the currency code (<currency field name>.TYPE) in the field mapping, or ensure that
the stream field (mapped to the currency field) defines the currency code value.
Page 1035 of 4705
Home
No conversion date for

Currency value for field {0}
The AROutput step cannot find the conversion date for the currency field value.
Map the conversion date (<currency field name>.DATE) in the field mapping, or ensure
that the stream field (mapped to the currency field) defines the conversion date value.
No Currency value for field {0}
The AROutput step cannot find the decimal value for the currency field.
Map the decimal value (<currency field name>.VALUE) in the field mapping, or ensure that
the stream field (mapped to the currency field) defines the decimal value.
No Currency Conversion
Ratio Defined from {0} to {1}
A currency conversion between two different currency types was needed during the execution of
a transformation that included the AROutput step. The conversion ratio was not defined in the AR
System Currency Ratios form.
Supply conversion ratios in the AR System Currency Ratios form for all possible conversions.
Error while fetching fields
The AROutput step failed to fetch field information from a form in BMC Remedy AR System.
information for form {0}

EXTERNAL operator is not
supported in the matching
qualification
Remove the External operator from the qualification.
No such form field having field

ID {0}
The AROutput step cannot find the Field ID used in the matching qualification on the form.
Review the qualification and remove the non-existent Field ID references. Use the Spoon client to
access the Qualification editor provided in the AROutput step dialog, and configure the
qualification. To access the qualification editor, press the Configure Matching Qualification
button on the Duplicates tab.
Wrong Matching Qualification.

Stream field {0} should be
used on the right hand side of
a relational operation.
The AROutput step determined that stream fields (fields from previous steps) are used in the left
side of the relation operation in the matching qualification.
Modify the matching qualification to use stream fields on the right side of the relation operation in
the matching qualification. Use the Spoon client to access the qualification editor provided in the
AROutput step dialog, and configure the qualification. Press the Configure Matching
Qualification button on the Duplicates tab to access the qualification editor.
No such stream field [{0}]
The AROutput step cannot find a stream field (field from the previous step) referenced in a
matching qualification.
Review the qualification to remove the non-existing stream field references. Use the Spoon client
to access the qualification editor provided in the AROutput step dialog, and configure the
qualification. Press the Configure Matching Qualification button on the Duplicates tab to
access the qualification editor.
Error initializing step...

java.io.FileNotFoundException
:
The file path specified in the ARX File Input step or specified as a variable value is not found on
the system.
Ensure that the file is present on the system.
Error while setting the private

RPC Queue
An error occurred while setting the private RPC queue number on the AR connection.
Error while reloading the

password collection
An error occurred while reloading information from the UDM:RAppPassword form.
Page 1036 of 4705
Home
Did not find Remedy

Application Service password
The Remedy Application Service password for a server is missing from the UDM:RAppPassword
form.
for server {0} in UDM:

RAppPassword Form on
Add an entry for the server in this form.
server {1}
Error while impersonating
user {0}
An error occurred while impersonating the provided user.
Error occurred while trying to

create transaction on the
An error occurred while starting a client managed transaction on the AR connection.
ARdatabase
No valid database connection
defined!
No connection related information is defined on AR connection. Please define host, port, TCP
port, RPC port, user name on connection to avoid this error.

connect to the database
An error occurred while connecting to BMC Remedy AR System.
Error disconnecting
An error occurred while disconnecting from BMC Remedy AR System.
ARdatabase: {0}
Error performing commit on
connection
An error occurred while committing the client managed transaction on the AR connection.
Error performing rollback on

connection
An error occurred while rolling back the client managed transaction on the AR connection.

get list of tables
An error occurred while fetching a list of form names from BMC Remedy AR System.

get table fields
An error occurred while fetching a list of fields on a form from BMC Remedy AR System.
Error occured while trying to

get table entries
An error occurred while fetching form entries from BMC Remedy AR System.
Error while converting AR

value to pentaho value
An error occurred while converting an AR data type value to an Atrium Integrator value.
Ensure that the source and target data types are compatible.
Error while fetching last log

date
An error occurred while fetching the last log date from log forms such as, the UDM:
TransformationLog form or the UDM:JobLog form.
Unable to write log record to

log form {0}
An error occurred while writing a log record to the logging form, such as the UDM:
Error while fetching log

records from {0} form
An error occurred while fetching log records from logging form such as, the UDM:
Error while clearing log form

entries from {0} form
An error occurred while deleting log records from a logging form such as, the UDM:
A log timeout was defined for

log table {0}, but it doesn't
have a log field
A log timeout value is defined in the logging setting, but the log date field is not defined on the log
form.
Ensure that you are using out-of-the box logging forms such as, the UDM:TransformationLog
form or the UDM:JobLog form. If you want to use your own logging form, ensure that you add all
fields with the same IDs that are used in the out-of-the-box logging forms.
Unable to clean up old log

records from log table {0}
An error occurred while deleting log records from a logging form such as, the UDM:
Page 1037 of 4705
Home
Invalid selection value {0} for

field [Name - {1}, ID - {2}]
The AROutput step found that the provided string value is not a valid string alias selection value
for the enum field.
Check the definition of the field on the BMC Remedy AR System form to get the valid string alias
values for that enum field, and use a valid value.
Exception while converting

string to diary list value1
The AROutput step cannot convert a string value to a diary list field value.
Java.lang.OutofMemoryError
If this error message appears in transformation and/or job execution logs or in the arcarte.log file
, the Carte server does not have sufficient memory to execute jobs. This error may result when
more than two jobs are running concurrently on a Carte server. Increase the heap size of the
Java Carte process in the armonitor.cfg file, and restart BMC Remedy AR System.
Design-time error messages

Message
Description
Please select
The AR System connection is not configured for an ARInput or AROutput step.
a valid
connection!
Configure a new connection, or select existing connections for an ARInput or AROutput step using the New and
Edit buttons on the General tab of the ARInput or AROutput step dialog.
Please select
a form name
to use
The Form name is not configured for the ARInput or AROutput step.
No fields are
Configure fields in the ARInput step.
specified.
Please add
fields in fields
tab.
Configure the form name for the ARInput or AROutput step by using the Browse button on the General tab of the
step dialog.
Use the Get Fields button on the Fields tab in the ARInput step dialog to see all the form fields from the .arx file.
Delete or add fields as needed.
Field with
name {0}
does not exist
on form {1}
A Field name specified on Fields tab was not found on the ARInput step form.
Invalid field
ID {0}. Field
A Field ID specified on Fields tab is non-numeric for the ARInput step.
ID should be
a number.
Ensure that the correct Field ID was entered on the Fields tab. To avoid this error, use the Get Fields button on
the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.
Field with ID {
A Field ID specified on Fields tab is not found on the ARInput step form.
0} does not
exist on form
Ensure that you entered the correct Field ID in the Fields tab in the ARInput step dialog. Use the Get Fields
{1}
button on the Fields tab in the ARInput step dialog to see all form fields. Delete or add fields as needed.
Field with ID {
0} does not
have name {1
} on form {2}
The Field Name for a Field ID is different than the actual Field name of the Field ID in the form definition.
No field
mappings are
specified.
Please
Field mappings are not configured for the AROutput step.
Make sure you entered the correct Field name on the Fields tab. Use the Get Fields button on the Fields tab in
the ARInput step dialog to see all form fields. Delete or add fields as needed.
Ensure that you entered the correct Field Name in the Fields tab in the ARInput step dialog. It must be in sync
with the form definition fields in your BMC Remedy AR System server. Use the Get Fields button on the Fields
tab in the ARInput step dialog to see all the fields on a form. Delete or add fields as needed.
Configure the field mappings with the AROutput step field mapping editor. To access the editor, press the Edit
Mapping button on Field Mapping tab of AR output step dialog.
Page 1038 of 4705
Home
specify field
mappings in
field mapping
tab.
It was not
The AROutput step dialog cannot retrieve any stream fields (fields from previous steps).
possible to
retrieve the
If the AROutput step is not connected to a previous step, create a hop between the previous step and the
source fields
for this step
AROutput step.
because of
an error: {0}
It was not
possible to
The AROutput step dialog could not fetch AR fields from a form. Problems establishing a connection to the BMC
Remedy AR System server might exist.
retrieve the
target fields
for this step
because of
an error: {0}
Certain
referenced
fields were
not found!
These source
fields were
not found: {0}
The AROutput step dialog cannot find some stream fields (fields from previous steps) used in field mappings.
Certain
referenced
fields were
not found!
These target
fields were
not found: {0}
The AROutput step dialog cannot find BMC Remedy AR System fields specified in the field mapping. Check the
mapping to ensure that the correct field names are used.
An ARX file is
not specified.
You must
specify the
correct ARX
file.
The ARX file path is not configured for the ARX File Input step.
No schema
name is
specified,
please
specify
schema
name.
The Form name is not configured in the ARX File Input step.
Chunk size
Use a Chunk size value greater than zero in the ARX File Input step.
Check if the hop between the previous step and the AROutput step is disabled. If it is disabled, enable the hop
and save the transformation. Also check if a field was removed from previous step but not removed from the
AROutput step field mapping. If it was removed, remove it from the field mapping and save the transformation. In
addition, check if the field is defined as an error handling parameter in a previous step. If the hop between the
previous step and the AROutput step is not defined as a normal hop or as an error hop, change the hop type from
a normal hop to an error hop. Save the transformation.
In the Spoon client, add the ARX file path using the Browse button on the ARX File Input step dialog, or specify
the value as a variable and supply the variable value at execution time.
In the Spoon client, open the combo box for the ARX File Input step and enter the Form name.
cannot be
blank, please
specify chunk
size.
Page 1039 of 4705
Home
No fields are
specified.
You must configure fields in the ARInput step.
Please add
fields in fields
Use the Get Fields button on the Fields tab in the ARInput step dialog to see all form fields from the .arx file.
Delete or add fields as needed.
tab.
Plug-in error messages

Message
Description
Error in initializing the plug-in
The ARDBC plug-in failed to initialize.
Error fetching in progress import

requests
The ARDBC plug-in failed to fetch the requests left to process since the last processing.
Carte Server Name is not populated in

UDM:Config for entry ID {0}
In a server group environment, the Atrium Integrator Engine Server Name field is not
populated with an Entry ID from the UDM:Config form.
Enter a value in the Entry ID field, and enter the co-located AR System server's name (
Server-Connect-Name) in the Atrium Integrator Engine Server Name field. Using the
value in this field, the Atrium Integrator adpater ARDBC plug-in will send the Carte
server the request.
Did not find Remedy Application

Service password for server {0} in UDM
:RAppPassword Form on server {1}
A BMC Remedy AR System server's Remedy Application Service password is missing

from the UDM:RAppPassword form.
Add an entry for the BMC Remedy AR System server in this form.
Create Entry not supported on form {0}
The Atrium Integrator adapter ARDBC plug-in only supports the Create Entry call in the
UDM:Import form, the UDM:Execution form, and the UDM:ScheduleProcessor form.
Error while creating an entry on form {0

}
A Create Entry operation failed in an Atrium Integrator adapter ARDBC plug-in vendor
form.
There was an error removing the

execution instance {0} of transformation
/job {1}on the Carte server {2}: {
message}
The Atrium Integrator adapter ARDBC plug-in failed to remove an Execution Instance of
a transformation or job from the Carte server.
There was an error doing pause/

resume for execution instance {0} of
transformation/job {1} on the Carte
server {2}: {message}
The Atrium Integrator adapter ARDBC plug-in failed to pause or resume an Execution
Instance of a transformation from the Carte server.
There was an error stopping the

/job {1} on the Carte server {2}: {
message}
The Atrium Integrator adapter ARDBC plug-in failed to stop an Execution Instance of a
transformation or job from the Carte server.
There was an error starting the

/job {1} on the Carte server {1}: {
message}
The Atrium Integrator adapter ARDBC plug-in failed to start an Execution Instance of a
transformation or job from the Carte server.
Review the Carte server error message and the arcarte.log file for more information
about this error.
about this error.
about this error.
about this error.
Page 1040 of 4705
Home
Repository Directory or Object ID is

required for Operation
For the Create Execution Instance request, you must provide a Repository Directory or
an Object ID for the transformation or job.
CREATE_EXEC_INSTANCE
There was an error posting the
transformation/job on the Carte server {
The Atrium Integrator adapter ARDBC plug-in failed to create an Execution Instance of
a transformation or job on the Carte server.
0}: {message}
about this error.
Failed to reload password collection
The Atrium Integrator adapter ARDBC plug-in failed to re-read all the passwords from
UDM:RAppPassword form.
Get List Entry With Fields not supported

on form {0}
The Atrium Integrator adapter ARDBC plug-in only supports a Search entry with a Get
List Entry With Fields API call only on the UDM:RepositoryObject form, UDM:
ExecutionStatus form, and the UDM:StepStatus form.
Error while fetching data from form
A Search Entry operation failed on a vendor form that belongs to the Atrium Integrator
adapter ARDBC plug-in.
Qualifier operator OR and NOT are not

supported only AND is supported
In the vendor forms that support Search, modify your qualification because only the
AND conditional operator (and not OR or NOT) is supported.
Only EQUAL relational operation is

supported for qualifier
In the vendor forms that support Search, modify your qualification because only the
EQUAL relational operator is supported.
Field {0} is not supported for query.

Supported fields for query are {1}
In the vendor forms that support Search, check the associated Field IDs and modify
your qualification because an unsupported field is used in the qualification.
No such repository directory {0}
The existing directory name is not valid for the Execution Instance operation on the
UDM:Execution form or the Search operation on the UDM:RepositoryObject form.
Provide the correct repository directory name on the UDM:Execution form or the UDM:
RepositoryObject form.
Delete Entry not supported on form {0}
A Delete Entry API call is not supported on any vendor form that belongs to the
Atrium Integrator adapter ARDBC plug-in.
Get Entry not supported on form {0}
A Get Entry API call is not supported on this vendor form. The Atrium Integrator
adapter ARDBC plug-in only supports Get Entry calls on the UDM:RepositoryObject
form, UDM:ExecutionStatus form, and UDM:StepStatus form.
Error while fetching entry from form {0}
A Search Entry operation fails on a vendor form that belongs to the Atrium Integrator
adapter ARDBC plug-in.
No Carte server with name {0} exists in

UDM:Config form.
A transformation or job uses the UDM:PermissionInfo form, which specifies a Carte

server name, but the UDM:Config form does not contain an entry for that Carte server
name. Use the correct Carte server name and use the menu in the Atrium Integrator
Engine Server Name field on the UDM:PermissionInfo form.
Execution instance name {0} is not

unique for transformation/job {1}
The Execution Instance name provided for the Create Execution Instance operation is
not unique.
Provide a unique Execution Instance name.
Invalid Execution Instance. Execution

Instance {0} does not exist or user {1}is
not allowed to access it.
The Execution Instance name provided for the Start, Stop, Pause, Resume or Remove
operation does not exist in the database.
Page 1041 of 4705
Home
Provide the correct existing Execution Instance name for the Start, Stop, Pause,
Resume or Remove operation. If the Execution Instance exists, then the current user
does not have permission for the Execution Instance record. To add permissions,
update Field 112 in the Execution Instance record.
Either a transformation or a job {0} (
Object ID {1}, Directory ID {2}) does not
exist Or User {2} is not allowed to
access transformation/job {3}
The transformation or job provided for the Create Execution Instance operation does not
exist.
Missing required parm {0}
The schedule for the transformation or job requires a parameter.
Provide the correct transformation or job name and directory or object ID. If the
transformation or job exists, then the user does not have permission for the
transformation or job. To add permissions, update Field 112 in the transformation or the
job's record on the UDM:PermissionInfo form.
Update the schedule with the required parameter.

{0} should be an integer value.
The schedule for the transformation or job required an integer value.

Update the schedule with a valid integer value.
Error performing asynch task {0}
The ARDBC plug-in failed to process an asynchronous UDM:Import task.
Error processing UDM Import (Entry ID
The ARDBC plug-in failed to process an asynchronous UDM:Import task.
{0})
Invalid xml file. Root Element should
be transformation or job
The transformation or job definition file attached to the UDM:Import record is not a valid
file.
Attach a valid transformation definition (.ktr) or job definition (.kjb) file to the UDM:
Import form.
Transformation/Job {0} already exists in

repository directory {1}
The transformation or job being imported exists in a repository directory.

Use Overwrite mode to overwrite the existing definition.
No Pentaho repository and Carte server

details are present in UDM:Config
The UDM:Config form is empty.

Add repository and Carte server connection information to the form so the Atrium
Integrator adapter ARDBC plug-in can process the transformation.
BMC Remedy AR System forms for data management

BMC Remedy AR System (AR System) provides an ARDBC plug-in implemented as a set of
user-accessible vendor forms (listed below) specifically designed to enable an AR System or ITSM
application team to create a comprehensive, end-user-facing AR form-based data management
user interface.
Regular forms that allow you to configure Atrium Integrator engine settings are also provided. With
these forms you can:
List, execute and schedule transformations and jobs
Provide the execution status for transformations and jobs
Allow Atrium Integrator engine parameters to be configured
Page 1042 of 4705
Home
The Unified Data Management (UDM) administrator can access all UDM forms on BMC Remedy
AR System. UDM users have access to a subset of the forms as shown in the following table.
AR System Forms for UDM Admin and UDM User
Form name
Form type
UDM Admin role access
UDM User role access
UDM:Config
Regular
UDM:Execution
Vendor
UDM:ExecutionInstance
Regular
UDM:ExecutionStatus
Vendor
UDM:Import
Regular
UDM:JobEntryLog
Regular
UDM:JobLog
Regular
UDM:LoggingChannelLog
Regular
UDM:PermissionInfo
Regular
UDM:RAppPassword
Regular
UDM:RepositoryObject
Vendor
UDM:ScheduleProcessor
Vendor
UDM:StepLog
Regular
UDM:StepPerformanceLog
Regular
UDM:StepStatus
Vendor
UDM:TransformationLog
Regular
UDM:Variable
Regular
UDM:CartePending
Regular
Configuration form
The UDM:Config regular form contains connection details for the Atrium Integrator repository and
Atrium Integrator engine. The repository is created when the AR System server is installed, and the
parameters are configured with default settings from the AR System server. The settings are stored
in the UDM:Config form fields and can be modified by users with AR System administrator level
access.
UDM:Config form
Page 1043 of 4705
Home
The Repository Connection Details section includes these fields:

Private RPC Program Number A private RPC queue for all operations (such as, load
and save) on the repository. The default value is 0 for no private RPC queue.
API Timeout Normal (seconds) The API time for all operations (such as, load and save)
on the repository. The default value is 7200 seconds.
The Atrium Integrator engine Details section includes these fields:
Atrium Integrator Server Name The name of the server hosting the Atrium Integrator.
By default this is the AR System server name.
Host The host name assigned to the server hosting the Atrium Integrator server. By
default this is the AR System server host name.
Port The server port assigned to the Atrium Integrator server.
Execution form
The UDM:Execution vendor form is used to execute transformations and jobs. Creating a new entry
for this form leads to the execution of the specified operation on the specified transformation or job
listed on the form. If the requesting user does not have permission for the requested transformation
or job, an error is returned.
To execute a transformation or job, you must first create an execution instance by creating a row in
this form.
1. In the Operation drop-down, select Create Execution Instance.
2. Add a unique name in the Execution Instance Name field.
This execution instance can be started, stopped, paused, or removed by creating another record
with the same Execution Instance Name and a new Start, Stop, Pause or Remove operation.
UDM:Execution form
Page 1044 of 4705
Home
Use these fields to set up your transformation or job execution:

Name (required) The name of the transformation or job object to be executed.
Type (required) The type of the object to be executed, either Transformation or Job.
Directory (optional) The repository directory location of the object to be executed. This is
required for the Create Execution Instance operation, and an object ID is not specified.
Object ID (optional) The ID of the object to be executed. This is required for the Create
Execution Instance operation and a repository directory is not specified.
Execution Instance Name (required) An unique name used to identify the execution
instance.
Log Level (optional) The level of logging to be used for the execution. This can be set to
any of the following:
Nothing
Error
Minimal
Basic
Detailed
Debug
Row level If this is left blank, the Minimal logging option is used.
Operation (required) This specifies the type of operation to be executed. The available
operations are:
Create Execution Instance An execution instance is created with the given instance
name. The ARDBC plug-in sends the transformation or job definition to the Atrium
Integrator engine. The Atrium Integrator engine then loads the transformation or job
definition into memory and creates and execution instance. If the combination of
instance name and transformation or job name is not found to be unique an error will
be thrown.
Start Execution Instance Start running the execution instance.
Stop Execution Instance Stop an execution instance that is currently running.
Pause Execution Instance Pauses an execution instance that is currently running.
This only applies to transformations.
Page 1045 of 4705
Home
Resume Execution Instance Resumes an execution instance that is currently

paused. Note that this also only works for transformations.
Remove Execution Instance Removes an execution instance from the Atrium
Integrator engine server's memory.
Variable Set Name (optional) Optional. Specifies the variable set to be used for this
execution instance. The ARDBC plug-in will query all the variables from the UDM:Variable
form that contain this variable set name. It will pass all variables to the Atrium Integration
engine server for this execution instance.
Related topics
Execution instance form
Variable form
Execution Instance form

The UDM:ExecutionInstance regular form allows multiple instances of the same transformations to
be run. For each execution instance that is created, the Atrium Adapter engine returns an identifier
called the Atrium Integrator Object ID. A combination of transformation or job name and Atrium
Integrator Object ID is used as a unique key and is used internally by the system to identify different
instances of the same transformation. However, externally, the unique execution instance name is
used to identify the unique execution instances.
UDM:ExecutionInstance form
Page 1046 of 4705
Home
Note that you cannot use this form to create a new Execution Instance, you can only use it to view
existing Execution Instances that were created from by the Create Execution Instance operation the
UDM:Execution form.
The UDM Execution Instance form contains the following fields:
Name The name of the transformation or job object to be executed.
Type The type of the object to be executed, either transformation or job.
Execution Instance Name (required) A unique name to be used to identify the execution
instance.
Atrium Integrator Object ID Internal unique identifier assigned by the Atrium Integrator
engine for the execution instance.
Directory The repository directory location of the object to be executed. This is only
needed when an object ID is not specified.
Page 1047 of 4705
Home
Object ID The ID of the object to be executed. This is only needed when a repository
directory is not specified.
Log Level The level of logging to be used for the execution. The default value is Minimal
logging. Selections include:
Nothing
Error
Minimal
Basic
Detailed
Debug
Row level
Atrium Integrator Engine Server Name (required) The name of the Atrium Integrator
server.
Variable Set Name Specifies an optional variable set to be used by the execution
instance.
Permissions Specifies the assigned permissions or role.
Execution Status form

The UDM:ExecutionStatus vendor form is used to monitor the execution of a transformation or job
instance. It contains a table that allows you to view the execution status of the steps of a
transformation or job.
UDM:ExecutionStatus form
Page 1048 of 4705
Home
Use this form to search for the current execution status of a transformation or job instance. The
following types of searches are supported:
Search by Type (transformation or job)
Search by Name and Type
Search by Name, Type and Execution Instance Name
No qualification (lists the status of all existing execution instances)
For each search result, the following attributes are returned in the form:
Name The name of the transformation or job object.
Type The type of the object, either a transformation or job.
Execution Instance Name The unique name to be used to identify the execution
instance.
Status The status of the transformation or job. For example, Running, Waiting, Stopped,
or Finished, etc.
Error An error description if one exists.
Number of Errors Displays error quantity.
Number of Lines Updated Displays quantity of lines modified.
Number of Lines Input Displays quantity of lines the file input.
Number of Lines Output Displays quantity of lines output by the file.
Number of Lines Read Displays quantity of lines read from the repository.
Number of Lines Written Displays quantity of lines written to the repository.
Number of Lines Rejected Displays quantity of lines that were not written or read.
Log Displays logged string of execution instance.
Step Execution Status Table containing execution status of steps for the transformation
instance.
Import form
The UDM:Import regular form allows you to import a job or transformation definition file ( .kjb or .ktr)
into a BMC Remedy AR System form repository. To import the transformation or job into the
repository, create an entry in this form and attach the .kjb or .ktr file. To write over an existing job
or transformation, set the Duplicate Action field to Overwrite.
UDM:Import form
Page 1049 of 4705
Home
Import ID The ID of the import request.

Permissions Set permissions for Groups or Roles.
Note
For BMC Remedy AR System servers running Linux, default form permissions
must be set to valid values before a transformation is executed.
Data Tag Enter the required data for tagging import files.
Duplicate Action Select Error or Overwrite.
Instance ID A unique identifier for the import instance.
Type The type of the imported object, either a job or a transformation.
Status The status of the import request. For example, In Progress, Completed, or Error.
Error Message The error message text for the Error status type.
Job Entry Log form

The UDM:JobEntryLog regular form provides a view into the history of all job entries.
UDM:JobEntryLog form
Page 1050 of 4705
Home
For each log file, the following attributes are returned in the form:
Job Entry Log ID Unique identifier for the job in the log file.
Log Displays logged string of job run.
Batch ID Unique identifier for a batch of jobs.
Job ID Unique identifier for the job.
Job Name Unique label for a job.
Job Entry Name Unique label for a job entry.
Channel ID Unique identifier for the job's channel.
Lines Read Displays quantity of lines read.
Lines Written Displays quantity of lines written to the repository.
Lines Input Displays quantity of lines the file input.
Lines Output Displays quantity of lines output by the file.
Lines Updated Displays the quantity of lines revised.
Lines Rejected Displays quantity of lines that were not written, read or updated.
Log Date Displays month, day and year the log file was created.
Number of Result Rows Displays quantity of rows resulting from the job run.
Number of Result Files Displays quantity of files resulting from the job run.
Result Select Yes to view the job results.
Permissions The assigned permissions or role.
Errors Displays the quantity of errors resulting from a job run.
Created by Displays the job originator.
Modified by Displays the name of the last user to change the job file.
Create date Displays the month, day, and year the job was developed.
Modify date Displays the month, day, and year the job was last changed.
Page 1051 of 4705
Home
Job Log form

The UDM:JobLog form provides job logging information.
UDM:JobLog form
Batch ID Unique identifier for a collection of jobs.
Job ID Unique identifier for the job.
Job Name Unique label for a job.
Log Field Displays logged string of job run.
Status Select Start, End, Stop, Error, Running, or Paused.
Errors Displays the quantity of errors resulting from a job run.
Channel ID Unique identifier for a job channel.
Start Date Displays month, day and year the logging started.
End Date Displays month, day and year the logging stopped.
Replay Date Displays month, day and year the logging was restarted.
Dependency Date Displays month, day and year the log file dependency was inserted.
Permissions The assigned permissions or role.
Page 1052 of 4705
Home
Created by Displays the log file originator.

Modified by Displays the name of the last user to change the log file .
Create date Displays the month, day, and year the log file was developed.
Modify date Displays the month, day, and year the log file was last changed.
Logging Channel Log form

The UDM:LoggingChannelLog regular form creates channel logging information.
UDM:LoggingChannelLog form
Log ID Unique identifier for the channel log file.
Batch ID Unique identifier for a collection of channels.
Object Name Unique label for an object.
Object Copy Unique label for an object's duplicate.
Repository Directory Location of the object storage.
Object ID Unique identifier for the object.
Channel ID Unique identifier for the channel.
Parent Channel ID Unique identifier for the channel parent.
Root Channel ID Unique identifier for the base channel.
Logging Object Type Category of object to which the log applies.
File Name Label for the log file.
Permissions Permissions for users or roles.
Log Date Displays the month, day, and year the channel log file was created.
Created by Displays the channel log file originator.
Modified by Displays the name of the last user to change the channel log file.
Create date Displays the month, day, and year the channel log file was developed.
Modify date Displays the month, day, and year the channel log file was last changed.
Page 1053 of 4705
Home
Permission Info form

The UDM:PermissionInfo regular form contains lists of all repository objects such as
transformations, jobs, database connections, directories, slave servers, and corresponding user,
group, or role permissions. By default, all transformations and jobs are assigned public permissions
. Users with access to this form can modify the permission settings for repository objects.
UDM:PermissionInfo form
For executing jobs or transformations, a query is performed on the UDM:PermissionInfo form to

check if the user has permission to access the transformation or job object. If the user has access
permission, the execution is performed. If the user does not have access permission, an error
message is displayed.
The form contains the following fields:
Name The name of the repository object for which the permission is assigned.
Type Type of the repository object, transformation, job, directory, database connection, or
slave server.
Object ID Unique identifier for the repository object.
Directory ID Unique identifier for the directory of the job or transformation.
Atrium Integrator Server Engine Name Set an Atrium Integrator engine server name for
a particular transformation or job in this field. After you set an Atrium Integrator engine server
name for a particular transformation or job, then the ARDBC plugin always executes that
transformation or job on that particular Atrium Integrator engine server. In this way, you can
Page 1054 of 4705
Home
load balance the data integration jobs across multiple Atrium Integrator engine servers. If
you do not set an Atrium Integrator engine server name for a transformation or job then that
transformation or job will always be executed on the co-located Atrium Integrator engine
server.
Permissions The assigned permission or role.
RApp Password form

The UDM:RAppPassword form stores a Remedy Application (RApp) Service password for a
specific BMC Remedy AR System server. The AR System server installer populates this regular
form during AR System server installation. The ARInput, AROutput, and CMDB steps provided by
BMC use this form to make connections to the AR System server.
The BMC Remedy AR System user password is not stored as part of the AR System connection
defined in a transformation for security reasons. The steps provided by BMC use an impersonation
API to connect to the AR System server. These steps query this form with the server name defined
in the AR Connection to get the Remedy Application Service password for that server. The steps 1)
create an initial connection to the server using the Remedy Application Service user name and
password (queried earlier from this form), and 2) impersonate the user named in the AR
Connection definition.
By default, the installer populates this form with the current AR System server's name and Remedy
Application Service password. If you must create connections using a fully qualified domain name (
FQDN) or IP address, enter the alternative entries in this form. For example, if you want to create
remote server connections, enter information about the remote server in this form.
UDM:RAppPassword form
Page 1055 of 4705
Home
The form contains the following fields:

Server Name The AR System server name to which a connection must be created from a
transformation.
RApp Password The (Remedy) Application Service Password supplied during AR
System server installation.
Note
This password is supplied on the AR System Administration: Server Information
form Connection Settings tab and should remain the same for all AR system
servers.
Load Balancer names

If the AR System servers are configured in an environment where a load balancer is used, the
Server-Name parameter and the Server-Connect-Name parameter change.
The Server-Name parameter changes to the name of load balancer.
The Server-Connect-Name parameter changes to the name of AR System server on each
server.
If 1) a load balancer server name is provided for an AR System server connection in BMC-provided
Pentaho step (such as, ARInput, AROutput, or CMDB) or 2) if a load balancer is defined in the
UDM:Variable form, you must populate the UDM:RAppPassword form with the load balancer server
name and its password (which is the same as the Application Service Password on the other AR
System server.)
Note
If you change the application password you must also update the RApp password.
Repository Object form

The UDM:RepositoryObject vendor form lists all existing transformations and jobs from the
repository for which the current user has permissions.
UDM:Repository object vendor form
Page 1056 of 4705
Home
This vendor form supports three search methods:

Search by type Returns all transformations or jobs from all repository directories for which
the current user has permissions.
Search by type and directory Returns all transformations or jobs from a specific directory
for which the current user has permissions.
Search with no qualification or (1 = 1) qualification Lists all jobs from all repository
directories when the default value in the Type field is job.
Example
To view all transformation in the /bmc_samples directory:
1. Open the UDM:RepositoryObject form in Search mode.
2. Enter /bmc_samples in the Directory field.
3. Select Transformation in the Type field.
4. Press Search.
The UDM:RepositoryObject form contains the following fields for each object:
ID A unique identifier automatically created when a new repository object is created.
Name A name assigned to the object.
Type The type of the repository object such as a job or a transformation.
Directory The repository directory in which the transformation or job is stored.
Description An optional description provided by the user when creating the object.
Modified By The name of the user that last modified the object.
Modified Date The date and time the object was last modified.
Page 1057 of 4705
Home
Schedule Processor form

The BMC Remedy Action Request System (BMC Remedy AR System) job scheduling framework
uses the UDM:ScheduleProcessor form to execute a job on Atrium Integrator engine server. An
entry is automatically created in this form every time the scheduled interval, or time, elapses for a
scheduled job defined in the BMC Remedy AR System Job form.
UDM:ScheduleProcessor form
The form has the following fields:

Request ID The ID of the requesting BMC Remedy AR System Job form item.
Name The name of the scheduled transformation or job that is executed.
Params The job parameters from the AR System Job form.
Common Params Any common parameter assigned on the BMC Remedy AR System
Job form.
Step Log form

The UDM:StepLog regular form provides a view into the logging history of all step executions.
UDM:StepLog form
Page 1058 of 4705
Home
Step Log ID Unique identifier for the step in the log file.
Log Displays logged string of the step run.
Batch ID Unique identifier for a batch of step log files.
Trans ID Unique identifier for the related transformation.
Trans Name Unique label for the related transformation.
Step Name Unique label for the step.
CopyNr Unique number of copies.
Errors Displays the quantity of errors resulting from a step execution.
Created by Displays the step log file originator.
Modified by Displays the name of the last user to change the step log file.
Create date Displays the month, day, and year the step log file was developed.
Modify date Displays the month, day, and year the step log file was last changed.
Page 1059 of 4705
Home
Step Performance Log form

The UDM:StepPerformanceLog form provides a view into the logging history of the performance of
each step in any transformation.
UDM:StepPerformanceLog form
Step Performance Log ID Unique identifier for the step in the log file.
Batch ID Unique identifier for a batch of step log files.
Errors Displays the quantity of errors resulting from a step performance.
Sequence Nr Displays the order of step performance.
Input Buffer Rows Displays quantity of rows in the Input buffer.
Output Buffer Rows Displays quantity of rows in the Output buffer.
Created by Displays the step performance log file originator.
Modified by Displays the name of the last user to change the step performance log file.
Page 1060 of 4705
Home
Create date Displays the month, day, and year the step performance log file was
developed.
Modify date Displays the month, day, and year the step performance log file was last
changed.
Step Status form

The UDM:StepStatus form is used to monitor steps inside a transformation execution. The following
types of searches are supported:
Search by transformation name Returns the execution status of all steps from all
execution instances of the specified transformation.
Search by transformation name and execution instance name Returns the execution
status of all steps of a particular transformation execution instance.
No qualification Returns the step status of all transformation execution instances.
UDM:StepStatus form
For each step status returned in a search, the following attributes are displayed:
Transformation Name Unique label for the transformation.
Step Copy Number Unique identifier for a duplicate of the step.
Page 1061 of 4705
Home
Number of Lines Updated Number of updates in a database table or file.

Number of Lines Rejected Number of lines that were not written or read.
Number of Lines Read Number of lines read from previous step(s).
Number of Lines Written Number of lines written to next step(s).
Number of Lines Input Number of lines read from a file or database.
Number of Lines Output Number of lines written to a file or database.
Number of Errors Displays error quantity.
Status of the step Displays the step state.
Time (in seconds) Time required to execute the step.
Speed Number of rows processed per second.
Execution Instance Name Unique name for the transformation instance currently
executing.
Transformation Log form

The UDM:TransformationLog regular form provides a view into the logging history of all
transformation executions.
UDM:TransformationLog form
Batch ID Unique identifier for a batch of transformation log files.
Log Field Displays logged string of the step run.
Page 1062 of 4705
Home

Errors Displays the quantity of errors resulting from a transformation execution.
Created by Displays the transformation log file originator.
Modified by Displays the name of the last user to change the transformation log file.
Create date Displays the month, day, and year the transformation log file was developed.
Modify date Displays the month, day, and year the transformation log file was last
changed.
Variable form
All variables used in transformations and job fields require entries in the UDM:Variable regular form
. The variables allow sets of common variable values to be substituted and used when executing
transformations and jobs. Variables are permission-based and substituted at runtime, during the
execution.
UDM:Variable form
Page 1063 of 4705
Home
This form contains these fields:

Variable ID The ID assigned to the variable when it is created.
Created By The name of the user who created the variable.
Name The name of the variable name.
Variable Set Name Name for a variable set. A variable set can contain multiple variables
that are designed to work together. You need to provide this variable set name when
creating an execution instance using the UDM:Execution form. The ARDBC plug-in takes all
the variable names and values for the provided variable set name from this form and passes
it to a transformation or job execution instance on the Atrium Integration engine server. See "
Variable sets" below.
Value The value of the variable.
Encrypted Value An optional encrypted value for the variable. See "Encrypted variables"
below.
Assignee Group Permissions The assigned permission or role required to use the
variable.
Variable sets
A variable set is a group of variables with a unique variable set name associated with a specific job
or transformation. Each variable must be associated with a variable set. Variables defined by the
current user take precedence if more than one variable with the same name is part of the same
variable set.
Page 1064 of 4705
Home
Encrypted variables
Variable values may be encrypted. If a value has been assigned in both plain text and encrypted
fields, the encrypted value takes precedence over the plain text value. All variable values, such as
a database password, should be encrypted.
Carte pending form

The UDM:CartePending form provides information of all the new and in-progress jobs running on
Carte servers. This form is used internally to fail-over new and in-progress jobs.
UDM:CartePending form
Use these fields to see the details of new and in-progress jobs:
Name: Enter specific job or transformation.
Type: The type of the repository object such as a job or a transformation.
Directory: The repository directory in which the transformation or job is stored
Atrium Integrator Engine Object ID: Internal unique identifier assigned by the Atrium Integrator
engine for the execution instance.
Object ID: Unique identifier for the repository object
Atrium Integrator Engine Server Name: The name of the server hosting the Carte server.
Job-Transformation Status: Choose to view jobs with status New and In Progress
Job Configuration XML: Lists the details of all the New or In progress jobs depending on the
selection.
Atrium Integrator Spoon client

The Atrium Integrator Spoon is a client side, user installable graphical user interface application
which is used to design transformations and jobs. These transformations and jobs are saved, and
then accessed and executed by the Atrium Integrator adapter for BMC Remedy AR System. The
Spoon client also allows you to define and create the AR Connection modules which enable the
transformations to use AR Systerm database transactions.
Page 1065 of 4705
Home
For complete documentation on creating transformations and jobs using the Atrium Integrator
Spoon client, see the third party documentation.
Accessing the Atrium Integrator Spoon application

The Atrium Integrator Spoon application is installed from the standard BMC Remedy AR System
installation program as one of the installable client program options. For more information about the
BMC Remedy Action Request System installation procedures, see Installing old.
Once installed, the application can be accessed from the Windows Start menu, under Programs,
under the BMC Software folder. AR System administrator permissions are required to log on and
use the Spoon client.
Scheduling and manually executing a transformation or job

Atrium Integrator uses workflow-based forms and scheduling operations in AR System to schedule
transformations or jobs for execution.
To schedule a transformation or job

1. Create an execution instance on the AR System server using the UDM:Execution form.
2. Select Create Execution Instance in the Operation field.
3. Create an entry in the AR System Job form and include the date, time, and recurrence.
4. Create an entry in the AR System Job Item form with the Atrium Integrator transformation or
job name and execution instance name created in step 1.
When a job is executed in this framework, an entry is automatically added to the UDM:
ScheduleProcessor form. This form then processes the job based on the job parameters.
The scheduling framework provides a escalation that runs hourly and retrieves due jobs from AR
System Job form. The due jobs are moved to a pending queue where the pending queue processor
writes each job item entry to appropriate vendor form based on a job type mapping provided in the
AR System Job Type Mapping section.
For the "pentaho" job type, AR System places an entry into the UDM:ScheduleProcessor vendor
form. The ARDBC plug-in form receives all the parameters, such as the transformation or job name
, type and execution instance. Then it starts the execution instance on the Atrium Integration engine
server using these parameters.
To manually execute a transformation or job

1. Create an execution instance on the AR System server using the UDM:Execution form.
2. Select Create Execution Instance in the Operation field.
3. Assign the other fields on the form as necessary.
4. Use the UDM:Execution form to create another entry.
5. Select Start Execution Instance in the Operation field. (You can also stop, pause/resume, or
remove an execution instance by configuring another value in the Operation field.)
Page 1066 of 4705
Home
Running external processes with the Run

Process action
Run Process actions can be used for integration on both the BMC Remedy AR System clients and
servers.
Running external processes introduction
Triggering Run Process on clients and servers
Starting applications with the Run Process action
Retrieving data from applications with Run Process
Using Run Process for the web
Running external processes introduction

One of the simplest ways to integrate two applications is to execute one application from within
another. BMC Remedy AR System enables you to include execution of external applications as
part of workflow to enhance or supplement the features of BMC Remedy AR System.
The reverse case, where another application executes an AR System client, is also valid. See
Beyond simply starting the external application, BMC Remedy AR System provides process-control
functionality for these types of integration:
Data passing and retrieving When BMC Remedy AR System executes external
applications (either manually or automatically), information from any form in the AR System
database can be extracted and passed as run-time arguments. You can also retrieve data by
using a Run Process command and place it in a field.
Client and server execution External applications can be executed locally on the AR
System client, or remotely on the AR System server.
Synchronously and Asynchronously Run Process on a filter and escalation is
asynchronous. All other Run Process commands (including $PROCESS$ in a Set Fields
action) run synchronously.
Executing an external process is done using the Run Process workflow action, available for filters,
active links, and escalations, or in a Set Fields action with the $PROCESS$ keyword.
For additional information, see Run Process action.
Triggering Run Process on clients and servers

The Run Process action can be triggered on both AR System clients and servers.
Page 1067 of 4705
Home
All three workflow components can run processes to provide centralized integration on the server.
In addition, active link processes can provide local integration on the clients.
Starting applications with the Run Process action

The Run Process action starts an external application. Depending on the function and behavior of
the application, it can be started through any of these means:
By a user (from an active link)
Automatically under certain states (from a filter)
Automatically under certain time conditions (from an escalation)
For example, a paging program can be called whenever a record marked Urgent is entered into the
database (a filter action), or when such a record has not been accessed for two days (an escalation
action). When the application is started, data from the current form can be passed as run-time
arguments to the application.
Opening a reference document from an active link button scenario
Calling a pager application from a filter scenario
The Run Process action simply executes an independent process; it does not return a value to the
calling program.
Executing another application
Page 1068 of 4705
Home
Unlike active links, which run with the access control permissions of the user, filters and escalations
run with the permissions of the administrator and thus have access to all form fields. Consider this
when you define filter or escalation actions because they can have security implications.
On a Windows server, a filter or escalation can run only processes that run in a console (like a .bat
script) or that create their own windows.
The processes that an active link launches can run on the local client machine or the server. They
are often triggered by actions taken by the user. For example, an external email program could be
started whenever the user clicks a button on an AR System form, or a problem resolution tool can
be invoked when a problem description is entered into a field.
An example of a Run Process action definition for an active link is shown in the following figure.
When the active link is triggered, the system executes the command specified in the Command
Line field, which launches a related process. To make sure that the executable is correctly
Page 1069 of 4705
Home
executed on the client machine, specify its full path name. When the application is started, data
from the current form can be passed as run-time arguments to the application.
Defining a Run Process action for an active link
When designing an active link that uses a Run Process action on the client, always consider the
variety of client platforms that users will use. Keywords can be used in the Run If expression for the
active link to verify that the client is on an appropriate platform. For more detail about the possible
values for $CLIENT-TYPE$, see the AR_CLIENT_TYPE constants defined in
ARSystemServerInstallDir\api\include\ar.h. If the active link is to be supported on multiple

platforms, each platform might require its own active link with an appropriate qualification.
Opening a reference document from an active link button scenario

In this scenario, you want to open reference documents that are in Word format from your help
desk application.
To open a reference document from an active link button

1. Create a form named Ref Docs that has two fields:
Document Name Contains the name of a reference document.
Doc Location Contains the path to where the document is stored.
2. Enter data for all of your documents into this form.
3. On the appropriate form of your help desk application, add two fields:
Reference Documents A visible field that has a Search Menu attached that
queries the Ref Docs form to build a menu of all of the Document Name titles.
Path A hidden field that is filled in using a Set Fields active link with the
corresponding Doc Location path whenever a Document Name is selected from the
menu on the Reference Documents field.
4.
Page 1070 of 4705
Home
4. On the same help desk application form, create an active link triggered by a button labeled
Open Document.
The qualification on the active link is that the Reference Documents field is not empty. The
active link action is to do a Run Process with a Command Line specification of something
like:
C:\program~1\micros~1\office\winword.exe $Path$
When a reference document is selected from the menu and the active link button clicked,
Word starts, and the selected document appears.
Calling a pager application from a filter scenario

When a service request is submitted or modified with a severity of Critical, you want to send a
pager message to the person identified in the Responsible Person field on the request. You use a
pager application called TelAlert.
You need a filter that has the following characteristics:
Executes on Submit or Modify
Runs if
'TR.Severity' = "Critical" AND 'DB.Severity' != "Critical" AND 'Responsible Person' != $
NULL$
In other words, it runs whenever a trouble report is set to Critical for the first time and the
Responsible Person field is not blank.
Sends a pager message to $Responsible Person$.
You would use the following command for the Run Process filter:
/usr/telalert/telalertc -c PageMart -PIN $Pager Access Number$

-m "Trouble Report $Call ID$ has just been set to Severity =
Critical."
This command performs the following actions:

It calls the TelAlert application. It uses the telalertc executable, which is the standard
TelAlert client, instead of the telalert executable, which is the client plus the administration
function.
The -c parameter tells TelAlert to use the PageMart configuration information in the
telalert.ini file.
The -PIN parameter takes the value of the field Pager Access Number and passes it to
PageMart to identify the specific pager that should receive the message.
The -m parameter specifies the message that is to be sent to the pager. The value of the
Call ID field is substituted into the message text.
Page 1071 of 4705
Home
Retrieving data from applications with Run Process

Another type of action, Set Fields, enables you to include workflow that automatically sets the
contents of fields from a variety of data sources.
These data sources include fixed values, values read from other forms (possibly in other databases
), values from arithmetic operations or functions, and values returned by external applications.
Using the $PROCESS$ keyword of the Set Fields action, BMC Remedy AR System can execute
an application and set the output of the application in various data fields. You can run only a
process that behaves as follows:
Runs in a console (such as a .bat script or runmacro.exe ), but not in a GUI application.
Returns 0 if successful. (In this case, stdout is pushed to the field.) If the process returns
anything other than 0, stdout displays an error message.
Whether you use an active link, filter, or escalation depends on the purpose of the external
application. Active links can execute locally on the client machines or on the server. Filters and
escalations execute only on the server.
Retrieving data from another application
Page 1072 of 4705
Home
When an external application is run on the server, BMC Remedy AR System waits for the process
to terminate so that it can capture and interpret the output of the process. To avoid situations where
BMC Remedy AR System waits indefinitely for a process that fails to terminate, a process time-out
is built into BMC Remedy AR System. This time-out can be configured for between 1 and 60
seconds, using the AR System Administration: Server Information form.
In a Set Fields definition, the keyword $PROCESS$ indicates that all following text is a command.
Use the full path name to the executable. AR System data field values can be passed as
parameters. When using active links, remember that they run with the access control of the user, so
access to form fields might be limited.
When workflow that performs a Set Fields action is fired, the process starts, and the web client
waits for it to complete. (In UNIX, the process runs in a Bourne shell.) All returned data is read by
the web client and processed according to the return status of the process:
Page 1073 of 4705
Home
If the return status is zero, the data is used as the new value for the field.
If the process returns with a status other than zero, the web client assumes the process
failed and does not update the field contents. Instead, the output from the process is used as
an error message and displayed to the user.
When designing an active link that uses a $PROCESS$ Set Fields action on the client, always
consider the variety of client platforms that users will use. The keywords $HARDWARE$ and $OS$
can be used in the Run If expression for the active link to verify that the client is on an appropriate
platform. If the active link is supported on multiple platforms, each platform requires its own active
link with an appropriate qualification.
Note
You can run a process on a server by inserting @ serverName: before the process name
in an active link. For example, $PROCESS$ @ServerA: C:/temp/process.exe If it is the
current server, you can use @@ instead of @ serverName.
An example of a Set Fields action for a filter is shown in the following figure. In this example, the
action sets the values of two fields by executing a separate utility program for each one, passing
values of existing fields as parameters. If the programs execute correctly (that is, return with an exit
code of zero), their outputs are assigned to the respective fields.
Defining a Set Fields action using $PROCESS$
Page 1074 of 4705
Home
Using Run Process for the web

JavaScript is an HTML scripting language that allows you to create programs that reside directly on
an HTML page. An active link can use the Run Process action to run JavaScript on the browser.
The JavaScript code must have the word javascript in front if it. For example, the following code
shows an alert box with "Hello world" in it:
javascript alert("Hello world");
You can use keywords and field references in the JavaScript, for example:
javascript alert("You are in $SCHEMA$ and Submitter is $2$");
In several BMC Remedy applications, the user is shown a table of related tickets along with the
primary ticket. These related tickets can be from different forms. A special form is maintained,
which records relationships between tickets. The related tickets table field shows this special form.
When the user double-clicks on any of the related tickets, instead of showing the special form to the
user, an open window action opens the form that has the ticket data.
JavaScript considerations
All the Run Process JavaScript actions are grouped together and executed at the end of the
active link. For example, if you have a Run Process action followed by a Set Fields action,
the Set Fields action is executed before the Run Process action.
Some JavaScript code is asynchronous. For example, openModifyForm starts the process of
opening the form, but does not wait for the action to complete. So it is not possible to have
another Run Process action that clicks a button on the newly opened form.
Any special characters in JavaScript must be properly escaped. For example, if the action
has JavaScript alert("Short Description is $8$") and the Short Description value contains a
double quote or a backslash or a new line, a JavaScript error occurs.
If the word javascript is not at the beginning of a run process action, it says "The following
specific error(s) occurred when executing 'xx', " but it does not say what the error is.
Run Process considerations

Active links that run a process on the client should have qualifications that limit usage to an
appropriate client platform. The keyword $HARDWARE$ can be used to check for the client
platform. On UNIX machines, $HARDWARE$ returns the value of the command uname -m.
On the Windows clients, it returns the value PC.
On UNIX machines, processes run under the Bourne shell.
When passing data fields as parameters to external programs, enclose the arguments with
double quotation marks if the value might contain spaces or special characters.
Page 1075 of 4705
Home
The $PROCESS$ feature of the Set Fields action is effective for dynamically pulling or
loading small amounts of data on the AR System client or server. For large amounts of data,
use the API.
The Run Process string can have a maximum length of 4096 bytes. To execute large scripts,
use field references to build the script's data.
For information about special Run Process commands, see the Developing an application
section.
Integrating the BMC Remedy Assignment

Engine into an application
This section explains how to integrate the BMC Remedy Assignment Engine with your application,
starting with the following overview of the process.
To integrate the BMC Remedy Assignment Engine with your

application
1. Create a form that holds the assignees, and add the appropriate Assignment Engine fields to
this form. See Preparing for the auto-assignment process.
Tip
For simple applications, you could use the User form to hold this information.
2. In the request form to which you want to assign users, create the fields that the Assignment
Engine sets on assignment. See Preparing for the auto-assignment process.
3. Create or add the assignee and request forms to the Assignment Engine. See Adding
assignee and request forms.
4. Create rules for assignments. See Adding assignment rules.
5. Create processes for assignments. See Adding assignment processes.
Preparing for the auto-assignment process
Adding fields to the assignee and request forms
Adding assignee and request forms
Adding assignment rules
Setting sequencing for rules
Adding and executing assignment processes
Page 1076 of 4705
Home
Preparing for the auto-assignment process

To begin the auto-assignment process, identify the following types of forms:
Assignee form Contains data about people or groups to whom you want to assign
requests. This form is the source form that holds information for the request form.
A single process can have multiple assignee forms.
Request form Is used to assign a request. An example might be a Help Desk form to
which Support representatives are assigned tickets. This is the target form that receives
information from the assignee form.
To prepare for the auto-assignment process

1. Create an assignee form.
Tip
You can also use the User form that is installed with BMC Remedy AR System.
2. On the assignee form, create the fields listed in Adding fields to the assignee form .
Hide the fields that you do not want users to see.
3. On the request form, create the fields listed in Adding fields to the request form .
Hide the fields that you do not want users to see.
Adding fields to the assignee and request forms

The following topics provide information about the fields on the assignee and request forms.
Adding fields to the assignee form
Adding fields to the request form
Adding fields to the assignee form

The assignee form must contain the following fields, which the Assignment Engine uses to run its
processes. These fields are mapped to the fields on the Assignee Form Fields tab of the
Assignment Engine Forms dialog box.
Assignee Unique ID
A field containing a unique identifier that distinguishes one assignee from another. This
can be a GUID field. See the Using character fields to generate GUIDs.
Instead of creating this field, you can use the Request ID field (ID 1) as the unique identifier.
Then, you can add the following optionalfields to this form:
Assignee Group Unique ID The unique instance ID for the assignee group.
Assignee Name/Login The name of the assignee.
Page 1077 of 4705
Home
Assignee Delivery Method A field used to store the method to notify the assignee
of the assignment.
Number Assigned An integer field used to obtain and set the current number of assigned
issues for each possible assignee.
If you use the Load Balance by Number or the Load Balance by Capacity auto-assignment
method, this field is required.
Capacity Rating A decimal field used to obtain the capacity rating for each possible
assignee.
This field is required for the Load Balance by Capacity auto-assignment method.
Last Assigned Time A decimal field used to obtain the last time an issue was assigned
to each possible assignee and to set the last assigned time for the successful assignee.
This field is required for the Round Robin auto-assignment method.
Last Assign Time (Display) A date/time field used to obtain the last date and time an
issue was assigned to each possible assignee and to set the last assigned time for the
successful assignee. This is an optional field.
Adding fields to the request form

The request form must contain the following fields, which the Assignment Engine uses to run its
processes. The following field is mapped to the fields on the Request Form Fields tab of the
Assignment Engine Forms dialog box.
Assignee Unique ID Character field that stores the selected assignee's unique ID.
Optionally, you can add the following fields:

Assignee ID Field Stores the Entry ID of the successful assignee.
Assignee Form Stores the name of the assignee form.
Return Code Field Stores the code for success or failure of the assignment. This field
can be used for debugging purposes.
Return Code Description Stores the successful Assignment Rule ID and the Assignment
Qualification ID if the assignment was successful, or an error code if the assignment failed.
This field can be used for debugging purposes.
Reason Code Field Stores the GUID of the executed rule.
Adding assignee and request forms

Before setting up the assignment rules and the assignment process, add the assignee forms and
request forms to which the rules apply.
To add an assignee form

1. Open the Assignment Engine Administration Console.
2. Click the Forms tab.
3.
Page 1078 of 4705
Home
3. Click Create to create assignee forms, or click Search to search for assignment forms.
The Assignment Engine Forms dialog box appears.
4. In the Form Name list, select the assignee form for which you want to build the assignment
process.
5. In the Display Name field, enter a display name for the form you selected.
The display name appears in the Form Name column on the Forms tab and in the
Assignee Form list on the Assignment Rule form.
6. For Form Type, select Assignee form.
7. In the Status list, select Active.
If you do not want to use the form at this time, select Inactive.
8. Optionally, specify a Localefor this assignment form.
Note
If the Localize Server option on the Advanced tab of the AR System
Administration: Server Information form is not selected, all records appear,
regardless of the client's locale. If it is selected, some rules apply. See Setting
performance and security options and Setting the Localize Server option.
9. In the Assignee Group Permissions field, select the group to give access to.
10. On the Common Fieldstab, complete the following fields:
Assignee Unique ID The unique identifier for the assignee (an individual user).
For example, you might select Request ID or Assignee ID.
Optional fields:
Assignee Group Unique ID Unique instance ID for the assignee group.
Assignee Name/Login Login name or full name of the assignee.
Assignee Delivery Method Field in the assignee form used to store the method to
notify the assignee of the assignment.
11. Click the Assignee Form Fields tab and map the fields from the form you selected.
For more information, see Adding fields to the assignee and request forms .
Assignee Form Fields tab
Page 1079 of 4705
Home
12. Click Save.
To add a request form

2. Click the Forms tab.
3. Click Create to create request forms, or click Search to search for assignment forms.
The Assignment Engine Forms dialog box appears.
4. From the Form Name list, select the request form for which to build the assignment process.
5. In the Display Name field, enter a display name for the form you selected.
The display name appears in the Form Name column on the Forms tab and in the Request
Form list on the Assignment Rule form.
6. For Form Type, select Request form.
7. From the Status field menu, select Active.
If you do not want to use the form at this time, select Inactive.
8. Optionally, specify a Localefor this assignment form.
Note
Page 1080 of 4705
8.
Home
If the Localize Server option (on the Advanced tab of the AR System
Administration:Server Information form) is not selected, all records appear,
regardless of the client's locale. If the option is selected, some rules apply. See
Setting performance and security options and Setting the Localize Server option.
9. In the Assignee Group Permissions field, select the group to give access to.
10. On the Common Fieldstab, complete the following fields, which are mapped from the
assignee form:
Assignee Unique ID The unique identifier for the assignee (an individual user).
For example, you might select Assignee ID.
Optional fields:
Assignee Group Unique ID The unique instance ID for the assignee group.
Assignee Name/Login Login name or full name of the assignee.
Assignee Delivery Method Method to notify the assignee of the assignment.
11. Click the Request Form Fields tab, and map the fields from the form you selected.
For more information, see Adding fields to the request form .
Request Form Fields tab
12.
Page 1081 of 4705
Home
12. Click Save.
Adding assignment rules

All assignment processes must have rules. A process can have multiple rules in sequential order.
Because assignment processes can share rules, modifying a rule affects all assignment processes
associated with it.
Note
Unrelating a rule from a process removes its relationship with that process but retains the
rule for other assignment processes.
To add an assignment rule

2. Click the Rules tab.
3. Click Create.
The Assignment Rule dialog box appears.
4. Enter information in the required fields:
a. In the Rule Name field, enter a rule name.
b. From the Assignee Form list, select an assignee form.
c. From the Request Form list, select a request form.
The Request Form field contains the form references in the Process Definition form.
The rules that you define fill in the assignment-related fields on the request and
assignee forms. These request and assignee forms are external to the Assignment
Engine and part of a separate application. The only requirement for these forms is
that they have the necessary fields on them to be read and written from the
Assignment Engine software. The requirements for these fields vary depending on
which Assignment Engine rule methods are used.
d. Make sure that Status is set to Active.
e. In the Assignment method field, select an assignment method. See Integrating the
Assignment Engine into an application.
5. Enter a qualification for the assignment rule.
A qualification string is a specified set of conditions used to make the automatic assignment.
The Assignment Engine applies the qualification defined here to try to assign a request to an
assignee.
The easiest way to build a qualification string is to select the keywords and form fields
directly from the bar and lists. When you do that, the correct syntax is automatically entered.
Assignee form fields use single quotation marks, and Request form fields use dollar signs.
For example:
Page 1082 of 4705
Home
('Support Group ID' = $Support Group ID$) AND ('Assignment

Availability' = "Yes") AND ('Assignment Availability 2' =
"Yes") AND ('Profile Status' = "Enabled")
6. Click Save.
Setting sequencing for rules

Rules are applied according to a specified sequence. If the first rule is valid, it is applied. If the first
rule is unsuccessful, the Assignment Engine process tries the second rule, and so on.
To specify sequencing for rules

2. From the Process tab, select the process for which you want to sequence rules.
3. Click View.
4. In the Process Definition dialog box, perform one of these actions:
If rules are defined for the process, select the rule to reorder.
If no rules are defined for the process, click Create to create rules (see Adding
assignment rules). Select the rule to reorder.
5. Use the arrow keys to order the rules in the sequence in which you want the Assignment
Engine to use them.
6. Click Save and Close.
Adding and executing assignment processes

After you set up the assignee and request forms, you can add and execute assignment processes.
To add an assignment process

2. Click the Processes tab, and click Create.
The Process Definition form appears.
3. In the Process Name field, enter a descriptive name for the process.
Note
BMC recommends that you use unique process names.
4. In the Request Form field, select a form that creates the requests to which you want to
assign users.
5. (Optional) Enter a description of the process.
6.
Page 1083 of 4705
Home
6. Click Create to create a rule.

See Adding assignment rules.
7. Specify a sequence for the rules.
The rules apply according to the order in which they appear. See Setting sequencing for
rules.
Note
The order of the rules is important. The most specific rules should be at the top of
your list because the Assignment Engine processes the rules from top to bottom
and makes an assignment when it finds a match.
8. Make sure that the Status is set to Active.

9. Click Save.
10. To create additional processes, follow steps 3 through 9.
To execute an assignment process

To execute your assignment processes, you must create workflow for each process. The workflow
must execute the Application-Command AE-ASSIGN DoAssign Run Process command.
For information about the Application-Command AE-ASSIGN DoAssign Run Process command,
see Process commands.
For information about creating workflow, see Defining workflow to automate processes.
Using DSO with BMC Atrium CMDB

BMC Remedy Distributed Server Option (DSO) is designed for use with BMC Remedy AR System
server environments, which use workflow to transfer data from one environment to another. Using
workflow ensures that, in addition to data replication, other activities can take place that update the
data to increase its value.
Typically, DSO is used across two environments running BMC Remedy Incident Management. The
environments might be widely separated, and Support personnel might create a high volume of
incident tickets at each site, but for business reasons, both user communities often need to be
aware of all the tickets created, whether they originate at their local site or not. In such situations,
DSO is used to replicate tickets after they are created. Typically, a prefix is added to replicated
ticket IDs to differentiate them from other tickets in the system. Additionally, ownership of replicated
tickets can be altered so that a ticket worked on during normal business hours at one site can then
be reassigned to a remote site and worked on during its business hours (a follow-the-sun scenario
).
Page 1084 of 4705
Home
BMC Atrium Configuration Management Database (CMDB) is a core component in any BMC
Remedy IT Service Management (ITSM) environment and adds substantial value to a simple
Incident Management environment. Specifically, it makes incident management more efficient by
providing support staff and IT management an up-to-date image of their production IT environment.
Given this synergy between DSO and BMC Atrium CMDB, using DSO as a replication engine is
clearly useful for a global environment with these characteristics:
1. Multiple sites running Incident Management are creating tickets.
2. All sites need a common view of the global IT environment.
Note
The primary value of DSO is its ability to copy data through workflow and hence to
replicate data and execute business logic.
Workflow functionality is unnecessary, however, simply to duplicate an entire database at
a remote site, such as for disaster recovery. In this case, DSO has more functionality than
is required. Simpler solutions, such as database mirroring or basic database replication,
might be more appropriate. Such replication technologies typically do less processing per
data element and hence might provide increased throughput, decreased latency, and
lower costs. Although DSO functionally achieves the same goal and can be used simply to
duplicate data if desired, other techniques might provide more appropriate solutions for
such cases.
Setting up DSO to use CMDB data

Using DSO for replicating CMDB data is similar to other uses of DSO: it essentially transfers data
from a form in one AR System server to a similar form in a remote AR System server. At a high
level, you set this up as follows:
1. Create data mappings that define:
Which local forms will have data transferred to remote forms
Which remote forms will receive the data
2. Create workflow filters that:
Fire at appropriate times
Use the defined mappings to copy data to the remote server
Page 1085 of 4705
Home
After these tasks are performed, every time data is written to a local form to which the filters are
attached, a transfer corresponding to the mapping is entered in the Distributed Pending form. This
form maintains a queue of all send operations that need to be performed, and various access
methods for this queue can be configured. For example, push requests can be executed as quickly
as possible after they arrive in the queue, or they can be run at a later time, such as during a
night-time batch window.
DSO can transfer data in one direction or bi-directionally between two environments. For
bidirectional transfers, you must set both sites up identically so that each is a source and a
destination for DSO transfers. For information about setting up and using DSO, see Configuring
BMC Remedy Distributed Server Option and Setting up DSO to synchronize data across multiple
AR System servers.
Join forms and BMC Atrium CMDB

Join forms are a useful abstraction within the AR System server because they provide a single view
that incorporates data from multiple base forms. BMC recommends that you perform the read or
write operations on the join forms rather than the base forms because you can access fields from
both primary and secondary forms when you work on the join forms. For more information, see Join
forms.
To ensure integrity of the data, CMDB creates corresponding entries in the respective base forms
and form hierarchy based on the read or write operations performed on the join forms.
BMC Atrium CMDB provides another level of data abstraction on top of the AR System server
forms: an object-oriented class hierarchy in which each class is designed to hold data associated
with typical IT environment components and relationships. This set of classes is called the BMC
Atrium CMDB Common Data Model (CDM).
The CDM is implemented as a series of join forms; each subclass can break down into a join of
multiple base forms, each of which is associated with a parent class of the subclass. Hence, the
most effective way to use DSO to transfer data between two CMDBs is to create mappings and
filters on the join forms corresponding to the CMDB classes.
The join forms have the same names as the associated CMDB class. For example, BMC_DiskDrive
is the join form associated with the BMC_DiskDrive class. If you know exactly which CDM classes
you plan to use, you can create mappings and filters on just those classes. A safer approach,
however, is to create mappings and filters for the entire CDM. Then, if a discovery product
populates a class that was not expected to be used, the data is still successfully transferred to the
remote site.
Page 1086 of 4705
Home
Writing to the CMDB production dataset

The most common use of integrating DSO with Atrium CMDB is to perform CMDB reconciliation on
one site and then use DSO to transfer data directly from the production dataset of that site to a
remote production dataset. An alternative scenario transferring from a discovery data staging
dataset to a remote version of that dataset requires performing reconciliation at both sites, thereby
duplicating processing requirements.
Note
BMC recommends that you should avoid writing to the production dataset directly. If you
are sure that there is no harm in writing directly, you might proceed with the operation.
By default, the only authorized writer to the production dataset is the CMDB Reconciliation Engine.
Any other data source should be written to a staging dataset and then reconciled to update the
production dataset. This protects the production image of an IT environment, a business-critical
asset. To use DSO to replicate the CMDB at a remote site, however, you must break this rule
based on your knowledge that the data you are inserting into the production dataset has been
successfully reconciled on the other site.
A mechanism enables an authorized user (who is not the Reconciliation Engine) to write to the
CMDB production dataset. Each CMDB base form contains a hidden field named
zCMDBEngOverrideCmd. The validation workflow that checks a users write permission first looks
at this value.
Data integrity is further protected by existing DSO functionality. Specifically, any failed transfer from
the local Distributed Pending form to the remote server is noted, and if the failure is due to a
connectivity issue, the data is retained until the transfer is confirmed as successful. However, if a
functional failure occurs, the data is not retained.
Examples of using DSO to replicate CMDB data

To use DSO to replicate CMDB data, you must first create mappings for each underlying join form
in the CDM for your version of BMC Atrium CMDB. CMDB identifies each CI with its InstanceID.
To replicate CMDB data

1. Create a mapping for the BMC.CORE:BMC_ComputerSystem form (Refer to the following
figure). Create such mappings for all CDM join forms.
Page 1087 of 4705
Home
2. In this form, perform the following:

In the To group, ensure that the Server Name value refers to the logical name of the
target server. You can create the logical server name in the Distributed Logical
Mapping form. For more information, see Distributed logical mapping.
To ensure that updates to existing CIs do not create errors, set the value of the
Duplicate Request ID Action field to Overwrite.
Clear the Match by Request ID check box.
In the Matching Qualification field, ensure that the two instances are matched based
on the InstanceID.
3. After all mappings are created, create the DSO filters for transferring data. (Create filters for
Submit, Modify, and Merge execute conditions because the remote CMDB might create or
update CIs at any time.)
Avoiding infinite loops

When you configure the DSO for bidirectional data transfer, you should be aware of the looping
issue that might occur. Use the following approach to avoid infinite loops.
Use the LastUpdatedDatasetId attribute defined in the top level classes in the CDM
hierarchy (BMC.CORE:BMC_BaseElement and BMC.CORE:BMC_BaseRelationship) to
avoid infinite loops.
Note
If you are using versions earlier than BMC Atrium 7.6.04, you need to add the
LastUpdatedDatasetId attribute explicitly. Where???? In the top level class definition????
Please confirm.
In the Distributed Mapping form, set the value of the LastUpdatedDatasetID attribute to the
name of the dataset ID of the target server.
Under the Transfer to Target area, set the mapping type as Custom.
Page 1088 of 4705
Home
In the DSO filter form, check whether the value of the LastUpdatedDatasetID attribute is set
to NULL.
Whenever an instance is DSOed from source to target, the LastUpdatedDatasetID attribute is set
with the name of the dataset ID of the target server, so that the DSO filter is not qualified for
execution. Similarly, when the instance gets updated the value of the LastUpdatedDatasetID
attribute is set to NULL thereby qualifying the DSO filter for execution. Use this approach to avoid
the looping issue when you are not using DSO to write directly to the production dataset.
Note
If you are using DSO to write directly to the production dataset, see Avoiding infinite loops
to avoid the looping issue.
Recommendations for using DSO with BMC Atrium CMDB

The most effective use of DSO in this solution is for incrementally updating the CMDB. Generally,
the CMDB is initially populated by a full load before the system goes live. After the full load is
completed, the database containing the fully populated CMDB can be physically copied to the
remote site so the two sites start with an identical image of the CMDB. This reduces the need to
copy potentially millions of CIs all at once.
After the system goes live, the CMDB is periodically updated to include new or changed CIs that
are identified in the IT environment by discovery sources. The number of CIs involved in the
incremental updates is typically much smaller than the total number of CIs in the CMDB. For
example, a site whose CMDB contains roughly one million CIs might have daily updates that
involve 0.1% to 1% of those CIs, which means 1,000 to 10,000 CIs need to be transferred by DSO.
Larger daily updates are possible, particularly if software distribution and patching are done
automatically across the enterprise, but they are much less common.
Timing of the DSO transfers should be considered within the context of overall operational planning
for the CMDB. Specifically:
Discovery scans are scheduled as the source for new and changed CIs.
Reconciliation jobs are scheduled to synchronize the production dataset with new discovery
data.
As the production dataset is updated, the DSO Distribution Pending queue accumulates
pending push operations.
Page 1089 of 4705
Home
For fastest updates of the CMDB, configure DSO to consume the queue as soon as possible. This
is the recommended setting, assuming that reconciliation is scheduled to impact online users as
little as possible (for example, it is scheduled during a batch window at night). A modest overhead
of CPU consumption is expected during DSO usage. So, if the system is heavily used or if
concurrent users might be impacted, configure DSO so that it consumes the pending queue in
another scheduled batch window.
Often, each site locally discovers its own IT assets, and a bidirectional DSO then shares the data
so that both sites can see information for the entire enterprise. You can implement this as a simple
bidirectional DSO transfer by performing the setup tasks described in Setting up DSO on both
servers. No asset, however, should be discovered by both sites. Because data is transferred after it
has been reconciled, if both sites try to write to the same CI, the CI might be updated with different
values by each site. The two sites will most likely discover identical information about the CI.
Therefore, as a best practice, BMC recommends that multiple sites should conduct local discovery
in nonoverlapping domains.
Performance considerations
By default, DSO runs as a single-threaded process writing to remote AR System forms. Excluding
network latency and bandwidth constraints, such an operation has throughput similar to other such
write operations (approximately for 10 DSO pools, 21 CIs per second in BMC Atrium CMDB 8.0
with BMC Remedy AR System server 8.0).
To achieve higher throughput, you must use DSO pools, which are essentially independent sets of
DSO activity that can be processed in parallel. For CMDB data, however, both component CIs and
relationship CIs (sometimes called relationship items or RIs) must be transferred, and a relationship
CI cannot exist until its endpoints are created. Therefore, in DSO pools, make sure that all
relationship CIs are created after their associated component CIs . This is best achieved by making
sure that all data from a computer system is in one DSO pool (data from a computer system should
not span multiple DSO pools). However, this might not work if the DSO pool that handles the
endpoint has more load than the DSO pool that handles the relationship instances, thereby creating
a racing condition.
The racing condition can be handled in this way when the DSO filter for the relationship instance
is triggered, DSO checks whether any endpoint CI is pending for transfer in the pending queue of
the Distributed Pending form. If an endpoint is found in the pending queue, the transfer of the
relationship instance is deferred. The deferred relationship instances are then taken care of by an
AR escalation, which executes at regular intervals and checks all the deferred relationship
instances and performs the same check on endpoint too. During the endpoint check, if the AR
escalation finds that there are no pending endpoints, it triggers the DSO of that relationship
instance and clears the deferred flag. However, if there are pending endpoints, the DSO of the
relationship instance is handled when the next escalation is triggered.
Page 1090 of 4705
Home
Because each DSO pool represents another thread of activity, the computational overhead of DSO
scales roughly linearly as a function of the number of DSO pools. Usually, each DSO pool
consumes about 510% of the CPU space on a two-CPU Intel server or equivalent for both the AR
System server tier and the database tier. In a lightly used system, the impact on online users
should be small. In a system that heavily consumes CPU space, the impact on response time or
overall system throughput might be more substantial.
Page 1091 of 4705
Home
Using
Meant for the end users, this section contains information about how to use the BMC Remedy AR
System product.
Goal
Instructions
Using the AR System Object List and Approval Central to navigate through the BMC
Remedy AR System interface
Navigating the BMC Remedy AR

System interface
Working with searches
Creating and managing reports in BMC Remedy AR System
Reporting on BMC Remedy AR

System data
Working with approval requests
Approving requests
Working with BMC Remedy Flashboards
Navigating the BMC Remedy AR System

interface
The following topics provide information about how to navigate the BMC Remedy AR System
interface:
Copying field information to a new request

The AR System Object List displays a list of all forms and other object types for which users have
permissions. The BMC Remedy AR System administrator can make the object list available in a
browser, by entering the URL
Page 1092 of 4705
Home
http://<hostName>/arsys/forms (hostName is the name of the web server where BMC Remedy
Mid Tier is running).
For information about how to make the AR System Object List available in a browser, see Enabling
the AR System Object List.
If the AR System Object List is enabled, you can use it to access forms and applications in your
browser.
Object List example
Opening forms and applications from the Object List

To open a form, select the form name and click Open New or Open Search.
To open an application, select the application and click Open.
Note
The Show Hidden check box is visible to administrators only.
For more information about the AR System Object List, see:

Searching for forms or applications in the Object List
Choosing how forms and applications are displayed
Creating requests
Editing fields with rich text formatting
Modifying requests
Using the query builder widget
How the back button behaves
Opening a form in a new window
Keyboard shortcuts
Page 1093 of 4705
Home
Searching for forms or applications in the Object List

By default, the AR System Object List displays all available forms and applications for your mid tier.
You can restrict the display to specific forms, applications, and servers by using any of the following
methods:
To find objects in a specific server, enter all or part of the server name in the Server field
and click Search.
To find an application, enter all or part of the application name in the Application field, and
click Search.
To find a form, enter all or part of the form name in the Name field and click Search.
To restore the full list of forms and applications, clear the Server, Application, and Name
fields, and click Search.
To find an application or form by keyword, enter a word or a phrase from the name and click
Search. The search is conducted only on the Name column. Use the following criteria:
The name of a form or any sequence of letters contained in the form or application
name. For example, if the form name is Purchase Requisition and you enter requ, the
form is found.
Multiple, non-sequential words or search operators are not valid as keywords. You
can also arrange items in the list by name, server, or type by clicking the appropriate
column headings.
Choosing how forms and applications are displayed

All the forms and applications on all servers to which you have access are listed in the table by
default. To restrict the list to a specific server, enter the server name in the Server field, and click
Search.
You can arrange the list of forms and applications by Name, Server, or Type by clicking on the
appropriate column heading.
The Show Hidden check box is available only to administrators. When selected, it displays hidden
objects.
Creating requests
A request is a record related to a specific task. For example, a request could be a description of a
software problem or a purchase order from a customer.
When you create a request, you enter each piece of information about the request in a field. When
you save the request, it is added to the database.
If you have permissions, you can open requests and modify them. Only administrators and
sub-administrators can delete requests.
Page 1094 of 4705
Home
To create a new request

1. Open the form.
2. Click New Request.
3. Fill in the appropriate fields in the form.
4. Click Save.
Editing fields with rich text formatting

If a field has a rich-text-formatting (RTF) icon (
) next to it, you can format the text in the field.
RTF allows extensive formatting options, including font color and size. You can also create lists,
align text, and use special characters. For example, you might want to make text bold or italic, or
you might want to center the text.
Note
The UI features and the font attributes such as, color, size, and style might vary in edit
mode for RTF fields and Rich Text in Place fields, when you compare them with non-edit
mode fields.
Click the
button to open a dialog box that contains more RTF functions.
RTF dialog box

If RTF within the field is enabled, a reduced set of RTF functions appear when you click in the field.
RTF functions in a field
Here are some tips for working in the RTF dialog box:
Page 1095 of 4705
Home
Note
The RTF options provide a way for you to apply some basic styling of text and to include
images with their text. The options do not provide the level of functionality of a
desktop-based word processor such as Microsoft Word. Functionality will vary among
browsers. Apple Safari browsers support the fewest number of features.
To enable the buttons in the dialog box, type some text or select existing text. Then, you can
format the selected text.
To undo all of the text you entered and formatted in the RTF dialog box, click Cancel or
press the ESC key.
To view text or images in the RTF field without the scroll bars, set the Custom CSS display
property of the RTF field as RTFPanel. Scroll bars appear on the panel that holds the RTF
fields. If the content size exceeds the maximum limits as specified in the display property of
the RTF field, scroll bars appear on the RTF field itself. See Creating and managing fields in
the Developing the application interface section.
Note
In the RTF editor, when you select any of the following formatting options and start
typing, the formatting automatically gets applied (without selecting the text.):
Font Name
Font Size
Fore Color
Background Color
To continue with the same formatting on the next line, press SHIFT+ENTER.
When you select a font from the Font Name option, it is not displayed as the
selected item in the drop down immediately, but gets applied.
When you select a font from the Font Name option, though the font gets applied to
the text, the font name is not displayed as selected.
In an unordered (bulleted) list or an ordered (numbered) list, you cannot apply
formatting to a single point in the list. The formatting must be applied to the entire
list.
The ordered or unordered list does not support the indentation option.
The RTF editor supports only one level of indentation.
The following topics provide information about working with RTF fields:
Page 1096 of 4705
Home
RTF functions
RTF editor shortcut keys
Applying RTF character formats
Adding a table to a character field
Configuring an image for a character field
Inserting and removing URL links in the RTF fields
Creating or updating bookmarks
Using other formatting options
Using the spell checker in the RTF
Updating the spell checker dictionary
RTF functions
The RTF functions toolbar contains the following buttons:
Button
Function
See also
Font and Size
Select the font type and point size from the list.
Applying RTF
character formats
Bold, italic, and
Make the selected text bolded, italicized, or underlined.
Applying RTF
character formats
Select from the character options Subscript, Superscript, and Strike through.
Applying RTF
character formats
Text Color
Select the text color from the list.
Applying RTF
character formats
Text
Background
Color
Select the text background color from the list. The options are Red, Blue, Green, Black,
Yellow, and White.
Applying RTF
character formats
Remove
Formatting
Remove all formatting from the selected text.
Applying RTF
character formats
Show/Hide
Select to show or hide the hidden elements.Note: You can use this option only with
Hidden
formatted text. However, if you format the text using Subscript, Superscript, or Strike
Applying RTF
character formats
Elements
through, this option does not work.
Alignment
Set the paragraph so that it aligns evenly on the left, center, or right.
Applying RTF
character formats
Paragraph
Set the paragraph formatting style, including heading tags.
Applying RTF
underline
Subscript,
Superscript, and
Strike through
character formats
Indent
Increase or decrease the selected text's distance from the left margin.
Applying RTF
character formats
Bulleted and
Numbered list
Create a list formatted with bullets or numbers.
Applying RTF
character formats
Page 1097 of 4705
Home
Button
Function
See also
Create
hyperlink
Insert a link to a Bookmark or another website or URL.
Inserting and
removing URL links
in the RTF fields
Add bookmark
Insert a bookmark
Creating or
updating
bookmarks
Insert image
Insert an image into the RTF field.
Configuring an
image for a
character field
Insert Special
Items
Use special formatting features, such as a horizontal rule, expandable section, and
special characters.
Using other
formatting options
Spell Check
Runs the spell checker.
Using the spell

checker in the RTF
Undo and Redo
Removes the last 30 changes made in the RTF editor or reverses the undo action.
Cut, copy, and
Remove, copy, and paste selected text to and from the clipboard.
paste
Applying RTF
character formats
Note: These buttons work only in Microsoft Internet Explorer browsers. For any other
browser, use the shortcut keys listed in the "General RTF shortcuts" table.
Insert table
Insert a table into the RTF field.
Adding a table to a
character field.
Cell Properties
Edit the properties of a cell in a table.
Adding a table to a
character field
RTF editor shortcut keys

The following tables list the keyboard shortcuts that you can use with RTF:
General RTF shortcuts
Shortcut
Description
CTRL+A
Select all text
CTRL+SHIFT+W
Close inner dialog boxes
SHIFT+CTRL+[
Justify left
SHIFT+CTRL+]
Justify right
SHIFT+CTRL+\
Justify center
CTRL+V
Paste
CTRL+Z
Undo
CTRL+Y
Redo
RTF shortcuts that work after text is selected
Page 1098 of 4705
Home
Shortcut
Description
SHIFT+CTRL+Up arrow
Increase font size
SHIFT+CTRL+Down arrow
Decrease font size
SHIFT+CTRL+L
Create a link
SHIFT+CTRL+A
Insert a bookmark
SHIFT+CTRL+B
Bold
SHIFT+CTRL+I
Italic
SHIFT+CTRL+U
Underline
CTRL+C
Copy
CTRL+X
Cut
Applying RTF character formats

You can apply rich-text formatting to a character field.
1. Click the RTF icon (
) next to the character field, and select the text to format.
2. Apply the appropriate formatting.

3. To clear the formatting you applied, click Cancel or press the ESC key.
4. Click Save.
Note
You can modify RTF properties for the character fields at run time by using a
workflow. For more information, see Change Field action.
Adding a table to a character field

Use the Table icon (
) to insert a table in an RTF field or to modify the properties of a
selected table. Table properties include:

Size of the table
Number of rows and columns
Cell spacing and padding
Table and cell borders
Table caption
Use the Cell Properties icon (

include:
) to edit the properties of a cell in a table. Cell properties
Page 1099 of 4705
Home
Cell border
Horizontal and vertical alignment
Cell background color
When adding a table, remember these guidelines:
You can change the format of one cell at a time (not multiple cells).
After you create a table, you cannot insert or delete rows or columns, so be sure to include
enough rows and columns when you create the initial table.
If you select a table that is larger than the RTF field, the bounding box anchors will appear
outside of the field. This is an HTML limitation.
If you change the size of a table or image by dragging the bounding box, the OK button in
the RTF editor (or the Save button when an RTF field is modified) is not enabled. To enable
it, modify the text in the RTF field. Then, click OK (or save the form).
Configuring an image for a character field

If an image is accessible through a URL, you can add it to a character field, if the field includes an
RTF icon (
).
Adding an image to a character field

1. Click the RTF icon (
2. Click the image button (
) next to the character field.

) to open the Image Options pop-up box.
3. Complete the following fields:

Field
Description
Image URL
URL to the image. If a browse button (...) appears, you can select an image file from your local computer.
See Using the browse button to add an image to a character field .
Note: Do not enter a local file path, such as C:\Documents and Settings\user1\My Documents\
companylogo.jpg. If you do enter a local path, the link will break on the computer.
Size
The length and width of the image in pixels.
Text Flow
The alignment of the image with the text.
Padding
Amount of space (in pixels) around the image.
Border
The type of border around the image. You can select the width, line type, and color.
Description
The text that appears when the mouse hovers over the image.
Link URL
The URL that is opened when you click the image in the character field.
Open in a
new
window
If this check box is selected (the default), when a user clicks the image, a new browser or browser tab
opens the URL. If the check box is not selected, the URL's web page opens on the same browser.
4. Click OK.
Page 1100 of 4705
Home
Using the browse button to add an image to a character field

1. In the Image Options pop-up box, click the browse button (...) if it is available.
2. In the Add Attachment dialog box, click Browse and search for an image to add.
3. Click OK.
Deleting an image from a character field

1. Select the image in the RTF field, and delete it.
2. Move the cursor out of the RTF field.
3. Save the form.

You can insert links to the available bookmarks in the same RTF field or different RTF fields on a
single form and also link to the external websites.
Note
To link to a location in the same RTF field or link to a different RTF field on the same form,
you must first create a bookmark by performing the steps provided in the Creating or
updating bookmarks section.
To add a link in the RTF field

1. Click the RTF icon next to the character field to open the RTF Editor.
2. Select the text to add a link to the bookmark.
Note
If you do not select the text, the HTML Link option will not be enabled to perform
Step 3.
3. Click the HTML Link option (
) to create a link to the bookmark on the RTF field or link
to an external URL. This opens the Link Options dialog box.

4. Perform one of the following to link to a bookmark:
Note
Page 1101 of 4705
Home
If you enter a link or a bookmark that does not exists, you see the following warning
message or note. Note: This link points to a missing bookmark and may do
nothing.
a. Select a bookmark from the list below the Link URLfield to link to a specific bookmark
.
Note
The list displays all the names of all bookmarks present on the form. You
can link to a bookmark present on the same RTF field or link to a bookmark
on an another RTF field on the same form. If the form does not contain any
bookmarks created, the list is disabled for selection and displays No
bookmarks....
b. Enter a URL in the Link URL field.

You can use any of the following formats to specify an external link:
www.bmc.com
http://www.bmc.com
<a href ="http://www.bmc.com">
Note
To open the Hypertext Transfer Protocol (HTTP) links, you can
specify the URL without using the http:// string. However,
to open a Hypertext Transfer Protocol Secure (https) links, you
must specify the complete address. For example, https://
www.bmc.com.
If you specify a non-existing page link, the Server not
found error page appears.
c. If you have defined a workflow mapped to the RTF field to open an external link or a
dynamic link, the ellipses option (
) appears next to the Link URL field. Click this
option to trigger the workflow, which generates an external URL or dynamic URL in
the Link URL field. For more details, see Generating a URL in an RTF field using a
workflow.
5. (Optional) Select the Open in a new windowoption to open an external URL on a new
window.
Page 1102 of 4705
5.
Home
Note
The Open in a new window option is available for use only for external and
dynamic links. If you have selected a bookmark from the list in Step 4, this option is
disabled.
6. Enter a description for the URL in the Description field. The updated text appears when you
hover the mouse on the link in the display mode. If you do not specify a description, BMC
Remedy Mid Tier displays undefined as the tool tip.
7. Close the Link Options dialog box.
8. Click OK.
When you view the RTF field in display mode, the linked text appears in Blue with the underline
formatting. For the bookmark text with an external URL link, the hand cursor appears when you
move the mouse pointer on the text.
Note
RTF fields generate an href tag when the links are created from the RTF Editor. Due to
security reasons, Firefox does not allow opening local or network links in the href tag. For
more information, see http://kb.mozillazine.org/Firefox_:_Issues_:_
Links_to_Local_Pages_Don%27t_Work.
To allow Firefox to open links in the href tag, add the following settings and their values in
the about:config page of Firefox and restart the browser.
Add a capability.policy.policynames setting and specify
localfilelinks as its value.
Add a capability.policy.localfilelinks.sites and specify http://<
midtier url including port number> as its value.
Add a capability.policy.localfilelinks.checkloaduri.enabled and
specify allAccess as its value.
Ensure UNC pattern paths are used for creating links to the network paths (e.g. file:
/////servername/share/file.ext)
For more information about the About:config page, see http://kb.mozillazine.org/About:
config.
To delete an existing link

This highlights all bookmarks in the RTF field.
2. Place the cursor on the bookmark within the highlighted area.
3.
Page 1103 of 4705
Home
3. Double-click the text or click
to open the Link Options dialog box.
4. Click Remove link from text.

6. Close the RTF Editor.
7. Save the form.
Creating or updating bookmarks

The bookmark is an identifier placed in a document so that it can be referenced through a URL
from a different location. Adding bookmark eliminates the need to scroll through the document to
locate the required information or type a URL address to navigate to a specific page.
You can add bookmarks to a character field, if the field has a rich-text-formatting (RTF) icon (
next to it.
Adding a bookmark includes the following steps:
1. Creating a bookmark
2. Inserting and removing URL links in the RTF fields
Creating a bookmark
To link a specific text in a RTF field or link to a different RTF field on the same form, you must
create a bookmark to mark the location or destination. After you create a bookmark, you can link
the bookmark from any RTF field on the form using the URL design.
Note
If you want a link to an external URL, you do not have to create a bookmark. Perform the
steps provided in the Inserting and removing URL links in the RTF fields section.
To create a bookmark
2. Select the text to which you want to create a bookmark.
Note
Do not select an image or a table to create a bookmark.
3. In the RTF editor, click the Insert or Change Bookmark option (
).
4. In the Bookmarks Options dialog box, enter the name of the bookmark, and close the
dialog box.
Page 1104 of 4705
4.
Home
Note
If you enter a duplicate name that already exists on the form, you see the following
warning message or note on the highlighted bookmark text. Note: A Bookmark
with the same name already exists.
5. The bookmark text is highlighted with a yellow backgroun d and blue-dashed border in the
RTF Editor. In display mode, the bookmark text appears as a regular text. However, for
bookmark text with the external URL links the hand cursor appears when you move the
mouse pointer on the text.
Note
You can use alpha-numeric characters in the bookmarks. As a best practice, do not
use special characters such as hyphen, ampersand ( &), angular brackets (< and >)
.

7. Save the form.
Modifying an existing bookmark

Perform the following steps to modify an existing bookmark.
To modify an existing bookmark

This displays highlighted text for all bookmarks in the RTF field.
2. Place the cursor on the bookmark that you want to modify within the highlighted area.
Note
This enables the Insert or Change Bookmark option. If you move the cursor away
from the bookmark or do not select any text in the RTF Editor, the button will be
disabled.
3. Click
to open the Bookmarks Options dialog box.
4. Rename the bookmark or make the required changes and close the dialog box.
6. Save the form.
Page 1105 of 4705
Home
Deleting a bookmark
Perform the following steps to delete a bookmark.
To delete an existing bookmark

This highlights all bookmarks in the RTF field.
2. Select the bookmark that you want to delete.
3. Double-click the bookmark or click
to open the Bookmarks Options dialog box.
4. Click Remove link from text.

5. Close the Bookmarks Options dialog box.
7. Save the form.
Related topics
Using other formatting options

You can use other formatting options that allow you to enhance the RTF field by presenting
information in a variety of structured formats. In addition to the features of the RTF field, you can
use the following formats:
Inserting a horizontal line

You can add a horizontal line to help differentiate sections in your RTF field. This type of formatting
can make the information more readable.
1. Click in the RTF field, where you want to insert the horizontal line.
2. From the RTF functions toolbar, click Insert Special Items, and select Line Rule - HR.
3. Click Save.
Inserting an expandable section

You can add an expandable section to provide additional information when users expand the
section header. Expandable sections contain an information header with hidden detail information.
The reader can expand the hidden content by clicking the section header. This type of formatting is
useful when you want to provide an overview of information for simplicity, but also need the
associated details.
Note
You can insert an expandable section within another.
1. Click in RTF field, where you want to insert the expandable section.
2.
Page 1106 of 4705
Home
2. From the RTF functions toolbar, click Insert Special Items, and select Expand Section.
3. Replace the bolded Information Header with text describing the section.
4. Replace the expanded text with text to display when the user expands the section.
5. Click Save.
Note
Even if the RTF field is disabled or read-only, you can still expand or contract the
expandable sections.
Inserting special characters

You can insert special characters that cannot be typed in from a keyboard, such as the trademark
symbol and common fractions. Special characters are those you cannot enter from a standard
keyboard.
1. Click in the RTF field, where you want to insert the special character.
2. From the RTF functions toolbar, click Insert Special Items, and select the character from
the list.
3. Click Save.
Using the spell checker in the RTF

To check for spelling errors in the RTF field, launch the spell checker from within the RTF field.
1. From the RTF functions toolbar, click Spell Check.
The spell checker highlights any misspelled words and provides an alternative spelling for
the word in the Replace with box. It also provides additional suggestions in the Suggestions
box.
Spell checker in RTF
2. Correct misspelled words by selecting the new word from the Suggestions box. Other
options in the spell checker window are as follows:
Change Once: Click to change the selected occurrence of the word with the spell
checker suggestion.
Change All: Click to change all the occurrences of the word with the spell checker
suggestion.
Ignore Once: Click to ignore the spell checker suggestions.
Ignore All: Click to ignore every occurrence of the word.
Page 1107 of 4705
Home
One-Click Change Once: Select to replace the first occurrence of the misspelled
word.
Note
Using this check box eliminates the need to use the Change Once button.
One-Click Change All: Select to replace all occurrences of the misspelled word.
Note
Using this check box eliminates the need to use the Change All button.
3. When the spell check is complete, the spell checker window closes automatically.
Updating the spell checker dictionary

When you launch the spell checker, BMC Remedy Mid Tier searches the dictionary index. If a word
in the RTF is not found in the dictionary, BMC Remedy Mid Tier considers the word to be
misspelled.
The dictionary and index use a group of files that are stored in the <midTierInstallationDir>/
SpellChecker directory.
The SpellChecker directory contains the following folders:
Dictionary - Location of all the text files that are a part of the spell check dictionary.
Default - Location of the default files when there is no support for a specified locale.
Locale folders - A set of folders that represent specific locales, such as en_US,
en_UK. Each folder contains the dictionary text files for that locale. If a folder with a
specific locale name does not exist, then the default folder is used.
Index - Location of all the index files. These files are generated and updated by BMC
Remedy Mid Tier based on the associated dictionary text files.
Default - Location of the default files when there is no support for a specified locale.
Locale folders - A set of folders that represent specific locales, such as en_US,
en_UK. Each folder contains the index files for that locale. If a folder with a specific
locale name does not exist, then the default folder is used.
Warning
BMC Remedy Mid Tier uses the index files when you launch the spell
checker. BMC recommends that you do not modify these files.
Page 1108 of 4705
Home
Adding dictionary files

System administrators can place their own text file(s) in the <midTierInstallationDir>/
SpellChecker/Dictionary folder. The words in the text file(s) are extracted and processed into the
spell check index for use by the spell checker.
For example, the newWords.txt file contains a list of new words for the dictionary. To add these
words to the dictionary, copy the newWords.txt file into the appropriate locale folder within the
dictionary folder. If the words in newWords.txt are for the UK locale, then copy the file in the
en_UK folder, or the default folder.
Modifying an existing dictionary file

As a system administrator, you can also modify the existing text files without restarting BMC
Remedy Mid Tier. To update any of the existing files, open the file in any text editor and make the
necessary changes. After you modify the dictionary files, BMC Remedy Mid Tier updates the index
automatically.
Modifying requests
If you have permissions, you can modify requests.
You can modify individual requests or a group of requests. If you change several requests at once,
fill in only the fields that you want updated on every request that you have selected.
The following topics provide information about how to modify requests:
Modifying a single request
Modifying several requests at once
Changes made to the Status field are recorded in the request's status history. You can view a list
of these changes in the Status History window (select View > Status History).
The dialog box displays the default name of the field ( Status), which can be changed by the
administrator.
Modifying a single request

1. Open the form containing the request that you want to change.
2. If the form is not in Search mode, click New Search.
3. Search for the request.
For more information, see Running searches.
4. The Results pane lists the requests that match the search criteria. The first request appears
in the Details pane, which is in Modify mode. Click the request that you want to change so
that it appears in the Details pane.
5. Make the necessary modifications to the fields in the form.
6.
Page 1109 of 4705
Home
6. Click Save.
Modifying several requests at once

1. Open the form containing the request that you want to change.
2. If the form is not in Search mode, click New Search.
3. Search for the requests.
The Results pane lists the requests that match the search criteria.
4. Select the requests that you want to change.
Use the CTRL or SHIFT key to select more than one request.
5. Click Modify all.
The Details pane changes to Modify All mode, and a blank form is displayed.
6. Fill in the fields you want updated for every request.
The data you enter in the fields will be applied to all the selected requests; therefore, fill in
only the fields that you want updated on every request you have selected.
7. Click Save.
A dialog box appears, listing the number of requests that will be modified and prompting you
to confirm your modifications.
Warning
You cannot undo this action if you select Yes.
8. Click Yes to confirm.
Using the query builder widget

The query builder widget provides an intuitive user interface which enables you to build simple
queries.
The query builder widget allows you to use words instead of symbols to build expressions in a
non-technical manner. It also presents only the appropriate data types and operators from which
you can select. For example, instead of saying "Create Date < 01/01/2011", you can enter "Create
Date less than 01/01/2011."
Query builder widget example
Page 1110 of 4705
Home
Note
A query builder widget appears in a form only if it is loaded into the form by the BMC
Remedy AR System Server Administrator.
To build a query
1. Open a form in which you want to perform a search.
The query builder widget appears when the form opens. If it does not, click the appropriate
button (for example, for advanced search) to open a query builder widget.
2. Build a query to add to the table:
a. In the left box of the query builder widget, select a field from the list of fields which can
be queried upon. This list of fields is provided for this form by the query builder widget
.
Note
All field types are available for the query builder widget except for currency
and status history.
b. In the center box, enter an operator using the list, which provides operators that are
meaningful for the selected field.
The following are the numeric and enumerated data type operators:
Is equal to - (for numeric and enumerated data types) Selects records in which
the value in the chosen field matches exactly the value entered in the query.
Is not equal to - Selects records in which the value in the chosen field does
not match the value entered in the query.
Is greater than - Selects records in which the value in the chosen field is
greater than the value entered in the query.
Is greater than or equal to - Selects records in which the value in the chosen
field is greater than or matches exactly the value entered in the query.
Is less than - Selects records in which the value in the chosen field is less
than the value entered in the query.
Page 1111 of 4705
Home
Is less than or equal to - Selects records in which the value in the chosen
field is less than or matches exactly the value entered in the query.
Is empty - Selects records in which the chosen field is empty
Is not empty - Selects records in which the chosen field contains some data
The following are the date/time data type operators:
On - See Is equal to.
Not on - See Is not equal to.
Before - See Is less than.
After - See Is greater than.
On or Before - See Is less than or equal to.
On or After - See Is greater than or equal to.
Is empty
Is not empty
The following are all other data type operators:
Contains - Finds entries that contain xx.
Starts with - Matches all entries that begin with xx.
Ends with - Matches all entries that end with xx.
c. In the right box, type the value for which to search.
For example, to find all current users with Create Date values that are less than 01/01
/2011, you could use the query builder widget to construct the following queries:
3. Refresh the table.

The table is refreshed based on the query created in the query builder widget.
4. Click the plus sign to the right of fields to add a new set of input fields, then repeat steps 2
through 3 for each query you want to add to the table.
In the Match field, select All or Any to display the results that match all queries or any query.
How the back button behaves

The Back button might not behave as you expect. If you view a form in a browser (in either New or
Search mode), go to another web page, and then click the Back button, the browser will display the
form in Search mode, and the form will be empty. Field properties, selections, and other values are
not saved.
Page 1112 of 4705
Home
Opening a form in a new window

The BMC Remedy 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 Shift+Click (
press the Shift key on the keyboard and click the left mouse button) on an entry point present on
the Application List field, the form opens on a new window.
Note
Depending on the browser, the form opens on a new window or a new tab.
Keyboard shortcuts
This topic provides information about the following BMC Remedy AR System keyboard shortcut
keys:
Panel field shortcut keys
Character field menu shortcut keys
Form action shortcut keys
The term focus refers to keyboard focus, not to virtual cursor positions defined by certain assistive
technologies.

Key
Description
LEFT ARROW
If the focus is on a tab selector (an anchor link), sets focus to the next or previous tab selector without
RIGHT ARROW
displaying it. Press ENTER to display the selector.
ENTER
If the focus is on a tab selector, displays the page.

In the Section 508 accessibility mode, the following shortcut keys do not work. To access a
character menu in 508 mode, you must be in Virtual PC Cursor (Non-Forms) mode.
For more information, see Making your application accessible - Section 508 compatibility .
Key
Description
UP or DOWN
ARROW
Moves focus through the menu items. Press ENTER to fill the field with the menu selection.
Page 1113 of 4705
Home
Key
Description
RIGHT ARROW
If the selected item is a submenu, opens and sets focus to the submenu.
LEFT ARROW
Dismisses the submenu and sets focus to the upper level menu. If focus is at the top level, no action
occurs.

These keys work only when the corresponding form action button is visible and enabled.
Key
Description
CTRL+ALT+F2
Switches to New Request mode
CTRL+ALT+F3
Switches to New Search mode.
CTRL+ALT+ENTER
In New or Modify mode, saves the changes. In Search mode, performs the search.
CTRL+ALT+L
Clears all field values.
CTRL+ALT+U
Sets default field values.
CTRL+ALT+H
Shows status history values.
CTRL+ALT+S
Sets focus to the Advanced Search Bar input field.
CTRL+ALT+C
Copies field information to a New Request.
Note
In some browsers, the CTRL+ALT+F2 and CTRL+ALT+F3 shortcuts do not work.
Alternatively, click the New Request and New Search buttons on the toolbar to switch
modes. This is keyboard accessible because you can tab through the toolbar.

This section describes the different ways to open Approval Central.
To open Approval Central from the BMC Remedy AR System home page
If you have configured BMC Remedy Approval Server, the BMC Remedy AR System home page
form will contain an Approval Central link. Click this link to open Approval Central.
Page 1114 of 4705
Home
To open Approval Central in a browser

1. Launch your browser and enter a URL as follows: http://<hostName>/arsys/forms/<
serverName>/Approval Central
where hostName is the name of the web server where BMC Remedy Mid Tier is running,
and serverName is the name of the BMC Remedy AR System server where BMC Remedy
Approval Server is running.
Ask your BMC Remedy AR System administrator for the exact URL.
2. In the BMC Remedy Mid Tier login window, enter your user name and password, along with
an authentication string if necessary, and click Log In.
You can use a similar procedure to access any other BMC Remedy Approval Server forms,
such as the AP:Administration form.
Copying field information to a new request

You can now copy information from the fields in an existing form to a form in New request mode in
the mid tier application. The new request contains all the data from the copied request, except diary
fields and attachments. If you want the same attachments, you must save each attachment to a file
and then attach each to the new request.
Also, if you wanted to create a new request but filled a form in Search mode, you can copy
information from the fields of the form in Search mode to a form in New request mode.
To copy information from an existing request to a new request

1. Open an existing request.
2. Press Ctrl+Alt+C.
The window changes to New mode, and fields are populated as in the original request.
3. Add or modify information in the fields for the new request.
Note
You cannot save a request until you add or modify data in the request.
4. Click Save.
To copy information from search mode to a new request

1. Open a new form in Search mode.
2. Instead of clicking New request, add information in the fields.
3. Press Ctrl+Alt+C.
The window changes to New mode, and fields are populated as in the Search mode.
4.
Page 1115 of 4705
Home
4. Add or modify information in the fields for the new request.

5. Click Save.

The following topics provide information about how to save and run searches on the web:
Finding a request by example
Running a saved, recent, or defined search
Loading search criteria without execution
Saving searches
Managing saved searches
Running searches
Types of searches
Using the advanced search bar
Finding a request by example

Finding a request by example enables you to enter information directly into the form to use as a
search.
1. In Search mode, open the form for which you want to find requests.
2. In the appropriate fields, specify the search criteria that the requests must match.
You cannot specify search criteria for attachment fields. You can enter values for more than
one field, creating a logical AND for the search criteria. The more fields that you fill in, the
more specific your search becomes.
3. Click Search.
You can modify the requests, or you can run a report. For more information, see Running
and saving searches.
The following topics provide information about how to find a request by example:
Search styles in character fields
Overriding the predefined search style
Using relational operators and wildcard symbols in a search
Using wildcard symbols as explicit characters in a form
Search styles in character fields

Each character field on a form is assigned a specific search style that determines how it finds
matching requests. Your administrator will set these for you. Three search styles are available:
Equal Searches for exactly what you entered in the field.
For example, if you enter Bob Smith in the Created By field, you find all requests created
by Bob Smith, but none created by Bob Smithe.
Page 1116 of 4705
Home
Leading Searches for the entered sequence of characters only at the beginning of the
field, ignoring any subsequent characters. The search will return every request with this field
that contains the first characters exactly as you entered plus any following characters.
For example, if you enter Bob in the Created By field, you find all requests created by Bob
Smith, as well as those created by Bob Smithe and Bobby Jones. You will not find any
created by Jill Bobbington. (The characters Bob in the name Jill Bobbington are not leading
characters.)
Anywhere Searches for the entered sequence of characters anywhere in the field.
For example, if you enter Bob in the Created By field, you find all requests created by Bob
Smith, as well as those created by Bob Smithe, Bobby Jones, and Jill Bobbington.
Note
Equal and Leading searches are faster than Anywhere searches because Anywhere
searches compare each character in the field while Equal and Leading searches do not.
Overriding the predefined search style

To override the default search style for a character field, enter exactly what you are searching for in
the field, and include a relational operator or wildcard character.
For example, you can use an equal sign (=) to search for an exact match even if the field has a
search style of Anywhere. Thus, if you enter =Bob Jones in the Created By field of a form, the
search will find all the requests created by Bob Jones. The search will not find requests created by
Bob Joneson.
You can also use the advanced search bar to override a field's search style. For example, to
override the Created By field in the previous example with a Leading search, you would specify the
following criteria in the advanced search bar:
'Created By' LIKE "Bob Jones%"
Using relational operators and wildcard symbols in a search

You can use the relational operators or wildcard symbols in a form and in the advanced search bar.
Using relational operators in a search

Relational operators are useful in non-text fields (such as date and time fields) when you want to
search for a value within a numerical range.
You can use the following relational operators as leading characters in fields in a form and in the
advanced search bar.
Relational operators
Page 1117 of 4705
Home
Operator
Action
<
Matches contents that are less than the value.
>
Matches contents that are greater than the value.
<=
Matches contents that are less than or equal to the value.
>=
Matches contents that are greater than or equal to the value.
Matches contents that are exactly equal to the value.
!=
Matches contents that are not equal to the value.
For example, to search for all requests created after a certain date, use the greater than (>)
relational operator and specify a date and time format. For example, > "July 5, 2008" in the Create
Date field finds all requests created after July 5, 2008. (Leaving out the time defaults the search
criteria to 0:00:00, the start of the day.)
Using wildcard symbols in a search

When you specify search criteria to find requests, you can use the following wildcard symbols
anywhere in a form to indicate one or more characters.
Note
Square brackets and the symbols associated with them do not work with Oracle
databases.
Wildcard symbols for searches

Wildcard
Function
% (Percent)
Matches any string of 0 or more characters. For example: J%son matches Jackson, Johnson, Jason, and
Json.
_ (Underscore)
Matches any single character. For example: B_b matches Bab, Bob, and Bub.
- (Hyphen)
Indicates a range. Always use within square brackets ([ ]).
[ ] (Square
brackets)
Matches any single character within a specified range or set. For example, [a-f] matches the range of
[^] (Square
brackets with
Matches any single character not within a specified range or set. For example, [â-f] matches all characters
characters a through f, and [abcf] matches the set of characters a, b, c, or f.
except the range a through f, and [âbcf] matches all characters except a, b, c, or f.
caret)
Use the percent symbol (%) to include leading or trailing characters in your search. For example, to
find all requests submitted by Jill Bobbington, Bobby Fenton, and Bob Comptonson with an
Anywhere search, enter *Bob%ton* in the Submitter field. The search returns all requests for
which the Submitter field contains the strings "Bob" and "ton" in that order with any number of
characters leading, trailing, and in between.
Page 1118 of 4705
Home
When used in a form, the percent sign (%), underscore (_), and open bracket ([) symbols always
function as wildcard symbols except as follows, where they function as explicit characters:
When you specify a relational operator (for example, > or =).
When the field's default search style is Equal and you do not use a leading or trailing percent
sign (%).
Note
You can override a field's search style by using a leading percent sign. For example, if the
field's search style is Equal and you enter %Rob into the Submitter field, your search
finds Robert Smith and Jim Robertson (not only equal matches to %Rob). However, if you
use a leading percent sign, you lose any faster search times that would result from using
the Equal or Leading search styles. See Search styles in character fields.
Using wildcard symbols as explicit characters in a form

To search for the actual characters that serve as wildcard symbols, you must force the system to
interpret these wildcard characters as explicit characters. For example, you might need to search
for all instances of the percent sign instead of using the percent sign as a wildcard symbol.
To search for the percent sign (%), underscore (_), or open bracket ([) as an explicit character,
enclose the character in square brackets. For example, if you enter the percent sign in square
brackets ([%]), the system searches for instances of the percent sign instead of using it as a
wildcard character.
The close bracket (]) functions as a wildcard only when it is accompanied by an open bracket ([).
The hyphen (-) functions as a wildcard character only when preceded by an open bracket ([) or an
open bracket with a caret ([^).
Running a saved, recent, or defined search

1. From the toolbar, select Searches > Run My Searches, Run Recent, or Run Defined.
Searches menu
2.
Page 1119 of 4705
Home
2. From the list of searches, select a search to run.

The system executes the search and displays a results list.
Search results
Loading search criteria without execution

You can load search criteria from saved, recent, or defined searches into a form without executing
the search. You can then modify the search criteria, or execute the search as it is.
1. Open a form in Search mode.
2. From the toolbar, select Searches > Load My Searches, Load Recent, or Load Defined.
3. From the list of searches, select the search you want to load into the form.
The search criteria is loaded into the form. You can execute the search by choosing Search
from the toolbar, or you can modify the search criteria.
Saving searches
The following procedure details how to save and run searches from a form that you created viewed
in a browser.
Note
You must execute a search before you can save it.
1. Run a search. (See Running searches.)

2. From the toolbar, select Searches > Save Search.
The Save or Redefine Search dialog box appears.
3. In the Search Name field, enter a name for the search, or select one from the list of existing
saved searches.
This is the name that will appear in the saved search list. If the name you enter already
exists, the search criteria under the existing name will be overwritten.
4. Click OK.
The new and refined search will now be available in the list of saved searches.
Page 1120 of 4705
Home
Managing saved searches

This section describes how to enable, disable, or delete existing saved searches. Disabling a
search removes it from the list of searches, but keeps the search data.
Enabling or disabling a search

1. From the toolbar, select Searches > Manage My Searches.
Manage Search dialog box
2. In the Manage Search dialog box, select the search you want to enable or disable, and click
the Enable or Disable button.
If a search is not yet selected in the Manage Search dialog box, the default button label of
Disable is displayed.
The state of the search changes to either Enabled or Disabled, depending on your action. If
the search is disabled, it no longer appears in the search menu on the toolbar, but the
search data is still stored in the AR System Searches Preference form.
3. Click Save to save your changes.
Deleting a search
1. Select the search you want to delete.
2. Click Delete.
3. Click Save.
The search is deleted from the list in the Manage Searches dialog box, from the search
menu, and from the AR System Searches Preference form. To restore a deleted search, you
must recreate and save it.
Running searches
You can save searches in a browser and run them at any time by selecting Searches from a toolbar
menu in a form. You can also make recent searches and defined searches available in a browser.
You can load each type of search criteria into a form, and update the search criteria before you
execute a search. You can run all searches across multiple sessions.
Methods for running searches

You can run a search using any combination of the following methods:
Page 1121 of 4705
Home
Finding a request by example The easiest way to specify search criteria is to fill in fields
and select choices and option buttons to match the requests that you want to find. You can
specify values for more than one field. The more fields that you fill in, the more specific your
search becomes. The system searches for requests that meet all the criteria and displays
them in the Results pane.
For more information, see Finding a request by example.
Advanced search bar You can use the advanced search bar to define a more complex
set of search criteria. For example, you can search for all requests with two different values
in the same field. You can use the search bar together with fields in a form to specify search
criteria.
The advanced search bar appears at the bottom of the browser window when you click the
Advanced Search button on the toolbar.
For more information, see Using the advanced search bar.
Parameters Enter a parameter enclosed in dollar signs ($) in the field. For example, so
that you can specify the submitter each time that you run the saved report, enter the prompt
text $Enter User Name$ instead of a specific name in the Submitter field. When you click
Search, you are prompted to enter a sample value for this parameter. A parameterized
search works best when it is saved. Saving the search enables you to enter different values
each time a search is performed.
To run a search
1. Open a form in Search mode.
2. Enter the search criteria in the form fields, in the advanced search bar, or a combination of
both.
3. Click Search.
Types of searches
The following types of searches are available on the Web:
Saved searches - Searches that you can create and save for a form.
Recent searches - Searches that you have executed recently.
Defined searches - Searches defined by your administrator.
Using the advanced search bar

You can use the advanced search bar to define a more complex set of criteria than you can specify
by using only fields in a form. For example, you can search for all requests with two different values
in the same field. Thus, you could search for all requests that have a status of Fixed or Closed.
When you specify search criteria in the advanced search bar, you can use the same operators as in
the form, and several more. See Using relational operators in the advanced search bar .
Page 1122 of 4705
Home
The easiest way to build your search in the advanced search bar is to select the fields, status
history fields, keywords, values, currency codes, currency field sub-values, and selection field
values directly from the Fields menu to the right of the bar. When you select items directly from this
menu, the correct syntax is automatically entered.
You can also type the information directly into the advanced search bar. If you select this option,
observe the conventions listed in the following sections.
For more information, see Examples of advanced search bar statements.
Note
If you enter search criteria in the advanced search bar and then hide the advanced search
bar, the criteria is still used to find matching requests. If you have entered criteria in the
advanced search bar and then decide not to use it, you must clear the advanced search
bar before you hide it.
Showing or hiding the advanced search bar

To show or hide the advanced search bar, click the Advanced Search button in a search window.
When visible, it appears at the bottom of the browser window.
Building an advanced search

1. Click the Advanced Search button in a search window.
2. Define a search statement in the Advanced Search bar.
If you use relational operators, observe the appropriate operator precedence. (See Using
relational operators in a search.)
3. Click Search.
The following topics provide information about how to work with the advanced search bar:
Using fields in the advanced search bar
Using relational operators in the advanced search bar
Using wildcard symbols in the advanced search bar
Examples of advanced search bar statements
Using fields in the advanced search bar

Enclose field labels in single quotation marks. For example:
'Short Description'
Page 1123 of 4705
Home
If a field name contains a single quotation mark (such as an apostrophe), add another single
quotation mark next to it. For example, if the field is named Submitter's Phone Number, enter it as '
Submitter''s Phone Number'.
To search on a field that does not have a label, see your administrator for the field ID. Use this ID
instead of the name enclosed in single quotation marks.
Note
Instead of entering the field label and the quotation marks into the advanced search bar,
click the field's label in the form, or select the field from the Field List dialog box. The field
name is automatically added, with the correct syntax, to the search statement.
See the following sections for more information about using fields in the advanced search bar:
Using status history fields
Using currency fields
Using keywords in the advanced search bar
Using values in the advanced search bar
Using selection field values
Using currency field values
Using status history fields

Status history fields must have all of the following information enclosed within single quotation
marks:
The name or ID of the status history field followed by a period.
The name or index of the status value that you want to match followed by a period.
The keyword USER (for the user who changed the request to that status) or TIME (for the
time last changed to that status).
The following example uses names:
'Status History.Fixed.TIME' < "07/01/08"
Using currency fields

For currency fields, you must enclose one of the following items in single quotation marks:
The name or ID of the currency field. For example:
'Currency Field' = $NULL$
The name of the currency field, followed by a period, followed by a specific portion of the
currency field's value, such as the date or a functional currency value. For example:
'Currency Field.VALUE' < 5000
Page 1124 of 4705
Home
Using keywords in the advanced search bar

You can use keywords anywhere that you can enter character values.
You can use the $NULL$ keyword to search for requests that have no value in a field. For example
, to search for requests that have not been assigned (requests with no value in the Assigned to field
), enter 'Assigned to' = $NULL$.
The most commonly used keywords are: $DATE$, $NULL$, $TIME$, $TIMESTAMP$, $USER$,
and $WEEKDAY$.
Note
Keywords are case-sensitive. Use only UPPERCASE, as shown in the following table.
Keywords
Keyword
Substituted value
$APPLICATION$
The application name if the application is running; $NULL$ when no application is running.
$BROWSER$
The browser (Internet Explorer or Netscape) being used in the current session. If the browser is
anything other than Internet Explorer or Netscape, Netscape is returned.
$CLIENT-TYPE$
The client type of the API program. AR System administrators use this keyword.
$CURRENTWINID$
The window ID that uniquely identifies the current window in the client environment. AR System
administrators use this keyword.
$DATABASE$
The name of the database on which the current form's data is stored.
$DATE$
In a character field, the current date is displayed. In a date/time field, the time defaults to midnight (00:
00:00).
$DEFAULT$
The default value for the associated field (used only when assigning a value to a field).
$ERRNO$
When an error is encountered, the number of the error that just occurred.
$ERRMSG$
The message for the error that just occurred.
$ERRAPPENDMSG$
The appended message, if any, for the error that just occurred.
$EVENTSRCWINID$
The window ID that uniquely identifies the event source window in the client environment. AR System
$EVENTDATA$
The value that identifies the data of the event. AR System administrators use this keyword.
$EVENTTYPE$
The value that identifies the type of the event. AR System administrators use this keyword.
$FIELDHELP$
The field help text for the currently selected field.
$FIELDID$
The ID of the field that is currently selected. If the field is not selected, it returns NULL.
$FIELDLABEL$
The label of the field that is currently selected, If the field is not selected, it returns NULL.
$FIELDNAME$
The name of the field that is currently selected. If the field is not selected, it returns NULL.
Page 1125 of 4705
Home
$GROUPIDS$
The group IDs of which the current user is a member. If there are no groups, the keyword returns a
value of NULL.
$GROUPS$
The groups to which the current user belongs.
$GUIDE$
The guide name if the guide is running; NULL if the guide is not running.
$GUIDETEXT$
Help text that provides instructions when a guide is running.
$HARDWARE$
The hardware platform on which the current process is running.
$HOMEURL$
The URL of the current page. This option is only valid on web pages. AR System administrators use
this keyword.
Indicates whether you are in a bulk transaction. This keyword is not supported and is reserved for
INBULKTRANSACTION
$
future use.
$LASTCOUNT$
The number of matches found in the most recent search.
$LASTID$
The ID of the last successfully created request.
$LASTOPENEDWINID$
The Send Event keyword that resolves to the ID of the window that was last opened. AR System
$LOCALE$
The language and country code for the specified locale, in the format language_COUNTRYCODE, for
example, en_US.
$NULL$
A null value.
$OPERATION$
The current mode or operation being performed. One of the following values is returned:
CREATE--For a Create request operation.
DELETE--For a Delete operation.
DIALOG--When a form is opened as a dialog box.
GET--For a Get Entry operation.
MERGE--For a Merge operation.
QUERY--For a database search.
SET--For a Modify operation.
SET ALL--For a Modify All operation.
$OS$
The operating system under which the current process is running.
$ROLES$
For a deployable application, returns the list of roles that map to groups to which the current user
belongs.
$ROWCHANGED$
Evaluates whether a row in a table field has changed in a table loop guide.
0 = Not changed
1 = Changed
$ROWSELECTED$
Evaluates whether a row in a table field is selected in a table loop guide.

0 = Not selected.
1 = Highlighted as the secondary selection.
2 = Highlighted as the primary selection.
$ROWVISIBLE$
Evaluates if a row in a table field is visible.

0 = Deleted, irrespective of table type, whether chunking is enabled, or whether content clipped
is enabled.
Page 1126 of 4705
Home
1 = Not deleted, for non-content clipped tables.
$SCHEMA$
The form on which you are currently operating.
$SCHEMA-ALIAS$
The singular alias used for a form.
$SERVER$
The name of the current AR System server.
$SERVERTIMESTAMP
The current date, time, or both on the AR System server. The keyword is used with the following fields:
$
Date/Time
Time
Date
$TCPPORT$
The TCP/IP port of the local AR System server. AR System administrators use this keyword.
$TIME$
In a character field, the current time is displayed. In a date/time field, the date defaults to the current
date.
$TIMESTAMP$
The current date/time stamp.
$USER$
The name of the user who is currently logged in.
$VERSION$
The version of AR System server. If the version includes a patch, it is also included.
$VUI$
The name of the view of the current active window.
$VUI-TYPE$
The views platform (such as Web or Windows).
$WEEKDAY$
The current day of the week.
Using values in the advanced search bar

Enclose nonnumeric values (including time, selection, and currency values) in double quotation
marks (for example, "07/01/08" for July 1, 2008).
Using selection field values

Selection field values can be specified as text values (in quotation marks) or numeric values or IDs
(not in quotation marks). For example, if you have a Status field with the option buttons labeled
Open, Fixed, and Verified, you can enter either "Open" or 0 to specify the value of Open, because
Open is the first selection value in the selection field. For example:
'Status'="Open"
or
'Status'= 0
Using currency field values

For currency fields, use the Currency Codes submenu to select an available currency code. When
you select a currency code, the double quotation marks are automatically entered (such as "USD" )
. Add the currency value within the double quotation marks (for example, "100 USD" ).
If you do not specify a currency code, the primary allowable currency type is assumed.
Page 1127 of 4705
Home
Using relational operators in the advanced search bar

Relational operators are useful especially in non-text fields (such as date and time fields) when you
want to search for a value within a numerical range.
You can use the following relational operators only in the advanced search bar. You cannot use
them in a form. See Using relational operators in a search.
Operators
Operator
Action
()
Use parentheses to control the order in which the expression is carried out. Operations found within parentheses are
executed together as a unit. For example, in the operation 'Gross Income' ('Unemployment Insurance' + '
Pension Plan Contributions' + 'Income Tax') , the items within the parentheses are added before they are
subtracted from Gross Income.
AND &&
Logical AND of the result of two conditions. The result is true only if both conditions are true. For example, 'Status'="
New" AND 'Assigned to'="Andy" finds all new requests assigned to Andy. You can use two ampersands ( && )
instead of the word AND.
OR ||
Logical OR of the result of two conditions. The result is true if either condition is true. For example, 'Status'="New"
OR 'Assigned to'="Andy" finds all new requests (regardless of who they are assigned to) and all requests assigned
to Andy (no matter what their status). You can use two vertical lines ( || ) instead of the word OR.
NOT !
Negates the condition that follows. If the condition is false, the result is true. For example, NOT 'Status'="New" finds
all requests that are not new. You can use an exclamation point (!) instead of the word NOT.
LIKE
Performs a pattern search. For example, 'Submitter' LIKE "Bob%ton" finds all requests with a submitter name that
begins with the letters Bob and ends with the letters ton--such as Bob Compton and Bobby Fenton. The LIKE operator
is useful only with character and diary fields. Use square brackets and the LIKE operator for Sybase databases.
Square brackets when used along with the LIKE operator do not work with Oracle databases. See Using relational
databases with BMC Remedy AR System and the Operators.
+
Adds two numerical values (integer, real values, or decimal).
Adds an integer interval to a date/time value.
Adds two character strings.
For example, 'Create date' > $DATE$ + (8*60*60) finds all requests that were created after 8:00 a.m. today. (*8*60*
60* is the number of seconds in 8 hours.)
Subtracts two numerical values (integer, real values, or decimal).
Subtracts two date/time values (resulting in an integer). Subtracts an integer interval from a date/time value.
For example, 'Create date' > $TIMESTAMP$ - (7*24*60*60) finds all requests that were created within the past week.
(*7*24*60*60* is the number of seconds in one week.) This is useful to include in a custom report of all requests
created in that week.
***
Multiplies two numeric values. For example, 'Quantity' * 'Price' > 50 finds all requests where the contents of the
Quantity field multiplied by the contents of the Price field is over 50.
Divides two numeric values. For example, 'Total Expenses' / 'Total Income' = 2 finds all requests where the total
amount spent for expenses is twice the total amount of income.
Page 1128 of 4705
Home
Modulo of two integer values (the remainder of a division of the values). Because a percent sign is also a valid
wildcard symbol, the context determines how it is interpreted. When used as part of a search statement, it is
interpreted as a wildcard symbol; when used in the expression where an operator is expected, it is interpreted as
modulo.Note: Use the modulo operator only with fields whose data type is integer. If you use this operator with fields
that have other data types, such as Date/Time, an error occurs.
<
Matches contents that are less than the value. For example, 'Create date' < ($TIMESTAMP$ - 24*60*60) finds all
requests created more than 24 hours ago. (24*60*60 or 86400, is the number of seconds in 24 hours.)
>
Matches contents that are greater than the value. For example, 'Create date' > "09/24/07 00:00:00" finds all requests
with Create dates that are newer than midnight September 24, 2007.
!=
Matches contents that are not equal to the value. For example, 'Status' != "Closed" finds all requests that are not
closed.
<=
Matches contents that are less than or equal to the value. For example, 'Salary' <= 30000 finds all requests where the
contents of the Salary field are less than or equal to 30000.
>=
Matches contents that are greater than or equal to the value. For example, 'Create date' >= "09/30/07" finds all
requests with Create dates equal to or more recent than September 30, 2007.
Matches contents that are exactly equal to the value. For example, 'Status' = 0 finds all requests with a status value
equal to the first selection value.
Order of precedence for multiple operators

When you use multiple operators to construct qualification criteria, they are executed in the
following order of precedence:
1. ( )
2. NOT (!) - (unary minus)
3. ** / %*
4. + 5. < <= > >= = != LIKE
6. AND (&&)
7. OR (||)
If the qualification contains multiple operators of the same precedence value, they are executed in
the order that they occur (from left to right). For example, in the expression A + (B*C), the
multiplication takes first precedence because it occurs within parentheses, which are of a higher
precedence than addition.
Using wildcard symbols in the advanced search bar

When you specify search criteria to find requests, you can use wildcard symbols as shown in the
following table to indicate one or more characters:
Wildcards
Use this
wildcard:
To match these characters:
% (Percent)
Matches any string of 0 or more characters. For example: J%son matches Jackson, Johnson, Jason, and
Json.
Page 1129 of 4705
Home
_ (Underscore)
Matches any single character. For example: B_b matches Bab, Bob, and Bub.
- (Hyphen)
Indicates a range. Always use within square brackets ([]).
[ ] (Square
brackets)
Matches any single character within a specified range or set. For example, [a-f] matches the range of
[^] (Square
brackets with
Matches any single character not within a specified range or set. For example, [â-f] matches all characters
characters a through f, and [abcf] matches the set of characters a, b, c, or f.
except the range a through f, and [âbcf] matches all characters except a, b, c, or f.
caret)
In the advanced search bar, wildcard symbols are interpreted as wildcards only when used with the
LIKE operator; otherwise, they are interpreted as explicit characters. You must use the percent
symbol (%) when you want to include leading or trailing characters in your search. For example, if
you want to find all requests submitted by Jill Bobbington, Bobby Fenton, and Bob Comptonson,
enter the following text in the advanced search bar:
'Submitter' LIKE "%Bob%ton%"
Note
Square brackets and the symbols associated with them do not work with Oracle
databases.
Examples of advanced search bar statements

The statements in the following examples illustrate ways you can use the advanced search bar to
build complex searches.
Finding all requests that were created by someone other than the current user
Enter
'Submitter' != $USER$
This example uses the not equal to operator (!= ) to find instances where the value in the Submitter
field is not equal to the user who is currently logged in. Notice the use of the $USER$ keyword.
Finding all requests that were created after 10:00 a.m. on the current day
Enter
'Create date' > "10:00:00"
The example uses the greater than operator (> ) to find requests where the value of the Create
date field is greater than the current day at 10:00 a.m.
Page 1130 of 4705
Home
Finding all requests that have been created for any problem that involves printing
Enter
'Submitted Problem Type' LIKE "%print%"
The example uses the LIKE operator to perform a pattern search that finds requests with the word
print anywhere in the Submitted Problem Type field.
Finding all requests with a status of released

Enter
'Status ' = "Released"
Notice the spaces after the word Status in the field specification. The spaces exist in the field label
on the form being used. If you use the Field List dialog box by selecting the Fields button on the
advanced search bar, the spaces (and single quotation marks) are added automatically.
Note
A search statement that includes a not equal to operator (!= ) might return unexpected
results because the advanced search bar complies with ANSI SQL standards. One of
these standards distinguishes between fields that contain data and fields that have never
contained data.
For example, the following statement does not return requests where CharacterField is empty:
'CharacterField' != "one"
To include requests where CharacterField is empty, enter the search statement like this:
'CharacterField' != "one" OR 'CharacterField' = $NULL$
Reporting on BMC Remedy AR System data

The BMC Remedy AR System Report Console provides a single interface for all Web-based
reporting functions. You can create and run ad hoc reports based on user-specified criteria, and
can also run existing reports that are defined by others or installed with BMC applications.
To open the Report Console, click the BMC Remedy AR System Report Console link in the
Quick Links area of the home page, or click the Report button after running a form search in a
browser. You can also open the Report Console by entering the correct URL to the AR System
Report Console form. BMC Remedy applications provide additional links that open the Report
Console.
The following topics provide information about reporting:
Page 1131 of 4705
Home
BMC Remedy AR System Report Console

Report designer screen
Report types
Running reports in the Report Console
Creating reports
Editing and deleting reports
Scheduling reports
Publishing reports
Saving or exporting BMC Remedy AR System reports
Using a BIRT editor to create or modify web reports
The following topics provide information about report permissions:
Running reports
Setting permissions for a report
BMC Remedy AR System Report Console

The Report Console includes the report list, where you can select and run reports, and the report
designer screen, where you can create and modify reports.
The Report Console with the report list
The links in the upper right part of the report list screen have the following functions:
Link name
Description
Close
Close the Report Console and return to the previous browser window.
Help
Open the Report Console help.
Logout
Log out of BMC Remedy AR System.
Refresh
Refresh the list of reports.
New
Create a new report. See Creating reports.
Delete
Delete the selected report.
Publish
Run and publish the selected report immediately.
Publish/Schedule
Create or modify a schedule to run and publish a report at a specified interval.
For information about using the remaining options in the report list screen to work with reports, see
Page 1132 of 4705
Home
Finding reports
Running reports
Adding to or overriding a report query at runtime
Reporting based on a search
Report designer screen

The report designer screen allows you use to create and edit Web reports. It displays the name of
the current report in the upper left and indicates whether it is new or being edited.
The report designer screen includes the Report Definition area, where you define the report
content, and the Filter By area, where you define an optional search query to select the records to
be included in the report.
The report designer screen of the Report Console
The buttons in the upper right of the report designer screen have the following functions:
Button name
Description
Preview
Preview the report
Save
Save the report
Save As
Save the report with a different name (make a copy)
Back
Return to the report list screen of the Report Console
For information about using the options in the report designer screen, see
Defining a Web list report
Creating a Web chart report
Using a query in a Web report
Defining BMC Remedy AR System reports
Page 1133 of 4705
Home
Report types
The options available for creating, running, and saving reports vary based on the report type. BMC
Remedy AR System includes these report types:
Web reports The Web report type provides browser users the ability to create nicely
formatted reports. Results can be returned in the form of a list, many styles of charts, or a list
and chart together. Web reports can contain links that allow you to drill down from the report
to open BMC Remedy AR System records and view the data upon which the report is based.
Web reports can be saved in several standard formats, including Adobe PDF and Postscript,
and Microsoft Word, Excel, and PowerPoint formats.
Web reports are suitable to use in presentations, documents, email, and printing, and can
transfer data directly to spreadsheet format. Also, because each row in the report output
contains a link to the underlying data in the form, you can use Web reports to work
interactively with BMC Remedy AR System data.
BMC Remedy AR System reports You can use BMC Remedy AR System reports to
generate output in several standard formats, including XML, .arx, and comma-separated
value (.csv). BMC Remedy AR System reports are typically used to export data in the
specified format for use in another application, for importing data into another BMC Remedy
AR System server, and to generate statistics based on the report data.
Crystal reports Some installations of BMC Remedy AR System are integrated with the
SAP BusinessObjects or Crystal Reports reporting tools. If your administrator has installed
one of these products and has designed Crystal reports for use with BMC Remedy AR
System, you can run Crystal reports from the Report Console.
Running reports in the Report Console

The following topics provide information about how to use the Report Console to run existing
reports:
Finding reports
Running reports
Exporting or printing Web reports
Opening the records in a Web report
Exporting BMC Remedy AR System reports
Adding or modifying a qualification at runtime
Using the My Reports toolbar button
For information about creating reports, see Creating reports.
Page 1134 of 4705
Home
Finding reports
When you open the Report Console from the home page, all reports to which you have permission
appear in the list. You can narrow the list to show only those reports you have created, or only
reports belonging to a certain category, such as Incident Management.
When you click the Report button after running a search, the Report Console lists only those
reports that are based on the form you searched. In this case, when you run the report, only the
data you selected from the search results is included, and you cannot add to or override the report
query.
Use any of the following methods to locate reports in the Report Console list:
In the Show field, select Created by Me to list only reports you have created.
If report categories are defined, select a category from the Category field menu to see only
the reports assigned to that category.
Sort the list by clicking any of the column headings. For example, click the Form Name
column heading to sort the list by the associated forms.
Use the expand and collapse buttons located below the list to see a longer or shorter view of
the list, or to hide the list.
Running reports
You can run BMC Remedy AR System, Web, and Crystal reports from the Report Console. The
available output formats and how you select them vary by the report type. (The type of report is
listed in the Report Type column.)
In some cases, you can add an additional qualification to the report query at runtime, or override
the built-in query with a new qualification.
Note
In order to run a report, you must have permissions to the form and to the fields included
in the report. If you do not have permission to the form, the report does not appear in the
list of available reports. If you have permission to the form but do not have permission to a
field included in the report, that column is blank when you run the report.
You can run the report of all types as-is, or if the report definition allows, you can change the report
results by adding to or overriding the built-in query.
1. Locate the report you want to run in the Report Console list.
2. (Optional) To narrow the report results by adding a query, click Show Additional Filter, and
then follow the steps described in Adding a qualification at runtime.
Page 1135 of 4705
2.
Home
Warning
If the report includes a primary and secondary form, the filter shows only fields that
are included in the primary form.
3. (Optional) To override a built-in report query, click Override. See Adding to or overriding a
report query at runtime.
4. For BMC Remedy AR System reports only, select the output format before running the
report. See Exporting BMC Remedy AR System reports .
Web reports run in HTML and you select the output format after running the report. See
Exporting Web reports.
5. Use one of these methods to run the report:
Select the report and click Run (
). In this case, the report appears in a viewing
area below the list of reports.

Double-click the report entry in the list. In this case, the report appears in a separate
window. This can be helpful if you need to compare two or more reports at a time.
6. If the Parameter dialog appears, enter the requested information to narrow the report results,
and then click OK.
The configuration parameter arsystem.nativereport.onscreen_max_entries controls the
number of entries that are to be displayed on the browser. (This is applicable only for Native reports
with destination to screen.) The browser cannot scale to show a large amount of records (for
example, 100,000 records). The system administrator must configure it to an appropriate value.
The default is set to 2000.
The arsystem.nativereport.onscreen_max_entries configuration property does not place
a limit on data exports such as CSV and ARX.
Note
You might see the Out Of Memory error messages when you run a BMC Remedy AR
System report without providing any qualification. To resolve this issue:
You can set the Allow Unqualified Search option on the Server Information form
for reports. (If the administrator configured the AR System server to disallow
unqualified search, reports without a qualification will return an error message.)
Buffering and streaming were introduced to reduce the heap consumption.
Exporting or printing Web reports

You can export or print Web reports based on your requirements.
Page 1136 of 4705
Home
Exporting Web reports

You can export Web reports to Microsoft Excel, Microsoft Word, Microsoft PowerPoint, Adobe PDF,
and Adobe PostScript formats. You can either save the result to a file in the selected format, or
open the report in the selected application to work with the report data.
Tip
Although you cannot save a Web report directly to .csv format, you can still use this
format to transfer the data from a Web report to another application. To do so, export the
Web report to Microsoft Excel, and then use Excel functions to save the data in .csv
format.
1. Run the report as described in Running reports.

2. In the report viewer, click Export Report
Note
If the mid tier is running on UNIX, you might face issues while exporting reports in
various formats such as Excel or Word. Add the (-Djava.awt.headless=true) Java
option in the /bin/startup.sh file along with other Java options before starting
Tomcat (or any other web server that you might be using).
For example, add the Java options on Linux as follows:
JAVA_OPTS="$JAVA_OPTS -Djava.awt.headless=true"; export JAVA_OPTS
3. In the Export Report dialog box, select the format for the exported report.
4. (Optional) Select which pages of the report to export. By default, all pages are selected.
5. (Optional) For PDF, PostScript, and PowerPoint formats, select Auto, Actual Size, or Fit to
Page.
These options help control how large reports are paginated in the selected output file type.
6. Click OK.
7. In the File Download dialog box, select whether you want to open or save the file.
Open The report opens in the selected application, such as Excel. (You must have
the application installed to use this option.)
Save The Save As dialog box appears. Navigate to the appropriate location, enter
a file name, and then click Save.
If you select Open, you can then use menu options in the associated application to
print, email, and search the report results.
Page 1137 of 4705
Home
The links to the underlying records in a list report remain active when you export the
report. This means that other users with access to the BMC Remedy AR System
server where the report was run can use the links in the report to drill down to the
underlying records. However, if a user without access to the BMC Remedy AR
System server clicks on the link in the exported report, the user will see a browser "
page not found" error.
Note
Chart drill-down is deactivated in an exported report. Only list report links
remain active.
Printing Web reports

2. In the report viewer, click Print Report (
).
3. In the Print Report dialog box, indicate which pages you want to print.
4. Click OK.
Tip
You can also export the report, and then print the report from the selected application.
Opening the records in a Web report

Web reports can contain links to the underlying data. This allows you to "drill down" by clicking the
links to open the underlying records and work interactively with the data in the report.
In a list report, each row represents a single request and contains a link to that request. The link
appears in the Request ID column if it is included in the report. If the Request ID field is not
included, the link is created on the Short Description field, if included, or on the first field in the
report (the left-most column). When you click the link, the request underlying that row of the list
opens.
In a chart report, elements of the chart reflect a group of one or more underlying records. For
example, the bars in a bar chart might represent the number of students enrolled in each class in
the Sample applications. Clicking on a bar in the chart opens the form, and the records summarized
in that bar of the chart are listed in the results list.
The following are restrictions on using the drill-down feature of Web reports:
Page 1138 of 4705
Home
The form must allow drilling down from a report. If the administrator has turned off the "Allow
Drill Down from Web Report" form property, reports on that form do not allow you to drill
down to the underlying requests.
If the form is a vendor form, the associated plug-in must include the fields used in the report
query. If not, the following error message appears:
"Illegal field encountered in the qualifier. (ARERR 3355)."
In a chart report, you cannot drill down in the following situations:
The report was run from a search results list or table field by selecting records and
then clicking Report. In this case, the chart drill-down links are not available, because
the records represented in the chart are already available in the search results.
The selected field is a field type that contains group IDs, including the Group List field
on the User form, the Assignee Group field, or a dynamic field (field ID in the range
60000 - 69999). In this case, BMC Remedy AR System reports "No matching
requests (or no permission to requests) for qualification
criteria. (ARWARN 9296)."
The field used for the Category axis contains records with a null value. In this case,
BMC Remedy AR System reports "No matching requests (or no
permission to requests) for qualification criteria. (ARWARN
9296)."
The Category axis is based on a group field. This includes the Group List field in the
User form (field 104), the Assignee Group field in any form (field 112), or any dynamic
group field (field ID in range 60000 - 69999).
The chart is in an exported report.
Exporting BMC Remedy AR System reports

You can export the results of an BMC Remedy AR System report to the following file formats:
BMC Remedy AR System export (file extension .arx)
BMC Remedy AR System XML (file extension .xml)
Comma-Separated Value (file extension .csv)
All of these formats can be used to import data to an BMC Remedy AR System form with BMC
Remedy Data Import. CSV files can also be imported to other applications, such as Microsoft Excel.
For more information about the BMC Remedy AR System report file types, see Saving or exporting
BMC Remedy AR System reports.
1. Select the report from the list.
2. In the Destination field, select whether to send the report to the screen, to a file, or to a
printer.
3. In the Format field, select the output format for the report.
Page 1139 of 4705
Home

When you open the Report Console to run a report, BMC Remedy AR System uses the report's
built-in query to select the records included in the report. Two additional options allow you to add a
qualification:
Show Additional Filter to narrow the report results
Override to override the built-in query to widen or change the report results.
If the edit icon (
) appears next to a report entry in the Report Console, you can open the report
definition to examine the built-in query.

The Adding or modifying a qualification at runtime topic explains how to use these two options,
describes example situations to illustrate their use, and explains why they are sometimes
unavailable or might produce unexpected search results.
Adding or modifying a qualification at runtime

A qualification is any query statement, such as "Number enrolled is greater than 0". When you
enter an additional qualification using Show Additional Filter, and do not select Override, your
qualification is added to the report's built-in query (using the AND operator). If you add a
qualification and select Override, then your qualification replaces the report's built-in query. If you
select Override but do not add a qualification, then the report's built-in query is ignored.
Note
You can also add a qualification at runtime when publishing a report. For more information
, see Publishing reports.
This topic includes:

To add or modify a qualification at runtime using Show Additional Filter and Override
Restrictions on modifying qualifications at runtime
Examples for modifying qualifications at runtime
To add or modify a qualification at runtime using Show Additional Filter and Override
1. Open the Report Console and select the report to run from the list of reports.
2. Click Show Additional Filter.
Warning
If the report includes a primary and secondary form, the filter shows only fields that
are included in the primary form.
Page 1140 of 4705
Home
3. Build the additional qualification, using either the Simple Query Builder or the Advanced
Query Builder, as described in Using a query in a Web report .
4. (Optional) Select Override to replace the report's built-in query with the added qualification.
If the Override check box is not available, overrides are disabled for this report. In that case
you can only add your qualification to the report and cannot override the built-in query.
5. Click Run to run the report with the added qualification.
Restrictions on modifying qualifications at runtime

Some reports do not allow modification at runtime. These options are unavailable in the following
cases:
If you search a form and then use the Report button in the search results list to create a
report, the records that you selected in the search results are passed to the Report Console
as a predefined query. In this case, the Show Additional Filter and Override options are
not available.
Override does not override the "base qualification" used in BMC Remedy AR System reports
. A base qualification is defined by the administrator and is outside of the report definition. If
the report contains a base qualification, your qualification is added to the base qualification.
Base qualifications are not visible in the report designer screen.
Note
Out-of- the-box Web reports provided with BMC Remedy IT Service Management
cannot be modified, even if the user is an application administrator, because the
reports are not created using the BMC Remedy Action Request System Report
Console. However, an application administrator can delete these reports.
The administrator can disable unqualified searches for reports. In other words, "1=1"
qualifications are not allowed for reports. In this case, attempts to run a report for an
unqualified search result in an error.
Examples for modifying qualifications at runtime

The following examples show you how to modify qualifications or queries at runtime:
Example of adding a qualification to narrow a report

An example report named Class Registration, based on the Sample:Classes form, has a built-in
query stating "Number enrolled is greater than 0". The report normally includes all classes for which
at least one student is enrolled. An instructor, Peter Thomas, needs to see this list, but only for the
courses he teaches.
Peter could use the Class Registration report and add a qualification before running the report,
Page 1141 of 4705
Home
such as "Instructor is equal to Peter Thomas" or "Instructor is myself". His additional qualification is
added to the built-in query, and the resulting report shows only those courses for which he is the
instructor and at least one student is enrolled. In other words, he narrows the report results from all
classes with enrolled students to only those he teaches that have enrolled students.
Examples of overriding a report query

A manager for the training program, on the other hand, needs to see a list of all classes, including
those where the enrollment is zero. Instead of writing a new report, she could use the Class
Registration report, but override the built-in query. By overriding the built-in query and adding no
additional conditions, she eliminates the built-in query. Thus she widens the report results to
include those classes that have no enrollees.
You can also use the Override and Show Additional Filter options together to replace any built-in
query in the report. For example, to see a list of all classes in Madrid with or without students
enrolled, the training program manager could use the Class Registration report, add the query "
Location is LIKE Madrid%", and click Override. The additional query narrows the report to include
only classes in Madrid, and the override causes the report to include classes with no enrollees as
well as those with students enrolled.

When you run a search on an BMC Remedy AR System form or view a table in a browser, the
Report button appears below the search results or in the table (assuming the form or table field is
not configured to prevent this). The Report button allows you to generate a report based on the
search results or table field contents.
Search results with Report button
When you click Report, the following actions occur:

The Report Console opens, listing only those reports that are associated with the form you
searched.
You can also create a new report definition based on this search. In this case the report is
automatically associated with the current form. If you select the Add default fields and sort
order option, the results list fields are automatically included in the report.
Page 1142 of 4705
Home
The records that are selected in the search results at the time you click Report, along with
the sort order, are passed to the Report Console as a predefined query.
When you search a form, the first record in the search results is automatically selected. If
you click Report without changing this selection, only the first record is included in the report
. Use any of the following methods to select the records you want to include in the report:
Select All Selects all entries in the table.
SHIFT-click To select a range of entries, click an entry and hold down the SHIFT
key. Click another entry above or below the original selection, and then release the
SHIFT key.
CTRL-click To report on multiple entries, click an entry and then hold down the
CTRL key. Continue to click the entries you want to include in the report while holding
down the CTRL key. When you have finished selecting table entries, release the
CTRL key.
Deselect All Clears all selections in the table.
If no entries in the table are selected when you click Report, the report includes all the
entries in the search results.
Using the My Reports toolbar button

With the My Reports toolbar button, you can save the sequence that generates a report based on
a search. Each named report in the My Reports list is unique per server, per form, and per user.
The My Reports feature is helpful if you frequently generate reports based on the same search, but
do not want to create a report definition.
Saving a report to the My Reports toolbar menu

1. Run a search on a form.
See Running and saving searches.
2. Run a report based on the search results. See Reporting based on a search.
3. Close the report.
4. In the browser window containing the search results, select My Reports > Save.
5. Enter a name for the report, and click OK.
Running a saved report from the My Reports toolbar menu

1. Open the form associated with the report that you saved.
2. Select My Reports > Run > reportName.
Managing reports from the My Reports toolbar menu

1. Open the form associated with the report that you saved.
2. Select My Reports > Manage.
The saved reports appear in a dialog box.
3. Delete, disable, or enable reports as needed.
4. Click Save.
Page 1143 of 4705
Home
Creating reports
This section describes how to define a new Web or BMC Remedy AR System report. (Crystal
reports are pre-designed and must be installed by the administrator.)
Web reports are suitable for preparing formatted list reports, which are presented in a table, and
chart reports, which allow you to select from various types of charts to illustrate the data. By using
the preview feature, you can use Web reports to work interactively with the data in the form.
BMC Remedy AR System reports are often used to export data in XML, .arx, or .csv format for use
in another application or on another BMC Remedy AR System server. In addition, you can use
BMC Remedy AR System reports to generate statistical values based on the data. BMC Remedy
AR System reports can be run on the Web.
The following topics provide information about how to create reports:
Setting up a new report
Types of report charts
Defining a chart report
Using the simple query builder
Using the advanced query builder
Queries on selection fields
Specifying fields and sorting criteria for a report
Including statistics in a report
Configuring the page setup in the General section
Specifying which records are in a report
Entering a description for a report
Specifying the report administrator and status
Setting up a new report

When you click New to create a report, you must first define the type of report, its associated form,
and the report name in the New Report screen.
Page 1144 of 4705
Home
Depending on the type of report you are creating, BMC Remedy AR System then opens either the
report design screen of the Report Console (for Web reports) or the ReportCreator form (for BMC
Remedy AR System reports).
Starting a new report

1. In a browser, click the BMC Remedy AR System Report Console link on the home page to
open the Report Console.
2. Click New
3. In the Type field of the New Report window, select the Web or BMC Remedy AR System
report type. This field is required.
4. In the Formfield, enter the name of the form to use for the report. This field is required.
(Optional) To limit the list of forms to those that are already used in other reports,
select Forms Used in Existing Reports. This can speed up retrieval of the list of
forms, but any form that is not already used in some report does appear on the list.
To find the form quickly, type the first few letters of the form name into the field. For
example, type "Sample" to select from the list of forms related to the Sample
application.
5. Select or clear the "Add default fields and sort order " check box:
Selected Fields that appear in the form's results list after a search are
automatically added to the report definition, along with the default sort order. You can
remove or change these fields and sort order later if necessary.
Not selected No fields are added to the report definition automatically.
6. In the Name field, type a name for the report. This field is required.
The report name must be unique. The maximum length is 128 characters. Also, you cannot
change the name of the report after you exit this screen, so use care in assigning a report
name.
Note
Each report must have a unique Name/Locale combination. For example, two
reports can both be name "Monday", if the locale for each report is different.
7.
Page 1145 of 4705
Home
7. Click OK.
If you selected the Web report type, the Report Console report designer screen appears. Build the
Web report definition using the following procedures:
If you selected the BMC Remedy AR System report type, the ReportCreator form opens instead.
See Defining BMC Remedy AR System reports .

List reports are presented in the form of a table, with one column for each field that you add to the
report. One column of the report includes a link to the record in the underlying form (assuming the
form properties allow this), so you can open the record and view the data underlying the report.
For example, a partial report based on the Sample:Classes form might list all class records in the
form, showing the class title, location, instructor and number enrolled.
Example list report based on the Sample:Classes form
A link to the underlying data appears in the report results, assuming the form properties allow this.
The link is created on the Request ID if it is included in the report. If the Request ID field is not
included, the link is created on the Short Description field, if included, or on the first field in the
report (the left-most column).
Defining a list report

1. Follow the steps described in Starting a new report.
2. (Optional) In the Report Definition area, add a brief description of the report in the
Description field.
This description appears in the list of reports in the Report Console. If you do not enter a
description, it is identified as a "Web Report."
3. In the Content field, select List or Chart + List.
List The report is presented as a table.
Page 1146 of 4705
3.
Home
Chart + List The report is presented as a chart, followed by a table. Use this
procedure to define the list section of the report. To define the chart, see Creating a
Web chart report.
4. (Optional) To share this report with other users who share at least one permission group in
common with you, clear the Private check box.
Other users must have also permission to the form in order to run the report, and they must
have permission to the fields included in the report in order to see the data in the report.
5. In the Columns tab, select fields from the Available Fields list to include in the report, and
then click Add, double-click, or drag them to the Column list.
You must add at least one field to the Column list to be able to save the report.
If you selected "Add default fields and sort order " when creating the report, the
defined results list fields for the form are already in the Column list.
You can select multiple fields at a time from the Available Fields list. To add all fields
to the report, click Add All.
You can include any field type except Diary fields in the report.
To remove a field from the report, select it in the Column list and then click Remove,
double-click the field, or drag it from the Column list back to the Available Fields list.
To remove all fields from the report definition, click Remove All.
Note
The available fields come from the standard view of the form or from the
view defined as the Master View for the locale. If the fields that appear do
not match the fields you see on the form, there might be a Web - Alternate
view defined. Fields in a Web - Alternate view do not appear in the Available
Fields list.
6. Use the Up and Down buttons next to the Column list to change the order of the columns in
the report.
7. (Optional) In the Sorting and Grouping tab, select one or more fields on which to sort the
report, and then click Add, or drag the selected field to the sorting list area.
If you selected "Add default fields and sort order " when creating the report, the
default sort order for the form is already added to the report definition.
To change the sort order between ascending and descending, click the arrow in the
Dir column for each field.
To group repeated values, click the Group check box.
8. (Optional) Define a qualification to identify the records that appear in the report. See Using a
query in a Web report.
9.
Page 1147 of 4705
Home
9. (Optional) To preview the report before you save it, click Preview.
A sample report runs and appears in a separate browser window. The Preview feature
allows you to check and modify the report design until you are satisfied with the results.
You can also use the Preview feature in cases where you want a quick view of the data in a
form. You can print the report or export data from the preview screen.
Note
When you preview a Report that has a base qualification, the base qualification is
ignored. In this case, the report preview might include more records than when you
run the report from the Report Console list.
10. To save the report for future use, click Save.

11. Click Back to return to the Report Console report list.

You can generate various types of charts and graphs to illustrate the report data. You can also
generate a chart or graph together with a list report that shows the supporting data.
For example, a tube chart could give a quick visual summary of the number of students enrolled in
each class in the Sample application, using the Sum aggregation type to calculate the total enrolled
for all locations.
Example chart report based on the Sample:Classes form
In ad hoc reports, you can click in the data area of the chart to open the form with a results list
containing the underlying requests. This drill-down function allows you to work interactively with the
data at the time you run or preview the report.
For example, to see more information about the students enrolled in the class "Managing Within the
Page 1148 of 4705
Home
Law" in the Sample application-, the instructor can run this example report and then click the
column labelled "Managing Within the Law" in the chart. The Sample:Classes form then opens with
a results list containing the records for each student enrolled.
Types of report charts

The following table describes the types of reports available from the Report Console:
Chart
Description
Pie
Pie charts are most often used to display a few components that are easily distinguishable. Typically, each slice of a
pie chart displays statistics from one variable as a slice of the pie.
Bar
Bar charts are most often used for direct comparison of magnitude between categories. Bar charts can also be used to
show time dependent data when the time interval is small.
Line
Line charts are most often used to display trends. Line charts display values along a common baseline, which allows
quick and accurate comparisons.
Area
Area charts are used to display a limited number of related, continuous variables.
Meter
Meter charts measure the most recent variable value from the variable associated with that meter. Meters can be
configured to show increasing levels of severity.
Scatter
Scatter charts are used to analyze the relationship between two variables. One variable is plotted on the horizontal
axis and the other is plotted on the vertical axis.
Tube
Tube charts are used to display a comparison of the quantity of each variable.
Cone
Cone charts are used to for direct comparisons of magnitude between categories in a cone shape.
Pyramid
Pyramid Charts display variables in a way that reveals hierarchical structure.
Defining a chart report

1. Create a new report as described in Starting a new report.
2. In the Content field, select Chart or Chart + List.
Chart The report is presented as a chart or graph of the type you select.
Chart + List The report is presented as a chart, followed by a table. Use this
procedure to define the chart section of the report. To define the list, see Defining a
Web list report.
3. In the Chart Options tab, select the chart options:
Type The type of chart you want to produce, such as a pie chart or a bar chart.
Category Field Select the field to supply the category data for the chart.
In a pie chart, the values in the category field become the "slices" of the pie. In graphs
, such as a bar chart, the values in the category field are plotted on the X-axis.
Warning
Make sure that the category you selected includes values. A null value can
inhibit the interactive drill-down functionality of the report.
Page 1149 of 4705
Home
Category Label Supply a label to appear on the chart that describes the category
data.
Aggregation Select an aggregation method that makes sense for the data in the
report.
Count Reports the number of existing records for each unique value in the
category field.
Sum Adds the values in the series field for each unique value in the
category field.
Average Calculates an average of the values in the series field for each
unique value in the category field.
Minimum Shows the minimum of the values in the series field for each
Maximum Shows the maximum of the values in the series field for each
Series Field Select the field to supply the category data for the chart.
In a pie chart, the values in the series field are used to created each "slice" of the pie.
In graphs, the values in the series field are plotted on the Y-axis.
Series Label Supply a label to appear on the chart that describes the series data.
For example, to produce a chart report based on the Sample:Classes form that shows
number of students enrolled in each class, select the following chart options:
Type Tube Chart
Category
Field Class Title
Label Class title
Series
Aggregation Sum
Field Number Enrolled
Label Total enrolled
4. (Optional) To preview the report before you save it, click Preview.
A sample report runs and appears in a separate browser window.
5. To save the report for future use, click Save.
6. Click Back to return to the Report Console report list.

To control which records from the form will appear in the report, build a query to select the data
when the report runs. The query is saved as part of the report definition.
You can use the simple query builder, the advanced query builder, or both. The simple query
builder joins all query statements with the AND operator. Alternatively, advanced users can build
the query using BMC Remedy AR System query syntax with the advanced query builder. To use
the operator types OR or NOT, you must use the advanced query builder.
Page 1150 of 4705
Home
Using the simple query builder

The Report Console includes a simple query builder that allows you to quickly construct a simple
query. By default, the report designer screen opens with the simple query builder active.
The simple query builder, with advanced query builder closed
Building a query using the simple query builder

1. In the Filter By area of the report designer screen, select a field from the Available Fields list.
2. Drag the field to the query area, or click Add Field.
3. Select the query operator:
Is equal to Selects records in which the value in the chosen field matches exactly
the value entered in the query.
Is not equal to Selects records in which the value in the chosen field does not
match the value entered in the query.
Is empty Selects records in which the chosen field is empty.
Is not empty Selects records in which the chosen field contains some data.
Is myself Selects records in which the value in the chosen field matches the
current user's login ID.
Is not myself Selects records in which the value in the chosen field does not
match the current user's login ID.
Is LIKE Selects records in which the value in the chosen field matches the string
defined in the query.
The LIKE operator requires that you use the percent (%) wildcard, which matches any
string of 0 or more characters. For example, to get a report of classes for which
Teresa Logan is the instructor, use one of the following search strings:
Teresa% matches all entries that begin with "Teresa"
%Logan matches all entries that end with "Logan"
T%eresa% would find entries that start with "Teresa" or "Theresa"
4. Type the value to search for in the blank field.
For example, to find Teresa Logan's classes that have students enrolled, you could use the simple
query builder to construct the following query:
Page 1151 of 4705
Home
Using the advanced query builder

The advanced query builder is located below the simple query builder. By default, the advanced
query builder is closed. Click the expansion arrow to open it.
The advanced query builder, opened
To use the advanced query builder to find the same records (Teresa Logan's classes that have
students enrolled), expand the advanced query builder and then add the following qualification:
'Instructor' LIKE "Teresa%" AND 'Number Enrolled' > 0
To add fields, you can drag them from the Available Fields list, or select the field and then click
Add Field. To cause the query builder buttons to appear, you must add a field or click in the query
area.
It is possible to enter queries in both the simple and advanced query builders for the same report. If
you do, these queries are linked with an AND operator when the report runs. If the advanced query
builder is closed, but contains a query, the beginning of the query appears along with the Advanced
expansion button:
Tip
You cannot add elements in the middle of an existing query in the advanced query builder.
If you need to modify an advanced query, you must add the modification on to the end of
the existing query, or revise the entire query.
For more information about building BMC Remedy AR System qualifications, see Running and
saving searches.
You can also use these query builders to add a query to an existing report at runtime. See Adding
to or overriding a report query at runtime .
Page 1152 of 4705
Home
Building a query using the advanced query builder

The following procedure begins in the Report Definition screen and assumes that you have already
created the report itself as described in Starting a new report.
1. In the Filter By area, select the first field that you want to use in the query from the
Available Fields list.
2. Click Add or drag the field to add it to the simple query builder.
3. In the simple query builder, click the down-arrow and select from the list of operations.
4. Enter the value to search for.
For example, to find classes for which Teresa Logan is the instructor, select the Instructor
field and the is equal to operation, and then type in Teresa Logan.
5. To add another item to the qualification, select the appropriate field from the Available Fields
list, and then click Add or drag the field to the simple query builder.
The second search criterion is added to the simple query builder with an AND search. In
other words, a record must match both conditions in order to appear in the report.
For example to find Teresa's classes that have at least one person enrolled, select Number
enrolled and is greater than, and then type in 0.
6. Click Save.
Queries on selection fields

Selection fields include drop-down lists, radio buttons, and check boxes. In selection fields, the sort
order is determined by the database value assigned to each selection. This value is not visible
when you are constructing the query. Depending upon how the database value is configured, you
might get unexpected results.
For example, a Priority field in which the user selects High, Medium, or Low might have the
database values High=0, Medium=1, Low=2. In this case, the query "Priority is greater than or
equal to Medium" will return records with priority set to Medium or Low, because in database terms
qualification is seeking values greater than or equal to 1.
If this occurs, try revising the query to use the opposite operation, for example "Priority is less than
or equal to Medium," and then re-run the search.

Create an BMC Remedy AR System report if you need to export data directly to BMC Remedy AR
System export (.arx), BMC Remedy AR System XML, or comma-separated value ( .csv) format.
1. In the Report Console, click New.
2.
Page 1153 of 4705
Home
2. Select the BMC Remedy AR System report type.

The ReportCreator opens in New mode.
ReportCreator
3. In the Report Name field, enter a unique, locale-specific name for the report; for example,
MyReport-en.
4. From the Report Format drop-down list, select one of the following choices for the format of
the report:
Record Displays each field of the request on a separate line.
Column Displays each field as a column heading, and displays information from
each request in a separate row.
Compressed Compresses the information with commas, white space, or any other
specified character between the columns. In a browser, the compressed format is
viewed in a column format.
5. (For administrators) In the Locale field, enter the locale of the report in the format
language_Country, for example pt_BR.

The country portion of the locale code is optional, depending on whether you want to allow
all country variations of a language to use the report. If you enter only the language portion,
all country variations of a language can use the report. For example, an entry of pt would
include all country variations of Portuguese, but pt_BR designates only Brazilian Portuguese
.
For a list of standard choices for this field, check the Locale view property on any form in
BMC Remedy Developer Studio.
6. In the Report Set field, enter a locale-independent description for the report.
The Report Set field is used to identify locale variants of the same report. The combination
of Report Set and Locale must be unique.
7. Update each tab in the form as described in the following sections.
Entries that are specific to Windows reports are identified in each of the tabs. Those settings
are ignored for Web reports.
8. Save the report.
Specifying fields and sorting criteria for a report

Use the following procedures to specify fields and sorting criteria for reports.
Page 1154 of 4705
Home
To specify fields for a report

In the Fields tab, define the fields on the form to be included in the report.
1. In the Field field, click the menu button to select which fields on the specified form will be
displayed on the report.
2. In the Label field, enter the field name as you want it displayed on the report.
3. In the Field to Add Before/After field, select a field to use as a reference when clicking the
Add After or Add Before buttons.
4. Click Add Before or Add After to set the positioning of fields in a report, with reference to
the Field to Add Before/After field.
5. Click Modify to update the selected field label or width specification.
6. Click Remove to remove a selected field.
7. Click Remove All to remove all selections from the field list.
To specify sorting criteria for a report

In the Sorting tab, select fields to sort on and set the sort order and grouping for each field for the
report. You can select up to five fields for sorting.
1. From the first Field Name list, select the field on which you want to sort.
2. Select Ascending or Descending Sort Order for the selected field.
3. To group by a field, select the Group check box for the selected field.
4. Repeat steps 1 through 3 for the other fields on which you want to sort.
Including statistics in a report

In the Statistics tab, define expressions that will calculate statistics for the requests contained in the
report. Use the Statistics tab to specify what type of statistics to include.
1. From the Operation field, select the appropriate operation:
Count Tallies the number of requests.
Sum Adds up specified fields or the arithmetic relationship among fields.
Average Calculates the average of specified fields.
Minimum Calculates the minimum value for a specified field.
Maximum Calculates the maximum value for a specified field.
Except for Count, these operations can be applied only to numeric and date/time
fields. Each operation can apply to the whole report, or to a group of requests in a
report. Groups are defined in the Sorting tab.
2. From the Expression field, select a field from the menu list to include as part of a statistic.
An expression is required for all statistical operations except Count. Whether you include an
expression for a Count operation depends on how you want rows with null values to be
counted.
If you are defining a Count operation that includes an expression, only rows with a value that
is not null for the specified expression are counted when the report is run. If you are defining
Page 1155 of 4705
Home
a Count operation that does not include an expression, all rows returned are counted,
including those with null values.
The menu list displays all numeric or date fields in the form. Expressions can include any of
the following values:
Numeric fields
Date fields
Status history fields
Keywords
The most commonly used keywords are $DATE$, $NULL$, $TIME$, $TIMESTAMP$,
$USER$, and $WEEKDAY$. Keywords are case-sensitive and must be entered in all
capital letters. For a complete list of AR System keywords, see Keywords.
Note
For reports to run properly in a browser, you must add a backslash to the
keyword in the Expression field, for example, $\TIMESTAMP$.
Numbers
You can type numbers directly into the Expression field, for example, 5.25, 33, and so
on.
Arithmetic operators (+, -, **, */, and % )
You can type arithmetic operators directly into the Expression field, similar to the way
they are entered in the advanced search bar.
3. In the Label field, type the label to identify a statistic on the report. You can include any of
the following control characters in a label field:
\b
Backspace
\n
Return
\t
Tab
Backslash
\nnn
ASCII character
4. From the Compute On field, select the scope of a statistic.

You can determine whether a statistic is calculated for the entire report, or for defined groups
within the report by selecting the appropriate setting in the Compute On field.
Report Calculates the statistic for all entries in the report. The statistic appears at
the end of the report.
Group N Calculates a statistic for groups defined in the Sorting tab. The statistic
appears below each group.
5. In the Layout field, for the Windows platform only, specify how you want the results to be
displayed in the report by choosing one of the following options:
Single Displays all the statistical results on one line.
Page 1156 of 4705
5.
Home
Multiple Displays each statistical result on its own line.

Column Displays the result for each value at the bottom of the column of the field
specified in the Expression field. Column is valid only for a column-formatted report.
The Layout field setting works with the Compute On setting to determine where a
statistic appears on a report.
Configuring the page setup in the General section

In the Page Setup tab, you only need to specify the page configuration information in the General
section.
1. Enter the name of the report in the Title field. The report title appears at the top of the report.
2. Enter text in the Header field. The header appears at the top of every page.
3. Enter text in the Footer field. The footer appears at the bottom of every page.
To use keywords for the Title, Header, and Footer fields, click the menu list and select the
appropriate keyword. The data in the Title, Header, and Footer fields must be a single line.
Embedded carriage returns are not allowed.
Specifying which records are in a report

In the Qualification tab, specify which records to include in a report. If a report is run from a results
list, any qualifications defined in this tab are ignored. See Running and saving searches.
Entering a description for a report

In the Description tab, enter a description of the report.

(For administrators only) In the Permissions tab, use the Assignee Groups field to define who has
access to a report.
If the server is configured to allow multiple groups in the Assignee Group field, then this field will
allow multiple groups to be specified, separating each group with a single space. If the server is not
configured to allow multiple groups, then only one group can be specified in this field.
Leaving the Assignee Groups field blank allows only the submitter to view the report. Specifying
Public allows anyone to view the report.
Specifying the report administrator and status

In the Administration tab of the Report Creator form, enter the user name of the person who is
creating the report, and define the status of the report.
1. In the Submitter field, enter the name of the user creating the report.
2. In the Status field, select one of the following options:
Active Makes the report available in the Report Console.
Inactive Indicates a report that is no longer active.
Page 1157 of 4705
2.
Home
Pending Indicates a report that is being reviewed.

If Inactive or Pending is selected, the report does not appear the Report Console list.
Editing and deleting reports

You can edit or delete any report that you created, and administrators can modify or delete any
report. You cannot edit or delete reports created by others, but you can open them to view the
built-in query and fields used in the report.
You can also create a copy of a report by using the Save As button to save the report with a new
name. In that case, you are the creator of the new report and can edit it.
Note
Out-of- the-box Web reports provided with BMC Remedy IT Service Management cannot
be modified, even if the user is an application administrator, because the reports are not
created by the BMC Remedy Action Request System Report Console. However, an
application administrator can delete these reports.
Editing an existing report

1. Select the report in the Report Console.
2. Click the Edit Report icon
that appears to the left of the report name in the console.
3. Make any necessary modifications to the report as described in:

(For BMC Remedy AR System reports) Defining BMC Remedy AR System reports .
5. Click Back to return to the Report Console list.
Deleting an existing report

1. Select the report in the Report Console.
2. Click Delete
Scheduling reports
An administrator can assign the Job Scheduler role to groups so that members can create or
modify a schedule that specifies when a report listed in the Report Console is run and published (
called report scheduling).
Page 1158 of 4705
Home
Note
Only administrators can schedule reports.
Prerequisites for scheduling reports

To schedule reports you must have Job scheduler role in your role list.
1. On the BMC Remedy AR System Administration Console, open the Roles form and search
for Role name as Job Scheduler.
2. In the Production field, select the Reporting User group.
3. Open the User form and assign the Reporting User to the Group List field.
4. Login to BMC Remedy AR System and verify if the user has the permission to publish/
schedule Web reports.
For more information on scheduling reports, see the following section.
To schedule reports
1. In the Report Console list, locate the report that you want to publish.
2. Select the report and click Schedule.
3. If a schedule has not been defined for the report, click New to create a schedule for
publishing a report.
4. (optional) To modify an existing schedule that is defined for a selected report, click Edit.
5. Select the date and time to publish the report.
6. In the Recurrence section, select one of the following:
Options
Descriptions
Run Once
to run and publish the report only once.
Daily
to run and publish the report every day, or in a regular interval of less than a week.
Perform the following:
a. In the Every field, specify the interval to publish the report. For example,
Enter 1 to publish every day.
Enter 2 to publish every alternate days.
Enter 3 to publish after every three days.
b. Select the date and time to stop the report publishing.
Weekly
to run and publish the report on a particular day or days of every week or regular week interval.
a. Enter a number to specify the week interval.
b. Select the day or days you want the report to publish.
c. Select the date and time to stop the report publishing.
Monthly
to run and publish the report on a particular day of every month or regular month interval.
a. Specify or select the day and month interval.
b. Select the date and time to stop the report publishing.
7. Click Next.
8. Specify the details for report publishing. For more details, see Publishing reports.
Page 1159 of 4705
Home
Publishing reports
A user who is authorized to run a report listed in the Report Console can also distribute that report
to a specified recipient or list of recipients (called report publishing). For details about running a
report, see Running reports.
1. In the Report Console list, locate the report that you want to publish.
2. Select the report and click Publish.
Note
If the report was created from a Results List or has been combined with a Saved
Search to create "My Reports," those qualifications will not be used when running
the scheduled report. Therefore, make sure that the report selected contains
appropriate qualifications within the report itself. If no qualifications are defined
within the report, the report will run as an unqualified query and might return more
results than anticipated.
3. In the AR System Report Schedule UI dialog box, select the file type for the report from the
Export options list. For example, PDF, Word, HTML, PowerPoint.
Note
If you use the HTML option, images and charts in a report are not rendered.
4. In the Send report to field, enter the email ID, login ID, login name, or email address of the
recipients to distribute the report.
Note
Use semicolon (;) to separate the email IDs.
In the Send status to field, enter the email ID, login ID, login name, or email address of the
recipients to provide information about the report status or errors that might occur while
publishing the report.
5. In the Qualification to Usefield, use or modify the external qualification that was entered
when searching the form data. If you modify the qualification, by copying it from the Report
Console or the advanced search bar, it overrides the qualification from the initial qualified
search. If this field is empty, the embedded report qualification is used.
Page 1160 of 4705
Home
Note
The Qualification to Use field does not appear when publishing or scheduling a
report from the Report Console instead of performing a form search. It also does
not appear after an unqualified form search or after editing an existing schedule
with a pre-saved empty qualification.
6. Click Finish.
Example of modifying a qualification when scheduling a report

Bob, a manager for the training program, creates an ad-hoc report by selecting the Sample:Classes
form and running a search. Bob saves the qualification in the report by adding a built-in qualification
. If Bob schedules and publishes a report from the search results, the Qualification to Use field
shown during scheduling uses his search qualification, which overrides his built-in qualification.
Chris, a different training program manager, runs a different search on the Sample:Classes form,
selects Bob's report, and then creates his own schedule. Dave, another manager, also runs a
different search on the same form, selects Bob's report, and creates his own schedule. When Chris
and Dave create their own schedules, the Qualification to Use field uses their own search
qualifications.
Saving or exporting BMC Remedy AR System reports

You can save or export AR System data to use in AR System forms, in a spreadsheet, or in other
applications. You can also save or export non-AR System data from another application to use in
an AR System form.
The file formats that you select for exporting depend on the original data source and how you will
use the data. File formats for BMC Remedy AR System reports are explained in the following
sections.
The following topics provide information about how to save or export BMC Remedy AR System
reports:
Using AR Export format
Using AR XML format
Using comma-separated values format
Using record, column, and compressed formats
Using AR Export format

AR Export (.arx) is the default file type. It yields the cleanest results when data is exported and
imported within AR System. The AR Export format properly formats data that you import into an AR
System form by using BMC Remedy Data Import.
Page 1161 of 4705
Home
Note
When an attachment is exported in AR Export format from a browser, a .zip file is created
that includes the .arx file and the attachments.
Using AR XML format

AR XML (.xml) is a BMC Remedy XML standard derived from the W3C XForm standard, and it
contains several elements that are required for AR System use. To import XML data into an AR
System form by using BMC Remedy Data Import, your data must conform to the AR XML data
specification. Data exported to the AR XML file type conforms to this specification. You can also
convert XML data obtained outside AR System to the AR XML standard.
Conversely, you can export AR XML data, parse it with any tool that parses documents that
conform to the XForm specification, and use the data outside AR System. For information about
XForms, see the W3C website.
Attachments are handled in the same manner as in the .arx file type.
Note
When you export AR System data from Crystal Reports to HTML 3.2, HTML 4.0, or XML,
your default export directory depends on whether your computer is connected to a
network. If your computer is connected to a network, and your login profile has a
temporary directory setting under Windows, your default export directory will be %
USERPROFILE%\LocalSettings\Temp. If your computer is not connected to a network
your export will default to whatever temporary directory is set in your Windows
environment settings, for example, C:\Temp or C:\Windows\Temp.
Using comma-separated values format

You can use the comma-separated values ( .csv) format if you plan to use the report data in other
applications, such as Crystal Enterprise or in spreadsheets. For example, if you want to use the
report data in a Microsoft Excel spreadsheet, export it as a .csv file, open Excel, and import the
data into the Excel file.
Note
You cannot export the content of an attachment with a .csv file. If you export a .csv file
with an attachment, only the file name of the attachment is exported.
Page 1162 of 4705
Home
Using record, column, and compressed formats

When you select Record, Column, or Compressed format in the ReportCreator form in a browser,
the report is saved as an HTML file (for example, report.rep.html).
Also, the compressed format is not supported in a browser. If you select Compressed as the report
format, the report is displayed in Column format instead.
Using a BIRT editor to create or modify web reports

This section explains how to use BIRT reporting tools with BMC Remedy Action Request System
Web reports. BIRT is an open source, Eclipse-based reporting system that can be used to create
reports in BMC Remedy AR System.
Using Web reports and the BIRT Report Designer, you can:
Create reports based on BMC Remedy AR System data in the BIRT Report Designer, and
then deploy those reports to the AR System server using the Report form.
Modify out-of-the-box Web reports in the BIRT Report Designer, and deploy those reports to
the AR System server using the Report form.
This section is intended for administrators with expertise using BMC Remedy AR System
Web reports and the BIRT Report Designer. This section is intended to document only
what is specific or different to modify reports for BMC Remedy AR System.
The procedures in this branch describe how to install and use the BIRT designer. BMC
uses this system; however, BMC does not support issues related to creating new reports
with BIRT or after modifying reports shipped with BMC Remedy AR System. For
non-BMC-related questions about BIRT, go to http://www.eclipse.org/birt or visit the
Eclipse Community Forum for BIRT at http://www.eclipse.org/forums.
For information and tutorials about using the BIRT Report Designer, choose Help > Help
Contents in the BIRT Report Designer..
For information about Web reports, see Configuring reporting.
This section provides the following information for using BIRT:

Installing the BIRT Report Designer to work with AR System Web reports
Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences
Creating a new report with the BIRT Report Designer
Modifying an out-of-the-box Web report with the BIRT Report Designer
Importing a Web report to a different AR System server
Deploying BIRT reports to the AR System server using the Report form
Examples for modifying reports with the BIRT Report Designer
Page 1163 of 4705
Home
Installing the BIRT Report Designer to work with AR System Web reports
Before you can modify or create reports using the BIRT Report Designer, you must perform the
following high-level steps:
1. Download version 2.5.1 the BIRT Report Designer.
2. Copy three BMC Remedy AR System plug-ins into their proper location.
3. Specify the BIRT library and template location in the BIRT Report Designer.
For information about system requirements for the BIRT Report Designer, see the Eclipse
documentation.
To download and open the BIRT Report Designer

1. Download the BIRT Report Designer 2.5.1 zip file: http://www.eclipse.org/downloads/
download.php?file=/birt/downloads/drops/R-R1-2_5_1-200909220630/
birt-rcp-report-designer-2_5_1.zip.
The BIRT Report Designer is a 32-bit application, and requires a 32-bit Java installation.
2. Extract the BIRT Report Designer zip file to a destination directory ( BIRTInstallDir).
3. To open the BIRT Report Designer application, click the BIRT.exe executable file.
To copy BMC Remedy AR System plug-ins for use with BIRT

1. Go to BIRTInstallDir, and create in it a plugins subdirectory.
2. Copy and paste the following plug-ins from your mid-tier plugins directory (MidTierInstallDir/
WEB-INF/platform/plugins) to BIRTInstallDir/plugins:
com.bmc.arsys.oda.designtime_versionNumber.buildNumber.jar
com.bmc.arsys.oda.runtime_versionNumber.buildNumber.jar
com.bmc.arsys.studio.api_versionNumber.buildNumber.jar
3. In the BIRTInstallDir directory, launch BIRT.exe.
The BIRT Report Designer application opens.
Where to go from here

Enabling BIRT to access your BMC Remedy AR System data by setting BIRT preferences
Enabling BIRT to access your BMC Remedy AR System data by setting BIRT
preferences
Before you can create new BIRT reports or export and import .rptdesign files, you must first
download and extract resource and template zip files from the AR System Resource Definitions
form, and then configure resource and template preferences in the BIRT Report Designer. The
Page 1164 of 4705
Home
Resource library files contain resource files for localized labels that you use for new labels to add to
a report. The BIRT library files contain the BIRT library (for example, stylesheets) and
out-of-the-box templates that you can use as you modify out-of-the-box reports or when you create
new BIRT reports.
To specify the BIRT library and template location in the BIRT Report Designer
1. To open the AR System Resource Definitions form, type the following URL into your browser
:
http://midTierServer /arsys/forms/ARSystemServer/AR System Resource Definitions
2. In the Type field, select BIRT Library, and then click Search.
AR System Resource Definitions form
3. In the search results, select BIRT Resource File.

4. In the Resource section, select the Resources.zip file, and click Save to Disk.
5. Go to BIRTInstallDir, and create a Library subdirectory.
6. Copy the Resources.zip file to the BIRTInstallDir/Library directory.
7. In the search results, select BIRT Report Library.
8. In the Resource section, select the BIRT_Library.zip file, and click Save to Disk.
9. Copy the BIRT_Library.zip file to the BIRTInstallDir/Library directory.
10. Create a Resources subdirectory in the BIRTInstallDir/Library directory.
11. Extract the BIRT_Library.zip file into the BIRTInstallDir/Library/Resources directory.
This creates the BIRTInstallDir/Library/Resources/Images and BIRTInstallDir/Library/
Resources/Templates directories. This also places the DateParameter.js and
bmc_library.rptlibrary files in the BIRTInstallDir/Library/Resources directory.
12. Extract the Resources.zip file into the BIRTInstallDir/Library/Resources directory.
This creates the BIRTInstallDir/Library/Resources/Resources directory with *.properties
files as content.
13. Open the BIRTInstallDir/Library/Resources directory, and copy its path.
14. In the BIRT Report Designer, choose Windows > Preferences.
15. In the Preferences box, choose Report Design > Resources, and copy the path for the
Resources directory into the Resources folder field, and then click OK.
Resource panel for Preferences in the BIRT Report Designer
16.
Page 1165 of 4705
Home
16. Open the BIRTInstallDir/Library/Resources/Templates directory, and copy its path.

17. In the BIRT Report Designer, choose Windows > Preferences.
18. In the Preferences box, choose Report Design > Templates, and copy the path for the
Templates directory into the Template folder field, and then click OK.
You can now complete the following tasks:

After installing BIRT, you can start creating new reports in the BIRT Report Designer. Perform the
workflow in the following procedures to create a new report in the BIRT Report Designer:
To create a new report with the BIRT Report Designer
To enable data access for a BIRT report by creating a data source
To define the data available in a report by creating a data set
To preview and save a new BIRT report
To create a new report with the BIRT Report Designer

1. In the BIRT Report Designer, choose File > New > New Report.
2. Enter a file name.
Use the default file location or browse to a different file location.
3. If you want to use a blank report template, click Finish.
4. If you want to select a report template, click Next, select a report template, then click Finish.
The new report appears in the Layout editor pane of the BIRT Report Designer.
New report in the BIRT Report Designer
To enable data access for a BIRT report by creating a data source

Before creating new BIRT reports, you must build a BIRT data source to connect a BIRT report to a
data source, such as an AR System database. A BIRT data source allows you to access data for a
BIRT report.
1.
Page 1166 of 4705
Home
1. In the BIRT Report Designer, go to the Data Explorer tab, right-click Data Sources, and
select New Data Source.
Data Explorer pane
2. If the Data Explorer tab is not open, choose Window > Show View > Data Explorer .
3. In the New Data Source dialog box, make sure Create from a data source type in the
follow list (default) and BMC Remedy AR System ODA Data Source (default) are selected
, and then click Next.
New Data Source box
If BMC Remedy AR System ODA Data Source does not appear as a selection in
the New Data Source box, make sure the correct BMC Remedy AR System plug-in
files were copied to the BIRT install directory. See To copy BMC Remedy AR
System plug-ins for use with BIRT.
4. In the New BMC Remedy AR System Designtime Data Source Profile dialog box, enter the
User Name and Server for the AR System server data source.
New BMC Remedy AR System Designtime Data Source Profile
5. Click Test Connection.

If the Ping succeeded! message appears, continue to the next step.
If the Ping failed! error message appears, review the details, correct the data source
information, and then test the connection again until you are successful.
6.
Page 1167 of 4705
Home
6. Click Finish, and then click OK to close the box.
To define the data available in a report by creating a data set

After creating a new report, you must build a data set to configure the data to extract from data
source. The data set defines all data that is available to the report. For example, the data set
configuration determines which fields are displayed in the report.
You must create a BIRT data source before you build a data set. For details, see To
enable data access for a BIRT report by creating a data source .
1. In the BIRT Report Designer, click the Data Explorer tab, right-click Data Sets, and select
New Data Set.
2. Configure the New Data Set dialog box:
a. Enter the Data Set Name, for example, Incident Data Set.
b. Under the Data Source node, select the data source, and then click Next.
For example, select a data source previously created for this report.
New Data Set box
3. Configure the Query box:

a. Select a form from the Form list.
Query box
b. Click Add.
The Available Fields dialog box displays all fields in the selected form.
Available fields box
Page 1168 of 4705
Home
c. Select the fields you want to include in the report, and then click OK.
d. In the Qualification field, enter the criteria to be used for the query, click Verify, and
then click Finish.
Enter the qualification using this format:
'field' operator "Parameter"
For example, for the incidents that are not closed, enter:
'Status' !="Closed"
e. Click Finish.
BMC recommends using query for a data set instead of filters. Data set
filters are applied to the entire result set, and can impair performance. Use
the qualification in the query configuration to filter data.
4. If you want to change a column label in a report, configure the Output Columns dialog box.
For example, you can change the Short Description column heading to Description.
a. Select the output column you want to edit.
b. Click Edit.
c. In the Display Name field, change the column label.
d. Click OK.
For a description of the parameters that can be configured in the Data Set editor, see
the BIRT online help.
To preview and save a new BIRT report

1. In the Edit Data Set dialog box, preview the data for the new report by clicking Preview
Results in the left navigation area, and then click OK.
The data that fills in the criteria of the data set appears in the right pane of the Edit Data Set
box.
Preview Results in Edit Data Set
Page 1169 of 4705
Home
2. To save the new BIRT report, choose File > Save As, and then enter a meaningful file name
in the File Name field.
3. Click Finish.

This section explains how you can export the .rptdesign file of a Web report from the Report form,
modify the report in the BIRT Report Designer, and then import the modified .rptdesign file back to
the AR System server using the Report form.
Note
Before modifying an out-of-the-box Web report with BIRT, BMC recommends saving a
copy of the report definition file ( .rptdesign file) and its corresponding record in the Report
form.
To make sure that future upgrades do not overwrite your modified Web report, set Status
to Pending or Inactive.
You can also import your original exported Web report ( .rptdesign file) to a different AR System
server. See Importing a Web report to a different AR System server .
To export a .rptdesign file from the Report form to the BIRT Report Designer
1. To open the Report form, type the following URL into your browser:
http:// midTierServer/arsys/forms/ARSystemServer/Report
2. Search for an out-of-the-box Web report that you want to edit, and select the report from the
search results.
3. In the Instance ID field, copy the Instance ID value of the report you want to edit.
Copying the Instance ID in the Report form
4. Open the Report Definition form, paste the Instance ID you copied in the previous step from
the Report form into the Report Definition GUID field, and then click Search.
5. In the search result, right-click the attached .rptdesign file, and then click Save.
6. Save the .rptdesign file to a folder where you store reports.
Page 1170 of 4705
Home
To modify an imported report in the BIRT Report Designer
Note
Make sure the Report Definition GUID does not change during editing. If the GUID of the
report definition changes, the GUID will not be associated with the correct report.
1. In the BIRT report tool, choose File > Open File, and open the .rptdesign file you exported
from the Report form.
2. Edit the report using the BIRT Report Designer, and then save the edited file.
Note
For details about modifying reports with the BIRT Report Designer, such as adding a row
or column, see the BIRT Report Designer help.
Modifying reports with BIRT Report Designer is discussed further in Examples for
modifying reports with the BIRT Report Designer .
To import the .rptdesign file from the BIRT Report Designer to the Report form
1. In the Report Console, open the Report form, and search for a Web report.
2. In the Report Definition File area, right-click the .rptdesign file, and click Add.
3. In the Confirm Save Request dialog box, click Yes.
4. In the Add Attachment dialog box, click Choose File, then browse and select the .rptdesign
file you edited in the BIRT Report Designer, and click OK.
To modify an out-of-the-box ITSM application report

1. Follow the same procedure as To modify an imported report in the BIRT Report Designer ,
with the following exceptions:
a. When you search for an out-of-the-box report in the Report form, select the Print
Incident report.
b. In the BIRT Report Designer, open the Print Incident report.
c. Right-click the data set, choose Edit > Query > Add, and select Work Detail in the
Available Fields dialog box.
d. Import the report back into an AR System server.
Importing a Web report to a different AR System server

This section explains how to export a Web report and then import it to a different AR System server
.
Page 1171 of 4705
Home
BMC recommends the process in this section instead of the one detailed in Modifying an
out-of-the-box Web report with the BIRT Report Designer .
To import a Web report to a different AR System server

1. In the Report form, select the Web report that you want to export.
2. Export the Web report to an .arx file.
The report attachment will be part of this .arx file.
3. Import the .arx file to the target AR System server using the BMC Remedy Data Import Tool.
To make sure that duplicate report entries are not created in the target AR System, import
the report file using the following fields as key fields: Report Set Name, Locale, and Report
Type. This is a concern when a report has been modified and a fixed report is being moved.
Deploying BIRT reports to the AR System server using the Report form
The reports you create or modify in the BIRT Report Designer must have a record in the Report
form in order to be available in the Report Console. Creating a record for your report in the Report
form includes:
Storing the .rptdesign file
Configuring how the report is filtered by the Category menu in the Report Console
Before you start, determine where in the Category menu hierarchy you want the report to appear.
As shown the following figure, this affects how you complete the Category 1 (for example, Incident)
, Category 2 (for example, Open Incidents), and Category 3 (for example, Count by Assignee
Group) fields. You can complete up to three Category fields, or you can create your own categories
, using the Category fields.
Category menu in the Report Console
To deploy a report to the AR System server using the Report form

1. To open the Report form, type the following URL into your browser:
http://midTierServer/arsys/forms/ARSystemServer/Report
2. In the Report form, click New Request to create a record for the report.
3.
Page 1172 of 4705
Home
3. Complete the required fields of the form and the Category fields.
Enter unique, meaningful names for the Report Name and Report Set Name.
New request in Report form
4. Attach the report definition file for the report to the request by doing the following:
a. Click Add.
b. Attach the .rptdesign file for the report.
c. Click OK.
5. Click Save, and then search for the report you just saved.
6. Copy the Instance ID of the report.
7. To open the Report Definition form, type the following URL into your browser:
http://midTierServer/arsys/forms/ARSystemServer/Report Definition
8. In the Report Definition form, paste the Instance ID you copied for the report in the Report
form into the Report Definition GUID field.
9. Click Search.
The search results show the report design file for the report you are deploying to the AR
System server using the Report form.
10. Go to the Report Console, and refresh the browser.
11. In the Category menu, locate the report you deployed.
12. Click the report to open it, and run the report.
Examples for modifying reports with the BIRT Report Designer

This section provides example scenarios for modifying reports in the BIRT Report Designer.
Applying styles to customize report appearance
Sorting and grouping results by a parameter to organize random results
Adding a column to report results
Adding a parameter to filter report results
Editing a Parameter box field to filter report results
Using subreports to link reports together
Using dynamic drill down reports to provide a series of detailed reports
Converting a currency type with a computed column
Grouping results in multiple groups by using grids
Using a stacked bar chart to compare different series of results
Applying styles to customize report appearance

This example explains how to customize the appearance of a new report by doing the following
tasks:
Page 1173 of 4705
Home
Modify the style elements of the report

Edit the table header of the report
To apply table styles to a report

1. To open the file of a report in the BIRT Report Designer, choose File > Open File, and then
select the file.
The report opens in the Layout tab of the layout editor.
2. In the Data Explorer tab, right-click a data set under the Data Sets node, and drag and drop
it into the layout editor.
Data set element dragged into layout editor in the BIRT Report Designer
After you drop the data set into the layout editor, the table is automatically created with the
fields you selected for the data set.
3. In the bottom left corner of the table, click the Table icon.
The icons for other parts of table appear on the left, such as Table-Header, Table-Detail, and
Table-Footer.
Table for an unformatted report
4. Right-click the icon of the report element to which you want to apply a style, and choose
Style > Apply Style, and select a style appropriate for the report element.
For example, apply the bmcReportTheme:TableHeader theme to the Table-Header.
Selecting a style

5. Save the report.
6. To preview the report, choose Run > View Report > In Web Viewer .
To rename the report header
1.
Page 1174 of 4705
Home
1. In the Layout tab of the layout editor, right-click the report header and choose Edit.
Layout editor
2. Type the updated title of the report.

3. Click Save.
Sorting and grouping results by a parameter to organize random results

If the results of a report are random, this procedure helps you sort or reorder the data by a
parameter.
Using the parameters used in the previous example, this example sorts the results in the far left
column by Status.
To sort results by a parameter

1. With the report open in the Layout tab of the layout editor, go to the Data Explorer tab and
double-click a data set under the Data Sets node.
2. In the Edit Data Set dialog box, click the Sorting tab.
3. Click Add to open the Available Fields dialog box.
4. Select the fields you want to sort by in the report, and then click OK.
For example, select the Status and Assignee Groups fields.
5. Preview the report to make sure the report is sorted by the parameter you added to the
Sorting tab.
a. Save the report.
b. Run the report.
c. Close the report after reviewing its content.
6. If the report is not sorted as expected, review step 2 through step 4.
To group results by a parameter

1. Go to the Layout tab of the layout editor, select the Table icon of the table, right-click the
table header row, and select Insert Group.
2. In the New Group dialog box, in the Group On list, select the parameter with which you want
to group the results, and then click OK.
3. Preview the report to make sure the results are grouped by the parameter you configured in
the New Group box.
In the following figure, the report is grouped and sorted by the Status parameter. The first
Assigned row has no data, then the next Assigned rows contain records. Then the first In
Progress row has no data, then the following In Progress rows contain records.
Page 1175 of 4705
Home
Report sorted by a parameter

4. To apply a style to the group header, go back to the report file in the Layout tab, and
right-click the group header row.
5. Choose Style > Apply Style > bmcReportTheme:GroupHeader1 .
6. Preview the report (save, run, and close the report) to check the group header style.
To aggregate results by a parameter

You can configure your report results to display aggregated data. In other words, instead of
displaying simple values, you can perform calculations on sets of values.
This example shows you how to configure a report that counts the number of incidents.
1. In the Layout tab of the layout editor, select the Table icon, right-click a cell in a Table
Group-Header row, and choose Insert > Aggregation.
Inserting an aggregation
2. In the Aggregation Builder dialog box, configure a report row by doing the following tasks:
a. In the Function list, select COUNT.
b. In the Expression list, select Incident Number.
c. Click OK.
3. Preview the report (save, run, and close the report).
This report groups results by the parameter you configured in the New Group box in, and
displays the number of incidents in the Table Group Header row for incidents with Assigned
and In Progress.
Report displaying number of incidents and sorted by group
Adding a column to report results

This section explains how to add a column to filter report results.
Page 1176 of 4705
Home
To add a column
1. In the BIRT Report Designer, go to the Layout pane of a report.
2. Click a column above its table header to select the entire column in a table.
3. Right-click in the selected column and choose Insert > Column to the Right (or Left).
4. Go to Data Explorer tab and drag a data set into the new column (for example, Data
Explorer tab > Data Sets > HPD_Help_Desk > Incident Number ).
5. Add a label (for example, Incident Number) at the top of the column.
Adding a parameter to filter report results

This section explains how to use the BIRT Report Designer to create a parameter that you can use
to filter your report results. In this example, the License type field is added to the Parameter box
for reports that return People records.
To add a parameter
1. In the BIRT Report Designer, go to the Outline tab.
2. Right-click Report Parameters, and select New Parameter.
3. In the Name field, type a name for the new parameter.
4. In the Data type field, select String.
5. In the Display type field, select Combo Box.
6. In the List of value area, select Static, then click New.
7. In the New Selection Choice dialog box, type Fixed in the Value field, and click OK.
8. Click OK to close the New Parameter box.
9. To create binding between the data set and the new parameter, go to the Data Explorer tab,
right-click the appropriate data set, click Edit, click Parameters, and click New.
10. In the New Parameter box, configure the new parameter by doing the following tasks:
a. In the Name field, type the name of the new parameter in the data set.
Note
Select one of the following options because the Default Value field can be
edited only if you do not edit the Linked to Report Parameter field.
b. In the Linked To Report Parameter field, select the name of the new parameter you
created.
c. In the Default Value field, edit the qualification query of the data set based on the
report parameter that you linked to.
For example, enter the following in the Expression Builder:
'License Type' = [param:dsLicenseType]
Page 1177 of 4705
Home
where dsLicenseType is the data set parameter which refers to the report
parameter.
The Parameter box of the report appears and specifies a fixed License type parameter. The
report shows People records having a fixed License type.
Editing a Parameter box field to filter report results

You can edit an existing field in the Parameter box to narrow your report results.
When you run most out-of-the-box reports in BMC Remedy AR System or BMC Remedy IT Service
Management Suite, the Parameter box appears and requests information to narrow the report
results. For example, the Parameter box can request the Start Date and End Date for reports with a
date range.
Parameter box
(Click the images to expand it.)
To edit the Parameter box fields

1. Search for an out-of-the-box Web report that contains date-related fields that you want to
edit, and save its .rptdesign file to a folder where you store reports.
For details, see Modifying an out-of-the-box Web report with the BIRT Report Designer .
a. In the Report form, search for a report with the words Date and Range in its title by
entering % Date Range in the Report Name field.
b. Select a report.
For example, the Expiring Contracts by Date Range report.
2. In the BIRT Report Designer, choose File > Open File, and open the .rptdesign file you
exported from the Report form.
3. Go to the Data Explorer tab, click the Report Parameters node.
4. To edit a report parameter, right-click the report parameter you want to edit, and select Edit
from the submenu.
For example, if you want to edit the Start Date field, right-click Start Date.
For details on editing parameters, see the BIRT Report Designer online help.
5. If you want to see how a parameter is filtered for a data set, go to the Data Explorer tab,
right-click the data set you want to examine, click Edit, then click Filters.
For details on editing a filter condition, see the BIRT Report Designer online help.
Page 1178 of 4705
Home
Using subreports to link reports together

Subreports, which are reports that are linked and appear inside another report, can provide detailed
information about a customer beyond the data provided in a parent report. For example:
If a customer listing provides a customer ID, that customer ID can be input into a subreport
that displays details about each customer. An ID value is often the common data between
two data sets.
If a parent report displays only the amount spent (or other customer data), a subreport can
provide customer details (such as address). A subreport can show a combined parent report
and subreport.
Testing each subreport before building the next subreport can help minimize difficulties that can
arise with subreports.
The example in this section provides high-level instructions. Subreports are discussed in detail in
the BIRT Report Designer online help.
To create a subreport
1. Design the structure of a report and its subreports.
This includes details of required data sets and how they are related, and can be a simple
relationship diagram of forms.
2. Create a data source and a required number of data sets.
For an example, consider a parent "People" report that can have an added subreport, which
shows roles attached to a particular people record. The relationship structure is:
CTM:People (Person ID) > CTM:SupportGroupFuncRoleLookUp (Person ID)
This structure has two data sets that are required to develop the subreport. The two required
data sets are CTM:People and CTM:SupportGroupFuncRoleLookUp.
3. Create the required data sets as follows:
4. Create a data set for the parent record (CTM:People).
5. Create a data set for the child records (CTM:SupportGroupFuncRoleLookUp).
6. In the Parameter tab of data set creation for child record, create a parameter for the parent
key based on which will pull child records.
For example, the key will be Person ID. Do not link the parameter to any report parameter.
7. Click Query and modify the query as follows to pull child records having a key value the
same as parent record:
"Person ID" = [param:dsPersonID]
8. Insert a second table element inside the new detail row of table.
The child table must have the child record data set associated to it.
Second table element inside a table detail row
Page 1179 of 4705
8.
Home
9. Go to the Binding tab of the new child table.

10. Bind the key field of the parent data set to the parameter of the child data set parameter.
Binding tab of the child table
11. Click Data Set Parameter Binding.

12. Bind the parent key value to the child.
Data Set Parameter
Page 1180 of 4705
Home
Using dynamic drill down reports to provide a series of detailed reports

This section provides high-level information about dynamic drill down reports.
Note
Adding interactive features, such as hyperlinks, to charts is discussed in detail in the BIRT
Report Designer online help.
Drill down reports are summary reports which can be drilled through to get related detail data in
other reports at a granular level. The first report presented in a series of drill down reports provides
only required or necessary data, and then the user decides whether they want further details. By
adding hyperlinks, you make drill down reports interactive for your user.
For example, a report first might show only a pie chart, which summarizes the report results. When
a user clicks a slice of the pie chart, a detailed report opens for that particular slice of data.
The following scenarios looks at the report development of the All incidents by Status and
assigned Group drill down report in ITSM.
To create a drill down report
To create a drill down report that links to an incident record
To create a drill down report

This procedure provides high-level steps to create a drill down report. This procedure features the
example All incidents by Status and assigned Group report.
1.
Page 1181 of 4705
Home
1. Gather and analyze data to decide how to divide information into multiple stages.
For example, the example report has a high number of incidents based on their status. The
incidents have a particular status and are assigned to groups. There are also records for the
incidents. A particular record in an incident form can provide details of that incident.
Therefore, the design of this drill down report needs the following levels:
Drill down report design example
(Click the image to enlarge it.)
In this example:
A pie chart shows Incident Count categories based on Status
A bar chart shows the Incident Count by Assigned Group for the Status slice selected
in the pie chart
A detailed incident report based on the Assigned Group bar selected in the bar chart
2. Create a data source and data set required for a report (for example, HPD: Help Desk).
3. Insert a table in the report layout area.
4. Bind the data set property of the table.
5. Insert the required fields in the details section (for example, Incident Number, Assignee,
Customer Name, and so on).
6. Insert groups in the table by right-clicking in the detail row of the table and selecting Insert
Group.
Insert the first group based on Status, and the second group based on Assigned Group.
7. Insert a chart in the table by right-clicking in a table header and choosing Insert > Chart.
Insert a pie chart showing the number of Incidents categorized based on Incident Status.
Drill down report pie chart example
8. In the Status group header (header of first group) of the table, insert a bar chart that will
show the number of Incidents categorized based on Assigned Group.
Drill down report inserting a bar chart
9.
Page 1182 of 4705
Home
9. In the second group header, choose Insert > Grid to display details of Incident Count,
Assigned Group, and Status.
Drill down report inserting a grid
10. In the first group header, right-click and select Properties, select Bookmark in the Property
Editor, then enter the following in the Bookmark box:
row["Status"]
Bookmark box on Properties tab
11. To set the bookmark with a hyperlink to the pie chart

a. Right-click the pie chart created in step 7
b. Click the Format Chart tab.
c. From the nodes in the left panel, choose Series > Value Series.
d. Click Interactivity.
e. Click Add in the Series Interactivity dialog box.
12. In the Hyperlink Editor box, type the name of the hyperlink in the Name field, and then click
Edit base URL.
13. In the Hyperlink Options box, select Internal Bookmark, and then select the bookmark you
created.
This adds the functionality for clicking a particular slice of a pie chart, then navigating to a
bar chart that shows the incident count of a selected Status based on the Assigned Group.
14. Create a hyperlink for a bar chart by repeating the process from steps 10 through 13.
To create a drill down report that links to an incident record

This example shows how to enable a user with a list of incident records in a report to click on a
particular Incident Number to open the form (for example, HPD:Help Desk), which includes the
incident details. This allows the user to easily access and modify an incident record starting a report
.
1. To add a new report parameter, select Hidden in the New Parameter dialog box box, and
click OK.
This new parameter will be used in script to fetch the mid tier URL.
2. Select a data set.
In this example, select the HPD:Help Desk data set.
3. Go to the Script tab of the report, and select the BeforeOpen event in the Script list.
The script fetches the MidTier URL at runtime and sets it to the hidden parameter created in
step 1. The script is as follows:
Page 1183 of 4705
3.
Home
var request = reportContext.getHttpServletRequest();

var urlValue = null;
if (request != null) {
var session = request.getSession();
if (session != null) {
urlValue = session.getAttribute("midTierURL");
}
}
if (urlValue != null) {
params["midTierURL"].value = urlValue;
} else {
params["midTierURL"].value = null;
}
4. Go to Layout tab of the report, and select Incident Number, which was inserted in the table
details section in step 5.
5. Select the Hyperlink properties tab, and click Edit.
6. In the Hyperlink Options dialog box, select URL as the hyperlink type, and enter the
following value:
params["midTierURL"].value + row["Entry ID"]

choose Target = "Blank"
7. Save the report.

8. Preview the results by running the report on the mid tier and clicking an Incident Number.
The selected incident opens in the Help Desk form.
Converting a currency type with a computed column

You can convert a particular currency field to the type entered by your user by creating a Computed
Column in a data set.
The Open Data Access (ODA) framework in BIRT converts the Currency Field in BMC Remedy AR
System to the following fields:
<Field Name>.OBJECT
<Field Name>.VALUE
<Field Name>.TYPE
OBJECT is of type String and has currency value as well as currency type.
To convert a currency field to the user entered currency type

1. With a report open in the Layout tab of the layout editor, click the Data Explorer tab, and
double-click a data set under the Data Sets node.
2.
Page 1184 of 4705
Home
2. In the Edit Data Set dialog box, click Computed Columns.

3. Click New.
4. In the Column Name field, type a name for the computed column.
5. In the Data Type field, select Decimal.
6. In the Expression field, type the expression, for example:
if (row["Associated Cost.OBJECT"].toFunctionalValue(params["CurrencyType"].value)
7. Click OK, then click Preview Results.
Grouping results in multiple groups by using grids

This example show how to create a report that shows grouped results, with those grouped results
being further broken down into another level of groups.
The first report shown in step 13 of this example shows the results grouped by their Assigned
Group (for example, A SupGrp) and then grouped by their Status (for example, Assigned, In
Progress, and Pending).
The second report shown in step 20 shows a deeper level of grouping, with the results grouped by
their Assigned Group, then grouped by each Assignee within each Assigned Group, and then
grouped by their Status.
To add multiple groups by using grids

1. View the report in the Layout tab of the layout editor.
This report starts with the Assigned Groups field in the left column. You can merge table
group header cells and add a label to the left of the data set field as shown.
Viewing the report in the Layout tab
2. Save and run the report to preview it.

3. In the Layout pane, add a column for the Incident Number to the right of the Assignee
column.
Adding a second column
4. Add another column for the Submit Date to the right of the Incident Number column.
The report shows columns for the Assigned Groups, Incident Number, and Submit Date.
Report preview after adding two columns
Page 1185 of 4705
5.
Home
6. In the Layout pane, right-click in the Table Group Header row, and choose Insert Group >
Below.
7. In the New Group dialog box, select Status in the Group On list, then click OK.
The Status group is added to the table.
8. Right-click the Status group, and select a Group Header style for it.
Selecting a style for the Status group
9. Apply a style to the other group headers and other rows in the table.
10. For formatting, merge the Status table group header cells and add a label to the left of the
data set field.
Merging and labeling the Status table group header
11. Right-click in the Status group header row, and choose Insert > Grid.
12. In the Insert Grid dialog box, set the grid size as 2 columns and 1 row.
The report shows the results grouped by their Assigned Group (for example, A Test Support,
ABC Group) and then grouped by their Status (for example, Assigned and In Progress).
Report preview showing grouping by Assigned Group and then Status
To take the grouping to another level, this example adds the Assignee group within the
Assigned Group group.
14. Right-click in the Status table group header, and choose Insert Group > Above.
15. In the New Group dialog box, set the grid size as 2 columns and 1 row.
16. Select Assignee in the Group On list, then click OK.
The Assignee group is added to the table.
Assignee group added in Layout pane
Page 1186 of 4705
Home
17. For formatting, merge the Assigned table group header cells and add a label to the left of the
data set field.
Merging and labeling the Assigned table group header
18. Right-click in the Assigned group header row, and choose Insert > Grid.
19. In the Insert Grid dialog box, set the grid size as 2 columns and 1 row.
The report shows the results grouped by their Assigned Group (for example, A SupGrp),
then grouped by Assignee (for example, A1 User), and then grouped by their Status (for
example, Assigned and In Progress).
Report preview showing grouping by Assigned Group, then grouped by Assignee,
and then Status
Using a stacked bar chart to compare different series of results

This procedure provides high-level steps to create a stacked bar chart report. A stacked bar chart
compares the results for different sets of results. This example is for a stacked bar chart for all
assignees in an incident group. The details of creating a bar chart are provided in the BIRT online
help.
1. In BIRT Report Designer, create a basic new report.
For details, see the BIRT online help.
2. Configure the data set for the report by adding the Status, Assignee Groups, Assignee,
and Incident Number fields in the Query tab.
3. In the Layout pane, right-click in the report layout and choose Insert > Chart.
4. On the Select Chart Type tab of the New Chart dialog box, select Bar as the Chart type,
and Stacked Bar chart as the Subtype.
5. On the Select Datatab of the New Chart dialog box:
a. Select Use Data from, and select Data Set from the list.
Select Data tab for a stacked bar chart
Page 1187 of 4705
Home
b. Under In the Value (Y) Series, configure at least two series of data for Status using
the Expression Builder.
Optionally, configure the Aggregate Expression field to Count.
c. Under In the Value (X) Series, configure a series of data for Assignee Groups using
the Expression Builder.
If the bar chart needs adjustment, click the Binding tab in the Property Editor for the chart
and review the data binding settings.
Approving requests
The following topics provide information about how to approve requests:
Approval notification through email
Configuring the Request ID link on Approval Central
Setting previews for approval requests
Processing approval requests
Using the Get Agreement sample application
Approval notification through email

For every new approval request, an email notification is sent to the approvers of the request. This
email contains configurable details of the request, such as the Request ID, Description, and
Submitter. This email also contains the following links:
Approve - To approve a request.
Reject - To reject a request. You must add a justification for rejecting the request in the reply
email under the "Please provide justification, if required" line.
Hold - To keep the request on hold.
Go to Approval Central - To view the detailed information of the request, highlight the new
request, and open Approval Central. You can access Approval Central only if the mid tier is
accessible from the device on which the e-mail notification is opened. You must also provide
appropriate credentials after the link is opened.
Approve, Reject, and Hold create an appropriate reply email that contains details about the
request entry in the AP:Detail-Signature form. You can verify the information and send this reply
email to BMC Remedy Approval Server to complete the action. The reply email message contains
comments about what must be changed before sending the message.
Page 1188 of 4705
Home
Note
An email confirmation of the action taken is sent to the approver, regardless of

whether the action is completed successfully. The administrator must configure
additional notifications in BMC Remedy Approval Server.
You do not need to manually enter any password or security key.
To configure your handheld devices to send approvals through email, the email
client on the handheld device must use the POP3 or MAPI protocol.
You must perform the following tasks to define an approval notification:

Configuring AR System server and email
Customizing the template
Defining notifications
The following examples illustrate this process.
Joe, the sales department manager, received an email notification in Microsoft Outlook on
his laptop. The request was from one of his sales representatives for a new Blackberry
phone. The message contained the standard options: Approve, Reject, Hold, and Go to
Approval Central. Because the sales representative had talked to Joe about this request,
Joe was fully aware of all the details. After verifying the price of the Blackberry phone, Joe
clicked Approve, and a reply email was created. Joe clicked Send to send the reply email to
BMC Remedy Approval Server. The following actions then took place:
Upon receiving the reply from Joe, BMC Remedy Email Engine parsed it, located the
approval signature record, and updated the record with the Approved action.
The workflow set the How Signed field on the signature line to Email.
If BMC Remedy Approval Server had been customized to do so, it sent an email
message back to Joe, informing him that the request was successfully approved.
If there are more approvers configured, BMC Remedy Approval Server sent an email
notification to the next approver in the approval chain.
If BMC Remedy Approval Server had been customized to do so, it sent an email
message back to the requestor, the sales representative, informing him that his
request was successfully approved. If not configured, the requestor can track the
request through Approval Central.
Sandy, the Finance Manager, received an email notification with the standard options in her
email inbox, asking her approval for a Blackberry phone for one of the sales representatives.
Sandy needed more information about this request, so she clicked Go to Approval Central.
In Approval Central, she reviewed the request details and approved the request.
Configuring AR System server and email

Follow the given procedures to configure AR System server and Email engine.
Page 1189 of 4705
Home
To configure the AR System server

1. Log on to a browser as an BMC Remedy AR System administrator.
2. Open the BMC Remedy AR System Administration Console, and select System > General
> Server Information.
3. In the Server Information window, click the Advanced tab and, if it is not already set, set the
Default Web Path field to the mid-tier web path URL (for example, http://<midTierServer>:
<portNumber>/arsys).
To configure email
Follow the steps in the Configuring BMC Remedy Email Engine for modify actions section.
Important
Set the Use Security Key field value to No instead of Yes in step 7 of that section.
Customizing the template
Note
The customization of the templates is optional. However, BMC recommends that you
customize the templates as per your requirements.
1. Log on to a browser as BMC Remedy AR System administrator.

2. Go to the BMC Remedy AR System Administration Console and click System > Email >
Email Templates.
3. Go to the AR System Email Templates form and edit the following HTML attachment files
present in the Template Attachment tab in a text file editor:
as_email_notification_template.html
as_email_notification_template_nc.html
Note
Do not change the template names or any other field values on the AR
System Email Templates form.
a. In the Configurable Section, add the fields that are required by the approver to take
the appropriate action for the approval requests from the application's three-way join
form.
Page 1190 of 4705
a.
Home
Important
Make sure that the fields that you are adding have appropriate permissions.
b. Save these template files.
Note
BMC recommends that the Encoding value must be set to UTF-8, while
saving the file.
4. In the table, right-click the Template attachment row and click Delete to remove the old file.
5. Right-click the Template attachment row and click Add.
6. In the Add Attachment window, select the template saved in step 3 and click OK.
7. Click Save to save the form.
Defining notifications
1. Log on to a browser as a process administrator or a BMC Remedy AR System administrator
and open the AP:Administration form in Search mode.
2. Click the Notification tab, and click Create.
The AP:Notification form opens in New mode, with the Basic tab selected.
3. Enter the following values in the Basic tab:
a. In the Notification Name field, type a name for the notification.
b. In the Process Name list, select the appropriate process.
The process must already exist. See Creating a process.
c. In the Status field, set the notification to Active.
d. In the Notify On field, select New Signature.
e. In the Qualification area, enter a condition statement to help control whether the
notification runs, if necessary.
The Additional Conditions field enables you to add conditions to the setting in the
Notify On field.
4. Click the Details tab and enter the following values:
a. In the Method list, select one of the notification option as Email.
b. Select a Priority for the notification from 0 to 10.
c. Select Notify List for the Send To field, which indicates where to send the notification
.
d. Enter a Subject line for the notification message.
e. To include field values in the subject line, use the Subject drop-down list.
The Subject panel lists fields from the application's three-way join form. Select the
field whose value you want to include in the subject line, and click OK.
f.
Page 1191 of 4705
Home
f. To attach more field information to the notification, use the Additional Fields field.
Enter the following required fields in the text box:
Request-ID
Detail-Sig-ID
Application
Also add the fields from the Configurable Section of the saved HTML
templates. For more information, see step 3 in Customizing the template.
g. To include field values in the message text, use the Message drop-down list.
5. Click the Email tab and enter the following values:
a. Select Yes as a value for the Use Email based Approval template field.
The appropriate template name appears in the Content field.
The other fields in the Email tab are the same as those used when you create an
Email or User Default notify mechanism in a Notify filter action.
The menus in the Fields columns on this tab contain fields from the three-way join
form. You can select from the Fields and Keywords menus to use variables in all the
fields on this tab.
b. In the Mailbox Name field, enter the name of an outgoing mailbox that is configured
in the AR System Email Mailbox Configuration form. This field is not required if you
use the default outgoing mailbox.
You can use a field or a keyword to get the mailbox name. The mailbox name must
correspond to an outgoing mailbox configured in the AR System Email Mailbox
Configuration form.
c. Enter the appropriate information in the From and Reply To fields.
Note
Make sure you use the same name for the From and Reply To fields.
BMC Remedy Email Engine uses these fields as follows:

From - Indicates the sender; should match the email address of the
corresponding incoming mailbox.
Reply To - Specifies the reply-to address if the recipient replies to the
notification message.
Note
If you set the CC and BCC fields while sending the notification, BMC
Remedy Email Engine displays an error, because the security key is
disabled and more that one recipients are mentioned.
d.
Page 1192 of 4705
Home
d. In the Organization field, enter a company name, an organization, a keyword, or a

field reference to an organization name.
This name appears in the Organization tag of the email header.
e. In the Header, Content, and Footer fields specify the names of the email templates
to use for the header, content, and footer of the email notification.
6. (Optional) Click the Administrative Information tab and enter Help Text that describes this
notification.
7. Click Save.
Configuring the Request ID link on Approval Central

Application administrators can configure the Request ID link on Approval Central to open one of the
following:
Application request form for the current request
Approval server three-way join form for the current request
A custom form
To configure the Request ID link

1. Log on to an AR System server, and click the Approval Administration Console link on the
home page.
2. On the Administration form, click the Form tab.
3. Perform one of the following to open the AP:Form form.
a. Click Create on the AP:Form, select the approval request form for your application
from the Form Name list.
b. Select a record from the table and click View to modify configurations for an existing
request form.
4. On the Basic tab of the AP:Form form, select one of the following options to configure the
Request ID link on Approval Central:
Application Request Form To open the application form for the current request
Approval - Application 3-Way Join Form To open the three-way join form between
the approval server and the application for the current request
Customize To open a custom form
a. On the AP:Customize-SourceID dialog box, specify the following values:
Display mode in which to open the form
Custom form to be opened
Form view to be displayed
Lookup field or the field mappings (depending on the selected Display mode)
b. Click OK.
For more information, see AP-Customize-SourceID form.
5. Select a view for the selected form.
If you do not select a view, the form opens in the default view.
6. Save the AP:Form form.
Page 1193 of 4705
Home
Setting previews for approval requests

The AP:PreviewInfo form allows requesters and approvers to get a list of the completed and
remaining approvals for any request. This is referred to as previewing approvals.
To allow users to preview approval responses, you must perform the following configuration actions
:
Configure the BMC Remedy AR System server and the BMC Remedy Approval Server to
use a Plug-in Loopback RPC socket. See Configuring server settings for BMC Remedy
Approval Server logging and loopback calls.
Configure the approval process to generate a preview at the required time. See Creating a
process.
Design a form that queries the AP:PreviewInfo form. See Adding previews to your approval
application.
Create workflow that uses the Add-PGNA-Values command to gather signatures. See
Defining Parameterized Get Next Approver rules .
Processing approval requests

Approval Central is the primary console for the users of BMC Remedy Approval Server.
The following topics provide information about how approvers use Approval Central to process
approval requests, how approvers and process administrators specify alternate approvers, and how
process administrators carry out approval overrides:
Overview of Approval Central
Working with pending approval requests
Processing More Information requests
Using alternate approvers
Performing overrides
Overview of Approval Central

Approval Central is designed for process administrators and approvers, and is used to perform the
following activities:
Searching for approval requests by specifying certain criteria
Viewing approval request details
Approving or rejecting requests
Putting requests on hold
Defining alternate approvers
Reassigning a request to another approver
Creating or responding to More Information requests
Page 1194 of 4705
Home
Process administrators use Approval Central to override approvers when necessary. Approvers
also use Approval Central when acting as alternates for other approvers.
Approval Central as seen by the sample user Jack Miller
For more information, see Approval Central.
Working with pending approval requests

The following topics provide information about how to search for specific approval requests, and
provide procedures for managing and responding to approval requests:
Processing an approval request
Performing a search on Approval Central
Approving and rejecting requests from Approval Central
Rejection justification for approval requests
Working with request details
The examples in this section are from the Get Agreement and Lunch Scheduler sample
applications, which are installed with BMC Remedy Approval Server. For more information about
the sample applications, see Using the Get Agreement sample application and Using the Lunch
Scheduler sample application.
Processing an approval request

Approvals typically follow this sequence:
1. Someone submits a request that requires your approval.
2. You receive notification of the approval request.
3. You review the approval request and take one of the following actions:
If the approval request appears to be in order, you can approve it.
If you need more information, you can enter a question or comment for the BMC
Remedy Approval Server to route to the requester or other individual (a More
Information request).
Page 1195 of 4705
Home
If the request appears unacceptable, you can reject it. Rejection usually ends the
process for this request, unless rules are in place that require further processing. See
Get Authority rules, Signature Accumulator rules, and Statistical Override rules.
If you are not the appropriate person to approve the request, you can reassign it.
Performing a search on Approval Central

When you open Approval Central, a query with the following search criteria is executed
automatically:
Acting As = MySelf
User = yourARSystemUserID
Approval Status = Pending or Approval Status = More Information or Approval Status
= Hold
Using this query, BMC Remedy AR System searches for requests that are awaiting your action. If
any requests are found, they appear in the Pending Approvals table.
The Summary section provides more predefined searches.
You can also use the Quick Search and Advanced Search functionality on Approval Central.
Specify your search criteria in this section, and click the Search icon to display a set of requests in
the Approval Search Result table.
For example, you can retrieve a list of only those requests pertaining to a particular application,
requests made by a specific requester, requests that are already approved or rejected, or requests
directed to another approver for whom you are designated as an alternate. For more information,
see Approval Search.
The following procedure is an example of how to retrieve a list of requests that pertain to a
particular application.
To see all requests in the AP-Sample2:Get Agreement application

1. Open Approval Central using one of the methods described in Opening Approval Central.
2. In the right pane, click Advanced Search to open the Approval Search section.
3. Select AP-Sample2:Get Agreement in the Application field, and select ( clear) in the Status
field.
4. Leave the default values in the remaining fields, and click Search.
The Approval Search Result table then displays all requests that belong to the
AP-Sample2:Get Agreement sample application for the current user.
For information about adding an application to the Application field, see Integrating
Approval Server with an application.
Page 1196 of 4705
Home
Approving and rejecting requests from Approval Central

Approval Central contains Approve Selected, Reject Selected, and Hold Selected buttons that
allow you to act on multiple approval requests without opening them individually. You can also use
the row-level icons for acting on individual requests.
To act on multiple requests

2. In the Pending Approvals table, use the check boxes to select the pending requests that
you want to act upon.
3. Click Approve Selected, Reject Selected, or Hold Selected.
If the related approval processes require approvers to enter a password, the AP:Password
dialog box appears. If necessary, enter your password when prompted, and click Submit.
Note
When you click Approve Selected, Reject Selected, or Hold Selected, the status
of the selected requests changes. These modified requests continue to appear in
the Pending Approvals table until the table is refreshed, or until you navigate to
another page or link. No undo option exists when you respond to a request so there
is no opportunity to change your mind.
For more information, see Action buttons.

If you provide an incorrect password, the following error message is displayed:
Authentication failed. Please enter your valid AR System password. (
ARERR 45490)
No action is performed on the selected requests.
To act on single requests

2. In the Pending Approvals table, select the pending request that you want to act upon.
3. Click Approve, Reject, Hold, Reassign, Approval Details, or View Questions and
Responses.
For more information about the various icons, see Working with pending approval requests.
Rejection justification for approval requests

On Approval Central or the AP:Show-Detail form, approvers can provide a justification for rejecting
a request by entering some meaningful text in the Justification For Action field and clicking
Reject.
Page 1197 of 4705
Home
The justification is stored as a note in the Approval Activity Log, and sent to:
AP:Question-Comment-Info as a comment of the Justification type
AP:Signature, from where the application can access it
A field on the application form, if and as defined in the process
Currently, this feature is associated only with the Reject action. If an approver enters a justification
and clicks any other action button, the request status changes as appropriate, but the text is not
stored at any location.
The mandate for providing a justification is configurable at the process level. Process
administrators can use the Rejection Justification area on the Configuration tab of the AP:
Process Definition form to specify:
whether an approver must provide a justification when rejecting a request
the field on the application form in which the justification is stored
If justification is required, but the approver does not enter any text in the Justification For Action
field on Approval Central before clicking Reject, the AP:Rejection Justification dialog box appears.
The following events could occur:
If the approver clicks Cancel, the following message is displayed:
Cancelling the action, because the justification required by the
current process was not provided. ARWARN 46408)
The Reject action is cancelled, the request remains in the Pending state, and no log entry is
created.
If the approver clicks OK without entering some text in the Justification field, the following
message is displayed:
Please enter appropriate rejection justification. (ARNOTE 46409)
If the approver provides some text and clicks OK, the request is rejected. The text is saved
in AP:Question-Comment-Info as a comment of the Justification type. The justification also
appears in the Activity Log.
Applications can also enable approvers to provide rejection justification on the three-way join form.
To make this possible, application developers must:
Add a Character field of unrestricted length (to accept more than 255 characters) on the
three-way join form for an approver to enter the comment.
Provide the workflow to push the comment onto the AP:Signature form after the approver
clicks Reject.
If the process mandates a rejection justification, and the approver sets Approval Status to Rejected
and saves the request without providing a justification, the Reject action fails. The following error is
written to the approval log:
Page 1198 of 4705
Home
The processName process requires a rejection justification, which the approver failed to provide.
See Creating the join forms and Approval forms.
For general information about join forms, see Join forms.
Working with request details

The Approval Details icon on Approval Central opens the AP:Show-Detail form, which enables
you to see more details about a request. You can also approve, reject, or hold an approval request,
add ad hoc approvers, reassign a request to another approver, and create or respond to More
Information requests using this form.
On Approval Central, the Request ID link that appears in the Request Details section for a request
opens the relevant application form. Click the Show Signatures button on the application form (if
implemented) to open the three-way join form associated with the application request. This
document also refers to this view as the "detail view." The following procedures use this detail view
to perform various actions on an approval request.
Setting the Approval Status in the detail view

After viewing the details of an approval request, you can approve or reject the request by changing
the Approval Status in the detail view.
To approve an approval request by changing the Approval Status field

1. Open Approval Central by using one of the methods described in Opening Approval Central.
2. In the Pending Approvals table, select the pending request you want to work with, and click
its link in the Request Details section.
The appropriate request form opens (for example, AP-Sample2:Get Agreement).
3. Click the Show Signatures button.
The appropriate three-way join form opens (for example, AP-Sample2:Issue Detail Signal).
Setting the Approval Status field
4. Click the drop-down arrow on the Approval Status field, and select Approve.
To ask for more information about the request, see Processing More Information requests.
5.
Page 1199 of 4705
Home
5. If the Password field is present, enter your password. Otherwise, proceed to the next step.
If a password is required and you do not enter your password, or if you enter the wrong
password, the product returns the following error message:
Authentication failed. Please enter your valid AR System password. (
ARERR 45490)
Note
The BMC Remedy AR System administrator must configure the Password field to
appear on the three-way join form when it is required. See Displaying the password
field in the detail view.
6. Click Save.
You can use the same procedure to reject or hold a request by setting the Approval Status
to Rejected or Hold.
For information about how to configure an approval process to require a password, see
Creating a process.
When you return to Approval Central and refresh the search, this request is removed from
the table of pending requests.
Warning
After you respond to a request, you cannot undo or change your response.
Specifying additional approvers

Perform the following procedure if you must specify the next approver instead of automatically
routing the request. With some processes, such as an Ad Hoc process, approvers can or must
specify additional approvers. The process administrator can also configure Parent-Child, Level, and
Rule-Based processes to allow users to add the next approver with the Allow Ad Hoc Next
Approver field. See Creating a process.
You must specify the additional approvers before or at the same time as you approve or reject the
approval request. After you have approved or rejected the request, you no longer have access to
the Next Approvers field.
Note
If the approval process includes rules that specify the next approver, the process rules
supersede any changes you make in the detail-signature view.
Page 1200 of 4705
Home
Specifying the next approver is not the same as reassigning an approval request. The option to
specify the next approver also requires you to approve or reject the request. For information about
reassigning requests, see Reassigning approval requests.
To specify next approvers

The relevant request form appears.
3. Click the Show Signatures button.
The appropriate three-way join form is displayed.
Adding multiple approvers
4. In the Next Approver field, enter the names of the next approvers.
You must enter one or more BMC Remedy AR System login IDs. To specify multiple
approvers, separate each name with a semicolon (;) .
5. If you specify multiple approvers, determine the appropriate option for the If Multiple
Approvers field.
One Must Sign A single signature entry is created for all approvers. Only one of
those approvers needs to take action.
All Must Sign Separate signature entries are created for all approvers. Each
approver must take action for the request to proceed further.
Note
In an Ad Hoc approval process, if you do not complete the If Multiple
Approvers field, BMC Remedy AR System requires all additional approvers
to sign the request.
6. In the Approval Status field, select Approved.
7.
Page 1201 of 4705
Home
7. Click Save. The Adding multiple approvers figure above illustrates an example of this
procedure. In this example, the approver Jack Miller has approved the request, added two
additional approvers, and specified that both must approve the request separately.
Reassigning approval requests

To reassign an approval request to a different approver, perform the following procedure. The
Reassign To field appears when the process allows you to reassign approval requests.
To reassign an approval request

3. In the request form, Click the Show Signatures button.
4. In the Reassign To field on the three-way join form, enter the name of the approver to whom
you want to reassign the request.
You can enter only one person's BMC Remedy AR System login ID.
5. Click Save.
BMC Remedy Approval Server routes the request to the reassigned approver.
Processing More Information requests

If you need more information before approving or rejecting an approval request, you can send a
More Information request, which is an independently-routed BMC Remedy AR System record. BMC
Remedy Approval Server uses the AP:More Information form to manage More Information requests
.
When you create a More Information request, BMC Remedy Approval Server links it to the original
approval request and changes the status of the approval request to More Information. Thus, others
can see that the request is paused until the More Information request is answered.
Your response to the original approval is independent from the More Information request's routing.
In other words, you do not have to wait for the More Information response before approving or
rejecting the approval request. However, if you do approve or reject the original approval request,
BMC Remedy Approval Server immediately closes any related outstanding More Information
requests.
The procedures in the following topics describe the basic steps for requesting more information and
responding to More Information requests:
Requesting more information about approval requests
Viewing and responding to More Information requests
Viewing pending More Information requests and responses
Viewing all the More Information requests you submitted
Page 1202 of 4705
Home
The Questions and Comments features that make it easier to work with More Information Requests
. For more information, see AP-Show-Detail form.
Requesting more information about approval requests

Use the following procedure to request more information before approving a request.
To request more information about approval requests

3. On the application request form that appears, click the Show Signatures button.
4. On the relevant detail form that appears, click Manage More Information.
Note
The Manage More Information control is not provided out-of-the-box with BMC
Remedy Approval Server; it is only included in the sample applications. To use this
control with a customized application, you must add it to the relevant three-way join
form.
5. On the AP:Dtl-Sig-MoreInfoDialog form, click New Record to create a More Information

request.
6. On the AP:More Information form, specify values in the various fields as follows:
a. In the To field, enter the name of the person from whom you want more information.
This can be the original requester or any other person, but it must be that person's
exact BMC Remedy AR System login ID.
b. In the Question field, enter a description of the information you need.
Creating a More Information request
c. Click Save.
The More Information form closes, and the pending More Information request appears
temporarily in the More Information Requests table on the AP:Dtl-Sig-MoreInfoDialog
form.
d. Click Close.
Page 1203 of 4705
Home
BMC Remedy AR System forwards the request to the person from whom you requested more
information. The original approval request is updated with More Information status and is retained
in the list of pending approval requests until the recipient has responded to the More Information
request. However, the approver can approve or reject the request even though the request is in
More Information state.

Use the following procedure to display and respond to the More Information requests directed to
you for your approval.
To view and respond to More Information requests to you

By default, the Pending Approvals table displays requests with the Pending, Hold, and
More Information, status.
2. To view requests with the More Information status only, in the Summary section, click
Needs Attention.
3. The Needs Attention Approvals table displays the list of More Information requests that are
awaiting your attention; select a request to view its details.
4. In the Request Details section, click Response.
The AP:More Information form opens in Modify mode, and More Information requests
directed to you are listed in the results table included on the form.
5. Select the request you want to respond to from the results list.
The details area of the form changes to show details of the selected More Information
request.
6. Type your answer in the Response field, and click Save.
The status of the More Information request automatically changes to Completed. The
request no longer appears in the More Information Requests table after the search is
refreshed. BMC Remedy Approval Server routes the response back to the More Information
requester.
Note
By default, the Public group does not have change permission to the Response
field of the AP:More Information form. The BMC Remedy AR System administrator
must set the correct permissions on this field to allow the appropriate groups to
respond to More Information requests.

Page 1204 of 4705
Home
Viewing pending More Information requests and responses

When you submit a More Information request, the status of the related approval request changes to
More Information. When the recipient responds to the More Information request, the status of the
related approval request changes back to Pending.
To view a More Information response

2. Select the appropriate request from the Pending Approvals table, and click Approval
Details.
3. On the AP:Show-Detail form, open the Activity Log tab.
4. Click the row pertaining to your Question or Comment.
The response is visible in the appropriate field of the Activity Log Details section.
You can access More Information requests that you have submitted by finding the related
approval request in Approval Central, and clicking Manage More Information in the details
view to access the related More Information request.
Note
The Manage More Information control is not provided out-of-the-box with BMC
Remedy Approval Server; it is only included in the sample applications. To use this
control with a customized application, you must add it to the relevant three-way join
form.
To view a pending More Information request

By default, the Pending Approvals table displays a predefined number of requests,
including those in the Pending, More Information, and Hold states.
2. To view More Information requests only, click the Needs Attention link in the Summary
panel.
This action also displays only a predefined number of requests at a time.
3. To view the complete list of More Information requests awaiting your attention, select More
Information in the Status field in the Quick search section. The Approval Search Result
table displays the requests for which the status is More Information.
4. In the Approval Search Result table, select a request and click Approval Details.
5.
Page 1205 of 4705
Home

6. Click the row pertaining to your Question or Comment.
The Activity Log Details section displays the corresponding details.
Viewing all the More Information requests you submitted

You can search the AP:More Information form to find and view all the More Information requests
that you have sent, regardless of the request status.
To retrieve all your More Information requests

1. In a browser, open the AP:More Information form.
2. Enter your BMC Remedy AR System user name in the From field, and click Search.
A list of the More Information requests you have sent appears in the results list area. This
includes both pending and completed More Information requests.
3. Select a request from the results list.
The details of the request appear in the details area of the window.
Displaying the More Information requests that you have sent
Using alternate approvers

Alternate approvers are approvers who serve in your place if you are unavailable. You can
designate your own alternates, or the process administrator can designate them for you. You can
also serve as an alternate for another approver.
The following topics provide information about how to use alternate approvers:
Designating alternate approvers for yourself or other approvers
Viewing and modifying alternate approver definitions
Viewing requests for which you are an alternate approver
Page 1206 of 4705
Home
Designating alternate approvers for yourself or other approvers

You can designate one person to act as an alternate for all approval processes, or you can specify
separate alternates for each approval process. You can also specify the time period for which the
alternate can grant approvals for each process.
If you want multiple alternates, repeat this procedure for each alternate.
Designating an alternate approver
Designating alternate approvers for yourself

Use the procedure in this section to designate an alternate approver for yourself.
Note
If your alternate designates an alternate, authority to sign your approvals is not passed on.
Only the specific person you designate can act as your alternate.
To designate alternate approvers

2. In the Actions section, click My Alternate Approvers.
The AP:Alternate form opens in New mode.
3. In the Alternate field, enter the BMC Remedy AR System login name of the person to
designate as your alternate.
4. Use the Start Date and End Date fields to specify the time frame in which you want the
alternate to act on your behalf.
5. In the Coveringfield, select either of the following options:
All To authorize the alternate to approve all processes for which you have
signature authority.
Specific To authorize the alternate to approve a specific process. Then select a
process from the Process list.
6. In the Notify Alternate field, select Yes to send notifications to the alternate for each new
approval, or No to prevent notifications to the alternate.
7. Click Save.
Page 1207 of 4705
7.
Home
Note
A time lapse of up to 60 minutes past the defined End Date might occur before an
alternate loses the alternate privileges. For performance reasons, this interval is set
to 60 minutes in BMC Remedy Approval Server.
Designating alternates for other approvers

Process administrators can designate alternates for other approvers within any process for which
the process administrator has Full Admin authority.
To define alternates for other approvers

1. Open the AP:Alternate form in New mode.
2. Create an alternate as described in the previous procedure.
3. In the For field, replace your user name with the BMC Remedy AR System user name of the
person this alternate will be substituting for.
4. Click Save.
Viewing and modifying alternate approver definitions

Use the procedures in this section to view or modify existing information about an alternate
approver.
To view and modify the record for an alternate approver

2. In the Actions section, click My Alternate Approvers.
The AP:Alternate form opens in New mode.
3. Click New Search to change to Search mode, and click Search.
The results list appears, containing a list of your past, current, and cancelled alternates.
4. To see details, select the record you want to view; the record details appear in the details
pane.
5. Modify the fields you want to change.
6. If you want to cancel this approver, select Cancelled from the Status field.
7. Click Save to save your changes, or Close to close the record without any changes.
Note
Your administrator might need to modify the permissions on the fields in the AP:
Alternate form to allow submitters to make changes to requests in the form.
Page 1208 of 4705
Home
Viewing requests for which you are an alternate approver

If you are acting as an alternate approver, you have the same signature authority as the approver
for whom you are serving. Your authority as an alternate approver exists for a specific time period,
and for the designated approval processes.
By default, Approval Central displays requests assigned to other approvers for whom you are
designated as an alternate approver. You can identify such requests by looking at the Acting As
column in the Approval Requests table. The requests for which there is no value in the Acting As
column, are directly assigned to you.
Approval Central displays only a predefined number of requests at a time. To view all requests on
which you can act as an alternate approver, perform a search as described in the following
procedure.
To view all requests for which you are an alternate approver

2. In the Actions section, click Search My Approvals.
3. In the Approval Search section:
a. In the Acting As field, select Alternate.
b. In the User field, type the BMC Remedy AR System user name of the person for
whom you are acting as the alternate.
c. In the Application field, select the appropriate application if necessary.
d. In the Process field, select the appropriate process if necessary.
e. Verify that the Status field is set to Pending.
f. Click Search.
The resulting requests are those on which you can act as an alternate approver, not
those that are directly assigned to you.
Performing overrides
The override capability of BMC Remedy Approval Server allows a process administrator to move an
approval process forward when the normal approver has not responded. An override is useful in an
unexpected situation, such as when the normal approver is unavailable but did not designate an
alternate.
A single-signature override closes one approver signature, similar to acting as an alternate
approver for one signature line, and allows the approval request to continue within the regular
process. In this case, an override rejection terminates the request just as if the original approver
had rejected it. An override approval moves the request forward just as if the original approver had
approved it. If more approvers exist, the request is routed to them.
Page 1209 of 4705
Home
A global override closes all open signatures, stops routing the request, and terminates the approval
process for that request. The global override is useful for unusual situations, such as ending an
approval process for a request that is no longer necessary.
The following topics provide information about how to perform an override:
Performing an override to a single signature
Performing a global override
A process administrator can assign override-only authority to any user without granting other
approval process administrator privileges. For more information, see Configuring process
administrator capabilities.
Performing an override to a single signature

If you have override capability for an approval process, you perform the same steps to approve or
reject the request as the original approver. However, you must specify that you are performing an
override.
To perform an override to a single signature

1. Log on to the product as the process administrator for the process you need to override (
such as the process administrator or BMC Remedy AR System administrator).
4. In the Approval Searchsection:
In the Acting As field, select Override.
In the User field, enter the BMC Remedy AR System user name of the user whose
pending approvals you want to access.
In the Application field, select the appropriate application if necessary.
Click Search.
The Approval Search Result table displays all pending requests for the specified
user. You can now approve or reject these requests with override authority.
Performing a global override

If you have global override capability, you perform the same steps to approve or reject the request
as the original approver. However, you must specify that you are performing a global override.
To perform global overrides

1. Log on to BMC Remedy AR System as the process administrator for the process you need
to override (such as the process administrator or BMC Remedy AR System administrator).
4. In the Approval Searchsection:
a. In the Acting As field, select Global Override.
b.
Page 1210 of 4705
4.
Home
b. In the Application field, select the appropriate application if necessary.

c. Click Search.
The Approval Search Result table displays all pending requests for the application
selected. You can now approve or reject these requests with override authority.
Using the Get Agreement sample application

This section demonstrates how to perform basic approval functions by using Get Agreement, one of
the sample applications bundled with BMC Remedy Approval Server. The Get Agreement
application demonstrates how requesters and approvers work with approval and More Information
requests in an Ad Hoc approval process.
The following topics provide information about the Get Agreement sample agreement:
Overview of the Get Agreement application
Accessing Approval Central
Creating new approval requests
Approving approval requests
Requesting more information
Working with Approval Status and More Information requests
Responding to and viewing responses to More Information requests
Checking status of requests
Overview of the Get Agreement application

If you installed BMC Remedy Approval Server sample applications, you can use them to
understand and test the approval server functionality. The Get Agreement sample application
demonstrates an Ad Hoc process, in which the requesters and approvers choose who should
approve the request. For more information about the Ad Hoc process type, see Ad Hoc process.
The procedures in this section use a set of sample users: Frank Williams, Jack Miller, Larry
Goldstein, Violet Anderson, and Sue Smith. To follow the sample application procedures using
these names, the BMC Remedy AR System administrator must create the BMC Remedy AR
System user names, and they must be issued either floating or fixed write licenses. Because this is
an Ad Hoc process, you can also substitute licensed user names that already exist on your system
when you try these procedures.
In the sample procedures, Frank Williams (the requester) requests a new computer. The approvers
use Approval Central to approve or reject the approval request, and to reassign an approval
request to another approver. The sample users also send and respond to More Information
requests.
The sample application demonstrates the use of Approval Central, an application request form (in
Page 1211 of 4705
Home
this case, AP-Sample2:Get Agreement), and related forms, such as the three-way join form (
AP-Sample2:Issue Detail Signat) and AP:More Information forms. It also demonstrates how to
display the status of an approval request and how to identify the actions taken by each approver.
Note
The Questions, Comments with attachments, Notes, and Multi-process preview features
are available out-of-the-box with this sample application. For more information, see
AP-Show-Detail form.
Accessing Approval Central

Most of the procedures in this section require that you start by opening Approval Central. To do so,
use the Approval Central link on the BMC Remedy AR System Home Page, or open the Approval
Central form in a browser.
For more information, see Opening Approval Central.
Creating new approval requests

In this section, use the sample application to start the approval process by creating a new approval
request.
1. Log on to the appropriate BMC Remedy AR System server as the sample user Frank
Williams.
2. In a browser, open AP-Sample2:Get Agreement in New mode using the URL:
http://<hostName>/arsys/forms/<serverName>/AP-Sample2:Get Agreement
hostName is the name of the web server where BMC Remedy Mid Tier is running, and
serverName is the name of the BMC Remedy AR System server where BMC Remedy
Approval Server is running.
Note
In this sample application, the Get Agreement form is the application request form.
The Get Agreement form in New mode

Page 1212 of 4705
Home
3. Type I need a new computer in the Summary field.

4. (optional) Type a longer description in the Details field.
5. In the Initial Approvers field, type
Jack Miller; Violet Anderson
Since this is an Ad Hoc process, you must enter at least one approver. To enter multiple
approvers, separate the names with semicolons.
6. Click Save to save the request and begin the approval process.
Approving approval requests

This section demonstrates how an approver responds to a request.
Before you begin

Before approving a request, you must follow the Creating new approval requests procedure.
To approve an approval request

1. Log on to BMC Remedy AR System as the sample user Jack Miller and open Approval
Central.
By default, the Pending Approvals table shows requests with the Pending, Hold, or More
Information status for the current user. Because Jack Miller was included in the list of
approvers, the "I need a new computer" request appears in the table.
2. In the Pending Approvals table, select the appropriate request.
3. Click the Approve icon.
Even after approving, Frank's request continues to appear in the list of pending approvals for
Jack Miller until the table is refreshed, or until you navigate to another page or link.

This section shows how an approver can transfer an approval request to another approver without
otherwise responding to the request.
Before you begin

Before approving a request, you must follow the Creating new approval requests procedure.
Note
Page 1213 of 4705
Home
The process specifies whether or not a request can be reassigned.
To reassign an approval request

1. Log on to BMC Remedy AR System as the sample user Violet Anderson, and open Approval
Central.
2. From the Pending Approvals table, select the I need a new computer request, and click the
Reassign icon.
3. If prompted, enter your BMC Remedy AR System password.
4. In the AP:Reassign dialog box, type Sue Smith, and click OK.
The reassigned request disappears from the Approval Requests table.
Requesting more information

This section demonstrates how to seek more information about approval requests.
Before you begin

Before approving a request, you must:
Follow the Creating new approval requests procedure.
Follow the Approving approval requests procedure.
To request more information about an approval request, you can create a separate More
Information request. The AP:More Information stores the More Information request, and allows
approvers to ask questions and have them answered before acting on an approval request.
To create a More Information request

1. Log on to BMC Remedy AR System as the sample user Larry Goldstein and open Approval
Central.
2. Select the I need a new computer request from the Approval Requests table, and click the
Approval Details icon.
3. On the AP:Show-Detail form, open the Activity Log tab and click Add.
4. In the Activity Log Details panel, perform the following steps:
a. In the Type field, select Question.
b. In the Question To field, specify the login name of the person from whom you need
more information.
c. In the Question field, enter appropriate text.
d. Click Save.
An entry is added to the Activity Log table.
5. Click Close.
Page 1214 of 4705
Home
Working with Approval Status and More Information requests

After you send a More Information request, the Approval Status of the related approval request
changes from Pending to More Information. If your Approval Status field in the Search Criteria area
of Approval Central is set to Pending (the default), the approval request is removed from the
approval requests table when you send a More Information request. However, you can still find and
open the approval request by changing the Approval Status to More Information in the Search
Criteria area, and clicking Search. To see More Information requests assigned to them, approvers
can click the Pending Approvals, Past Due, or Due Soon link on Approval Central.
Note
Larry could approve or reject the approval request without waiting for Violet's response to
the More Information request. If he does so, Larry's More Information request is closed
when Frank's approval request is complete (all approvers have responded), regardless of
whether Violet has responded to the More Information request.
Responding to and viewing responses to More Information requests

This section demonstrates responding to a More Information request and then viewing the
responses.
Before you begin

Before approving a request, you must:
Follow the Creating new approval requests procedure
Follow the Requesting more information procedure.
To respond to a More Information request

1. Log on to BMC Remedy AR System as the sample user Violet Anderson, and open Approval
Central.
2. In the Summary panel, click the Needs Attention link.
3. Select the "I need a new computer" request, and click Response.
4. In the AP:More Information form, enter the appropriate text in the Response field, and click
Save.
The AP:More Information form closes. The More Information request is no longer visible to
Violet after she responds to it, and the Approval Status of the request changes back to
Pending.
Violet Anderson responds to Larry Goldstein's question
Page 1215 of 4705
Home
Note
To save an entry in the Response field of the AP:More Information form, the user
must be a member of a group with Change permission to the field. The BMC
Remedy AR System administrator might need to set the appropriate group-based
permissions on the Response field. For information about changing field
permissions, see Field permissions.
To view the response to a More Information request

1. Log on to BMC Remedy AR System as the sample user Larry Goldstein, and open Approval
Central.
2. Select the approval request for which you sent a More Information request, and click the
Approval Details icon.
Note
Until the recipient responds to the More Information request, the Approval Status of
the associated approval request is More Information, rather than Pending. If you do
not see the approval request you are looking for in the approval requests table on
Approval Central, click the Search My Approvals link in the Actions panel and
search for More Information requests.

4. In the activity log table, select the appropriate entry.
If your question has been answered, the answer appears in the Response field in the
Activity Log Details panel.
Tip
Page 1216 of 4705
Home
Optionally, to see the response in the AP:More Information form, click Needs
Attention on Approval Central, select the appropriate request, and click View.
Checking status of requests

This section shows how to verify the status of an approval request that you created. It requires that
you have followed Creating new approval requests.
Before trying you check the status of Frank Williams' request, perform the following procedures (
see Approving approval requests):
1. Log on to BMC Remedy AR System as Larry Goldstein, and approve the "I need a new
computer" request.
2. Log on to BMC Remedy AR System as Jack Miller, and approve the "I need a new computer
" request.
To check the status of an approval request you have sent

1. Log on to BMC Remedy AR System as Frank Williams, open the AP-Sample2:Get
Agreement form in Search mode, and click Search.
2. In the results list that appears, select Frank's request for the new computer.
The current status of the approval request appears in the Status field. If all three approvers
have approved the request for a new computer, the status of the request (in the detail area
of the window) is now Approved. If any of the approvers have not responded to the approval
request, the status of the request remains Pending.
3. To determine which approvers have responded to the approval request, click Show
Approver Signatures.
The detail-signature form opens in Search mode, with a results list that contains one entry
for each approver on the request. In this results list, the Approval Status column shows the
status of the request for each approver.
Viewing the status for each approver in the Get Agreement application
4.
Page 1217 of 4705
Home
4. To determine which approver is associated with each status, select an entry from the results
list.
The approver's name appears in the Approvers field, in the detail area of the window. In the
example shown in above figure, Frank can see that this request is Pending for Violet
Anderson.

The following topics provide general guidelines for working with flashboards you have created or
BMC Remedy Flashboards:
Viewing flashboards
Sorting flashboards
Refreshing flashboards
Displaying tooltips
Manipulating BMC Remedy Flashboards
Drilling down to information in a flashboard
For information about configuring and using the flashboards provided with the BMC Remedy ITSM
implementation, see Configuring flashboards and Using flashboards.
Viewing flashboards
After you add the flashboard to the form and configure the mid tier and BMC Remedy AR System,
you can view your flashboard by opening the form that contains the Data Visualization field with
the flashboard in a web browser.
Note
To view Unicode characters in a flashboards field on the BMC Remedy Mid Tier, you must
have the appropriate language packages installed on the system on which the mid tier is
running.
Sorting flashboards
In versions earlier than 8.1, you could sort BMC Remedy Flashboards based on the labels that
were specified for the charts. In version 8.1, you can sort flashboards based on the values specified
for each data point in ascending or descending order, and display the resulting data.
Note
This feature is not supported in the HTML version of flashboards.
Page 1218 of 4705
Home
The sorting depends on the flashboard variable grouping:

Single Group by The X axis does not have multiple categories. Every data point falls into
one category on the X axis. The sorting is done inside that category.
Double Group by The X axis has multiple categories and each category has multiple
bars. The sorting is done over each category according to length of corresponding bars.
In this topic:
How to sort flashboards
Types of sorting
How to sort flashboards

You can sort flashboards during design time or run time.
To sort flashboards during design time

1. Select All Objects > Flashboard Variables and click the Operations tab.
2. On the Group By tab, select the primary and secondary values.
3. In the Sortfield, select one of the following values:
No Sort
By Value
By Attribute
For more information, see the description of the Sort variable in Fields used to create
a flashboard variable table.
4. Specify the sort order by selecting either Ascending or Descending.
5. If you selected the By Attribute value in step 3, type the required value in the Sort Attribute
field.
6. Click Save.
To sort flashboards during run time

1. In a web browser, display the flashboard created during design time. For more information,
see Setting up flashboard update intervals.
2. Create a Set Field action for using any of the following parameters and its values defined
during run time:
sortType
sortOrder
sortAttribute
sortIsAttributeEnum
For more information, see Display parameters for charts.
Note
Page 1219 of 4705
Home
The parameters and the values set during run time, overwrite the
parameters and values set during design time.
Types of sorting
This section explains the types of sorting and provides examples.
Sort by numbers
Use the Sort by numbers option to arrange the primary categories by the cumulative values (
heights of the bars). For this type of sorting, both, Single Group by and Double Group by variable
grouping is supported.
The example in the following figure uses the Single Group by option to show the population in
each age group in a city. When you sort the data in ascending order, the result shows the total
number of people in each category, with the children being the smallest category and middle-aged
people being the largest category.
Sort by numbers Single Group by
The example in the following figure uses the Double Group by option to show the total population
and the population of each age group for different cities. The sorting is in ascending order based on
the age group in each city.
Sort by numbers Double Group by
Page 1220 of 4705
Home
Sort by specific value of attribute

Use the Sort by specific value of attribute option to sort flashboards and arrange the bars
according to the increasing value of a particular attribute.
Note
Only Double Group by variable grouping supports the Sort by specific value of attribute
option.
The example in the following figure uses the Sort by specific value of attribute option. The
sorting is in ascending order according to the number of middle-aged people (purple).
Sort by specific value of attribute
Refreshing flashboards
To enable users to refresh a BMC Remedy Flashboard, you can implement one of several methods
:
The user can refresh a flashboard by closing and re-opening the form that contains the
flashboard.
Page 1221 of 4705
Home
You can create a Refresh button that activates a Set Fields active link that resets the
flashboards field.
You can create a Refresh button that activates a Set Fields active link that resets the
flashboards field. Simply set the field to itself for the Set Fields action to refresh the field.
You can create a Set Fields active link at a specified interval to refresh a flashboard.
For more information, see Set Fields action and structures.
Displaying tooltips
When you hover your mouse over a flashboard, is shows the corresponding values of the
underlying data.
Displaying a tooltip
Tooltips are automatic and available on all types of charts.
Manipulating BMC Remedy Flashboards

If an application includes a flashboard (a graph such as bar chart or pie chart), you can manipulate
the look of the flashboard. You can use the following controls to manipulate the flashboard:
Flashboard controls
Button or
field
Description
Opens the Options panel where you can make changes as described in the Changing labels or variables section.
Opens the flashboard to a full-screen view. In a browser, press ESC to return to normal view.
Page 1222 of 4705
Home
Returns the flashboard to a normal view.
Opens the toolbar, which reveals the Zoom buttons, the Show Legend check box, and the chart selection menu.
Closes the toolbar, which reveals the Zoom buttons, the Show Legend check box, and the chart selection menu.
Show
Legend
Displays a legend for the flashboard.
Zooms in on specific parts of the flashboard. Click the button, and move the cursor to the flashboard. Click and drag
the area you want to zoom in on.
Zooms out to view more of the flashboard.
Allows you to change the flashboard to another type of chart. The options are:
Line Chart
Column Chart
Stacked Bar
Area Chart
Stacked Area
Pie Chart
Changing labels or variables

1. Click the properties (
) button.
2. Edit the following options:

Title - Title that appears in the tab above the set of flashboards.
X Axis Label
Y Axis Label
Active Variables - Enables you to add or remove variables from the flashboard.
Drilling down to information in a flashboard

You can view more information about a chart in a flashboard using the following methods:
Mouse over a grouping, and a tooltip displays the statistics for that grouping.
Click a grouping, and a tooltip displays more statistical information (such as the x and y
values).
To view the information about line, area, and stacked area charts, mouse over or click the end point
of the group.
Page 1223 of 4705
Home
Administering
BMC Remedy AR System administrators and security administrators use the information in this
section to set up user accounts and to manage and maintain the system after it is installed and
configured. For information about additional initial configuration, see Configuring after installation.
Goal
Instructions
Configuring servers and applications in the console interface

Administration console interface
Setting options in configuration files that are read upon startup of BMC Remedy AR
BMC Remedy AR System configuration
System components
files
Understanding processes or utilities and how to set options for BMC Remedy AR
System components and external utilities
AR System server components and

external utilities
Managing passwords, access control, and other security matters
Security administration
Setting options for user and administration preferences in the BMC Remedy AR
System User Preference form or the BMC Remedy Mid Tier
Managing time periods to define business schedules by using BMC Remedy AR

System commands
Defining business schedules using

Business Time
Configuring the server to allow workflow to notify users
Automatically specifying the person responsible for handling a request
Assigning requests with the Assignment

Engine
Allowing search within attached documents and increasing search speed in long text
fields
Configuring the appearance, functionality, and processing of your email
Controlling BMC Remedy AR System

through email
Managing processes and rules for approval requests
Transferring and managing requests between multiple servers in various distribution

environments
Setting up DSO to synchronize data across

Managing the capture of server-related activities, and notifying other servers or

clients of these changes
Capturing server events for workflow or

API calls
Auditing, archiving, importing, and exporting data, including other BMC Remedy AR
System database matters
Managing data
Automatically transferring objects and data between AR System servers with

workflows
Migrating applications and data between

AR System servers
Configuring Twitter, RSS feeds, and chat for end users and receiving BMC Remedy
ITSM Suite Twitter alerts
Enabling Social Collaboration in BMC

Remedy AR System
Page 1224 of 4705
Home

Administration console interface
This topic explains how to navigate the AR System Administration Console interface to configure
servers and clients to work with BMC Remedy AR System.
In this topic:
Opening the AR System Administration Console
AR System Administration Console introduction
System category

1. In a browser, go to the following URL address:
http://<midTierServerInstallDir>/arsys/forms/<serverName>
2. Log on.
3. Select AR System Administration > AR System Administration Console .

The AR System Administration Console gives you access to many administrator functions in BMC
Remedy AR System. The console is part of the AR System Server Administration plug-in, which
consists of a library file and a deployable application. (The plug-in is installed as part of the AR
System server installation.)
AR System Administration Console
Page 1225 of 4705
Home
The following sections describe the categories available in the AR System Administration Console.
System category
Application category
Admin Preferences category
User Preferences category
System category
General Provides the following links that enable you to configure your server and view
server information:
Server Information Used to configure your server. See Configuring AR System
servers.
FTS Configuration Used to configure FTS. See FTS Configuration form in the AR
System Administration Console.
SNMP Configuration Used to configure the SNMP Agent. See SNMP
Configuration form in the AR System Administration Console .
Review Statistics Used to view statistics about the server.
Review Server Events Used to capture server-related activities and use them in
workflow and API programs. See Capturing server events for workflow or API calls .
Add or Remove Licenses Used to configure license information. See Working
with BMC Remedy AR System licenses .
Password Management Configuration User to force password changes. See
Orchestrator Configuration Used to define the Atrium Orchestrator web service
for BMC Remedy AR System. See Defining BMC Atrium Orchestrator web services .
Web Services Registry Used to register a web service. See Registering,
modifying, and de-registering web services .
Page 1226 of 4705
Home
Web Services Registry Query Used to register the ServiceContext web service
for a BMC application. See Registering the Service Context web service for BMC
applications.
Distributed Server Option (DSO) Provides the following links that enable you to
configure DSO. See How BMC Remedy Distributed Server Option manages distributed
business requests.
Distributed Mappings See Distributed mapping.
Distributed Pools See Distributed pools.
Pending DSO Operations Managing pending distributed operations.
Distributed Logical Mappings See Enabling logical mappings.
LDAP Provides the following links that enable you to configure LDAP. See LDAP plug-ins
in BMC Remedy AR System.
ARDBC Configuration Used to configure the ARDBC plug-in. See Configuring the
ARDBC LDAP plug-in.
AREA Configuration Used to configure the AREA plug-in. See Configuring the
AREA LDAP plug-in.
Email Provides the following links that enable you to configure Email Engine. See
Controlling BMC Remedy AR System through email .
Mailbox Configuration Used to configure outgoing and incoming mailboxes. See
Configuring outgoing mailboxes and Configuring incoming mailboxes.
Email Templates Used to create templates for outgoing or incoming email. See
Creating and using email templates.
Email Security Used to configure outgoing and incoming mailbox security. See
Securing incoming and outgoing email.
Email Error Logs Used to store the logs of errors that have occurred during email
transmissions. See Email error and system status logs.
Application category
Users/Groups/Roles Used to configure users, groups, and roles. See these topics:
Users Used to configure users. See Adding and modifying user information.
Groups Used to configure groups. See Creating and managing groups.
Roles Used to configure roles. See Creating and mapping roles.
License Review Used to view the current user information. See Viewing user
license information.
Business Time Used to configure business time. See Defining business schedules using
Business Time.
Reports Used to configure reports. See Configuring reporting.
Report Creator See Defining BMC Remedy AR System reports .
Report Type See Defining a report type.
Currency Used to configure currency fields. See Currency fields and Setting currency
types.
Currency Codes See Localizing currency codes.
Page 1227 of 4705
Home
Currency Label Catalog See Localizing currency codes.

Currency Localized Labels See Localizing currency codes.
Currency Ratios See Currency exchange ratios
Other Used to view Message Catalog entries and application state information.
Message Catalog See Localizing BMC Remedy AR System applications .
Application States See Working with deployable application states for more
information about application states.
Admin Preferences category

This category enables you to configure and search for centralized administrator preferences, which
are discussed in Setting user preferences.
My Admin
Search Admin
User Preferences category

This category enables you to configure and search for centralized user preferences, which are
discussed in Setting user preferences.
My User Preferences
My Central Files
Search User Preferences
Search User Central Files
Search User Search Preferences
BMC Remedy AR System configuration files

This section contains information about AR System configuration files. Each file is listed by its UNIX
name. If the Microsoft Windows equivalent is different, it appears in parentheses after the UNIX
name.
ar
ar.cfg or ar.conf
ardb.cfg or ardb.conf
armonitor.cfg or armonitor.conf
Page 1228 of 4705
Home
ar
The ar file contains the list of BMC Remedy AR System servers to which the client tools (BMC
Remedy Developer Studio) connect if no servers are specified on startup. The ARGetListServer
function uses this file to return a list of available servers.
Entries in this file contain the following fields separated by a space or tab:
serverName serverInformationList
serverName is the name of the server computer. The name is resolved to a network
address by using the name resolution strategy of the local computer.
serverInformationList identifies the server as a BMC Remedy AR System server (AR) and
specifies the TCP port and RPC program numbers if applicable.
Lines with a pound sign (#) in column 1 are treated as comments and are ignored.
ar synopsis
ar environment
ar scenarios
ar synopsis
UNIX ARSystemServerInstallDir/conf/ar
Windows ARSystemHomeDir\ar
ar environment
ARCONFIGDIR
(UNIX only) Specifies the directory where the ar.conf file and other BMC Remedy AR System
configuration files are stored. The arsystem script sets ARCONFIGDIR to
ARSystemServerInstallDir/conf, and you should not need to change this value. However,
arsystem does not modify ARCONFIGDIR if a preset value is found.
ar scenarios
The following ar file entries register two server computers as BMC Remedy AR System servers:
# Directory file for BMC Remedy AR System servers

remedy AR
server2 AR;;3030;;390600
The TCP port and RPC program numbers are specified for server2.
Page 1229 of 4705
Home
ar.cfg or ar.conf
The ar.cfg (Windows) or ar.conf (UNIX) file contains AR System server configuration changes and
is dynamically created when you install AR System server.
When you make a server configuration change in the AR System Administration:Server Information
form, the configuration parameters and their new values appear in this file.
Any process can use the ARGetServerInfo function to retrieve configuration information from this
file. You can use the ARSetServerInfo function to modify the information. Such modifications take
effect immediately.
Manual modifications do not take effect until the BMC Remedy AR System server process is
restarted or signaled to reread the configuration file with arsignal -c.
Synopsis
Options
Environment
Scenarios
Synopsis
UNIX ARSystemServerInstallDir/conf/ar.conf
Windows ARSystemServerInstallDir\Conf\ar.cfg
Options
For ar.conf options, see:
ar.cfg or ar.conf options A-B
ar.cfg or ar.conf options C-D
ar.cfg or ar.conf options E-M
ar.cfg or ar.conf options N-R
ar.cfg or ar.conf options S-Z
Environment
ARCONFIGDIR
(UNIX only) Specifies the directory where the ar.conf file and other BMC Remedy AR System
configuration files are stored. The arsystem script sets ARCONFIGDIR to
Page 1230 of 4705
Home
Scenarios
The following configuration file identifies two directory locations:
# Configuration file for BMC Remedy AR System server

Server-directory: /usr/ar/db
Dbhome-directory: /usr/SQL-DB
The location of the data directory for this server is /usr/ar/db.

The location of the SQL database files is /usr/SQL-DB.
ar.cfg or ar.conf options A-B

Entries in this file contain the following fields separated by a space or tab:
<parameter>: <value>
Each parameter represents a particular configuration option. The available configuration options
and their settings are described in the following table. Lines that do not begin with one of these
options are ignored.
The associated value represents the current setting for the option. All numeric values are in a base
10 system.
Default behavior occurs either when an option is set to the default value or when the option is not in
the file.
1. Options you can view (but not set) using the AR System Administration: Server Information form.
2. Options you cannot set or view using the AR System Administration: Server Information form.
Lines with a pound sign (# ) in column 1 are treated as comments and ignored.
The following tables lists the options available for the ar.cfg (ar.conf) file. Unless otherwise
denoted by the table's footnotes, you can also set these options in the AR System Administration:
This section of the table includes the options for the ar.cfg (ar.conf) file that begin with the letters A
and B.
Note
All options in this file can be manually modified. Entries are case- and space-sensitive, so
be careful when editing this file.
Page 1231 of 4705
Home
ar.cfg (ar.conf) file options (A-B)
Tips
Press F to view the table in full screen mode. Press Esc to exit full screen mode.
To easily search for a specific parameter in the below table, select the parameter
from the Option list. Alternatively, type the name of the parameter in the Option
text box.
For example, to search for the Admin-Only-Mode parameter, select it from the
Option list, or type the parameter name in the Option text box.
To search for all parameters having a specific text string in the name, type the text
string in the Option text box.
For example, to search for all API parameters, type API in the Option text box.
To search for the parameters which have a specific text string in the description,
type the string in the Description text box.
For example, to search for the parameters which have $\USER$ in the description,
type $\USER$ in the Description text box.
Option
Description
Maps to
Active-Link-Dir
Directory in which active link server run processes are

stored. Only commands in the specified directory can be
run. This is a security feature that ensures clients or API
programs use only a safe set of server processes.
The Security area
(UNIX only) Parent shell of any active link server process.

This parameter causes the server to start the shell with
the specified process as a parameter. This is a security
feature. The specified shell might be a security shell that
verifies a path or runs with a user ID other than the one
the server uses. For example, if the server runs as root
and an administrator specifies a shell that runs as a lower
user privilege, an active link invokes the shell that runs as
a user instead of as root. Because the AR System server
passes the shell command to the Active-Link-Shell as a
single string without any other command-line arguments,
the command parameters can often get interpreted
incorrectly. The AR System server does not know which
custom shell is supposed to be used for active link
The Security area
Active-Link-Shell
on the Advanced
tab of the AR
System
Administration:
Server Information
form. (See Setting
performance and
security options.)
on the Advanced
tab of the AR
System
Administration:
Server Information
form. (See Setting
performance and
security options.)
Page 1232 of 4705
Home
Option
Description
Maps to
processing, so it does not know how to supply all of the

necessary arguments. In order to avoid this and use the
Active-Link-Shell Feature correctly, follow the steps listed
below:
1. Determine what your desired shell is, and how to
invoke it passing a single command line. If the
desired shell is /bin/csh, the correct way to invoke
with a single command line is
"/bin/csh" "-c" "process command"
2. Write a /bin/sh script that invokes your custom

shell in the required manner, as shown below:
#!/bin/sh
# Usage:
#
/path/to/arsystem-csh-helper
process-command
# Pass process-command as a command line to
/bin/csh.
#
# use "$*" preserve argument as a single
string
exec /bin/csh -c "$*"
3. Put the script in a location where the AR System

server will be able to call it. For example, local
utilities are often installed in a directory named /
usr/local or /usr/local/bin. Another good location
might be the AR System server installation
directory. Be sure to mark the new program
executable:
# cp arsystem-csh-helper /usr/local/
arsystem-csh-helper
# chmod 755 /usr/local/arsystem-csh-helper
4. In the AR System server configuration, change the

Active-Link-Shell to be the new program /usr/local
/arsystem-csh-helper
Admin-Only-Mode
Flag indicating whether only administrators and

subadministrators can access the server. Values are
The
Administrator-Only
Mode field on the
T Admin-only mode is on.

F (Default) Admin-only mode is off.
AE-Poll-Interval 2
Configuration tab
of the AR System
Administration:
Server Information
form. (See Setting
administrative
options.)
Interval (in minutes) at which the Assignment Engine polls

the BMC Remedy AR System server. If this option is not
specified, the polls occur every 5 minutes.
Page 1233 of 4705
Home
Option
Description
AE-Worker-Thread
Indicates the total number of worker threads that process

various assignment requests (See Configuring the
Maps to
Assignment Engine).
Allow-Backquote-In-Process-String
Option that enables the server to run a process with a

backquote in the process name or in its arguments.
Values are T and F (default).
Allow-Guest-Users
Flag indicating whether the BMC Remedy AR System

server accepts guest users (users not registered with
BMC Remedy AR System in a User form). Values are
T (Default) Allow guest users. Unregistered
users have no permissions but can perform some
basic operations. For example, they can submit
requests to forms to which the Public group has
access and whose fields allow any user to submit
values.
The Allow Guest

Users field on the
Configuration tab
of the AR System
Administration:
Server Information
form. (See Setting
administrative
options.)
F Do not allow guest users. Unregistered users

have no access to the system.
Flag indicating whether unqualified searches can be

performed on the BMC Remedy AR System server.
The Allow
Unqualified searches are ARGetListEntry or
Searches field on
ARGetListEntryWithFields calls in which the qualifier
the Configuration
tab of the AR
System
Administration:
Server Information
form. (See Setting
administrative
options.)
parameter is NULL or has an operation value of 0 (

AR_COND_OP_NONE ). Such searches can cause
performance problems because they return all requests
for a form. This is especially problematic for large forms.
Values are
T (Default) Allow unqualified searches.
Unqualified
F Do not allow unqualified searches.
Alternate-Approval-Reg 2
Flag indicating how applications such as Approval Server

or Reconciliation Engine listen for the BMC Remedy AR
System server's signal. Values are
T (default) Listen for the application dispatcher
to signal.
If your application relies on the application
dispatcher, set this option to T. To verify that
arsvcdsp is configured to start with the BMC
Remedy AR System server, check the
armonitor.cfg (armonitor.conf ) file.
F Listen for the server's signal directly.
API-Log-File
Full path name of the file to use if API logging is on (See

Debug-mode).
The API Log field

on the Log Files
tab of the AR
System
Administration:
Server Information
form. (See Setting
log files options.)
Page 1234 of 4705
Home
Option
Description
API-SQL-Stats-Control
A bit mask value indicating options selected.
API-SQL-Stats-Max-Saved-Long-Operations
Maximum number of longest API and SQL operations
Maps to
saved in memory. The default is 20 of each type. The

highest value allowed is 100.
API-SQL-Stats-Flush-To-DB-Interval
Time, in minutes, between flushing the longest operations

from memory to the forms. A value of 0 (the default)
means that there is no automatic flushing.
API-SQL-Stats-Minimum-Elapsed-Time
Minimum elapsed time an operation must have to qualify

for recording. The default is 5000 milliseconds (or 5
seconds).
Approval-Defn-Check-Interval 2
Interval (in seconds) at which Approval Server checks for

changed or updated data in the data definition forms.
Approval-Log-File 2
Full path of the Approval Server log file.
Approval-Notify 2
Flag indicating whether approval notifications are

configured from the Server Settings dialog box. An
Approval-Notify entry exists for each ID. The syntax is
Approval-Notify: ID value Do not change this option in
the ar.cfg (ar.conf ) file. Instead, from the AP:
Administration form, click the Server Settings link to open
a dialog box with configuration settings for the Approval
Server.
Approval-Polling-Interval
Interval at which the Approval Server polls the AR System

server for pending work. This setting is intended as a
backup method, not the primary contact method. Under
normal circumstances, the AR System server or the
Application Dispatcher (depending on the configuration)
contacts the Approval Server when work is pending.
When this option is specified, the Approval Server polls
the AR System server only if it does not receive a signal
from the AR System server in the specified time.
Specify the interval in seconds. Minimum is 30 seconds.
Maximum is 3600 seconds (one hour).
If the interval value is not specified, the default value (
1800 seconds or 30 minutes) is considered.
Approval-RPC-Socket 2
RPC Program Number that Approval Server uses when

contacting BMC Remedy AR System. This enables you to
specify a private BMC Remedy AR System server for
Approval Server.
AppSignal logging
Flag indicating whether logging for the appsignal library is

enabled or disabled. By default, logging is disabled. To
enable logging, add the following entry in the ar.cfg(
ar.conf ) file:
AppSignal logging : T
Note: If this entry is missing from the file, the default
value (AppSignal logging: F) is considered.
Page 1235 of 4705
Home
Option
Description
Maps to
When you enable logging, the following log files are

created in the db directory (installationDirectory/db for
UNIX and installationDirectory\Arserver\db for Windows):
For Approval Server: appSignalAPlog.log
For Assignment Engine: appSignalAElog.log
For Distributed Server Option (DSO):
appSignalDSOlog.log
AR-Max-Attach-Size 2
Maximum size (in bytes) of compressed attachments that

can be sent to the AR System database from the AR
System server. By preventing large attachments from
being sent to the database, you can prevent excessive
memory growth and reduce transmission time. This limit
does not apply to attachments retrieved from the
database by the AR System server. This option applies to
all databases.
Note: To limit the size of compressed attachments that
the server can retrieve from Oracle databases, use
Db-Max-Attach-Size.
ARDBC-LDAP-Base-DN
Base distinguished name (DN) to use instead of the root
The Base DN For
DN as the starting point for discovering vendor tables
Discovery field on
when you design vendor forms. For example:
the ARDBC LDAP

Configuration form.
ARBDC-LDAP-Base-DN: CN=Users, DC=ldapesslab,

DC=com
(See Configuring
the ARDBC LDAP
plug-in.)
ARDBC-LDAP-Cache-MaxSize
Size limit (in bytes) for the cache. For no size limit, set
this to 0. The default is 32768 bytes.
The Maximum Size

field in the ARDBC
Plugin Cache box
on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
ARDBC-LDAP-Cache-TTL
Time limit (in seconds) that data remains cached. For no

time limit, set this to 0. The default is 60 seconds.
The Time To Live

field in the ARDBC
Plugin Cache box
on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
ARDBC-LDAP-Cert-DB
Directory name of the certificate database. The cert8.db
The Certificate
or cert7.db and key3.db certificate database files are in

this directory. If the directory is not specified, the LDAP
plug-in looks in the BMC Remedy AR System installation
directory for these files. The path in this option is used
Database field on
the ARDBC LDAP
only when ARDBC-LDAP-UsingSSL is set toT.
Page 1236 of 4705
Home
Option
Description
Maps to
Configuration form.
(See Configuring
the ARDBC LDAP
plug-in.)
ARDBC-LDAP-Cert-Name 2
Not yet implemented.
ARDBC-LDAP-Chase-Referrals 2
Flag that enables automatic referral chasing by LDAP

clients. Values are
T Referrals are chased.
F (Default) Referrals are not chased.
This option is for Microsoft Active Directories only.
ARDBC-LDAP-Connect-Timeout 2
Number of seconds that the plug-in waits for a response

from the directory service before it fails. The minimum
value is 0, in which case the connection must be
immediate. The maximum value is the
External-Authentication-RPC-Timeout setting. If a
value is not specified, this option is set to the value of the
External-Authentication-RPC-Timeout option (by
default, 40 seconds).
ARDBC-LDAP-DN-Timeout 2
Number of seconds that the plug-in retains the base

distinguished name (DN) used to access an LDAP
ARDBC vendor form after the user becomes inactive. The
default is 3600 seconds.
ARDBC-LDAP-Drop-Large-Values 2
Obsolete in version 7.0.00 and later.
ARDBC-LDAP-Hostname
Host name of the system on which the directory service

runs. If the host name is not specified, the ARDBC LDAP
plug-in uses localhost as the host name. For example:
ARDBC-LDAP-Hostname: server1.eng.remedy.com
ARDBC-LDAP-Key-DB 2
ARDBC-LDAP-Key-Password 2
ARDBC-LDAP-Page-Size 2
Page size in the pagedResultsControl of the ARDBC

LDAP plug-in search request. This specifies the number
of entries to return per page from the external directory
server to the client when processing a search request
The Host Name

field on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
containing the pagedResultsControl. The maximum

value is 100,000. The minimum value is 100. The default
value is 10,000. (See Using the ARDBC LDAP plug-in.)
ARDBC-LDAP-Port
Port number on which the directory service listens for

clients.
The Port Number

field on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
Page 1237 of 4705
Home
Option
Description
ARDBC-LDAP-Time-Format 2
Format of LDAP date and time data. Values are
Maps to
0--Generalized Time Format (

YYYYMMDDHHMMSSZ ) This format is
recognized by all LDAP servers and is
recommended.
1--AD Generalized Time Format (
YYYYMMDDHHMMSS.0Z ) This format is
recognized by Microsoft Active Directory servers
only.
2--UTC Time Format (YYMMDDHHMMSSZ )
This historical format does not indicate the century. It is
not recommended.
ARDBC-LDAP-Use-Cache 2
Flag that enables caching of search requests. Values are

T and F. After caching is enabled, search requests issued
via the ARDBC plug-in are cached. Subsequent matching
search requests are satisfied from the cache.
ARDBC-LDAP-User-DN
Distinguished name (DN) of the user account that the

ARDBC LDAP plug-in uses to search and modify the
ARDBC-LDAP-User-DN: server1\admin
The Bind User field

on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
Flag indicating whether to establish a secure socket layer
The Using Secure
(SSL) connection to the directory service. Values are T
Socket Layer field

on the ARDBC
LDAP Configuration
form. (See
Configuring the
ARDBC LDAP
plug-in.)
contents of the directory service. For example:
ARDBC-LDAP-UsingSSL
and F. If you use LDAP over SSL, you must also specify
the file name of the certificate database used to establish
the connection.
AREA-LDAP-Bind-Password
Password of the user account that the AREA LDAP
The Bind
plug-in uses to find the user object when using the User
Search filter. If the distinguished name (DN) is not
Password field on
specified, the AREA LDAP plug-in uses an anonymous

login to find the user object. If the target directory service
does not allow anonymous access, you must specify a
DN and password; otherwise, the plug-in cannot
determine the DN of the user.
AREA-LDAP-Bind-User
Distinguished name (DN) of the user account that the

AREA LDAP plug-in uses to find the user object when
using the User Search filter. If the DN is not specified, the
AREA LDAP plug-in uses an anonymous login to find the
user object. If the target directory service does not allow
anonymous access, you must specify a DN and password
; otherwise, the plug-in cannot determine the DN of the
the AREA LDAP

Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
The Bind User field

on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
user. For example: AREA-LDAP-Bind-User: ldapesslab

\admin
AREA-LDAP-Cert-DB
Page 1238 of 4705
Home
Option
Description
Maps to
Directory name of the certificate database. The cert8.db
The Certificate
or cert7.db and key3.db certificate database files are in

this directory. If the directory is not specified, the LDAP
plug-in looks in the BMC Remedy AR System installation
directory for these files. This path is used only when
Database field in
ARDBC-LDAP-UsingSSL is set to T.
the Directory
Service
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
AREA-LDAP-Chase-Referral 2
Flag that specifies whether referral chasing is performed

by the AD server or the AREA LDAP plug-in. Values are
The Chase Referral

field in the
Directory Service
T Referral chasing is performed by the AD

server.
F (Default) Referral chasing is performed by the
AREA LDAP plug-in (via the third-party LDAP
library).
This option is for Microsoft Active Directories only.
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
Note: To force referral chasing logic to be disabled, you

must also specify the AREA-LDAP-Disable-Referral
option. (See ar.cfg or ar.conf options A-B.)
AREA-LDAP-Connect-Timeout
Number of seconds that the plug-in waits to establish a
The Failover
connection with the directory service. The minimum value

is 0, in which case the connection must be immediate.
Timeout field in the
The maximum value is the
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
External-Authentication-RPC-Timeout setting. If a
value is not specified, this option is set to the value of the
External-Authentication-RPC-Timeout option (by
default, 40 seconds).
AREA-LDAP-Disable-Referral 2
Directory Service
Flag that disables all referral processes by the

AREALDAP plug-in. Values are
T Referrals are disabled.
Note: This overrides the
AREA-LDAP-Chase-Referral setting.
F (Default) Referrals are not disabled.
For information about how the referrals are
processed, see ar.cfg or ar.conf options A-B. The
referral option is for Microsoft Active Directories
only. When connecting to a non-Microsoft Active
Directory, BMC recommends disabling referral
processing.
AREA-LDAP-Email 2
Name of the attribute that specifies the email address of

the user. This attribute corresponds to the Email Address
field in the BMC Remedy AR System User form. If the
attribute is not specified, the specified default or a system
default is applied.
Page 1239 of 4705
Home
Option
Description
AREA-LDAP-Email-Default 2
Value that the AREA LDAP plug-in uses if the
Maps to
AREA-LDAP-Email parameter is not specified or has no

value for the user.
AREA-LDAP-Group-Base
Base of the LDAP directory to search groups from. To

determine the option's values at runtime, use these
keywords:
Note: The backslash (\) is required.
$\USER$ User's login name.
$\DN$ User's distinguished name. This applies
only to the Group Base Name and Group Search
Filter. It does not apply to the User Base name and
User Search filter.
The Group Base

field in the User
and Group
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
$\AUTHSTRING$ Value that users enter into

the Authentication String field when they log in.
$\NETWORKADDR$ IP address of the AR
System client accessing the AR System server.
AREA-LDAP-Group-Default 2
Default groups to which the user belongs if no group

information is available from the directory service. If the
user belongs to multiple groups, use a semicolon to
separate them.
AREA-LDAP-Group-Filter
LDAP search filter used to locate the groups to which the

user belongs. To determine the option's values at runtime
, use these keywords:
The Group Search

Filter field in the
User and Group
Information area

$\DN$--- User's distinguished name. This only
applies to the Group Base Name and Group
Search Filter. It does not apply to the User Base
Name and User Search Filter.
on the AREA LDAP

Configuration form.
(See Configuring
the AREA LDAP
plug-in.)

AREA-LDAP-Hostname
Host name of the system on which the directory service

runs. If no value is specified, the AREA LDAP plug-in
The Host Name

field in the
uses localhost as the host name.
Directory Service
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
AREA-LDAP-Lic 2
Name of the attribute that identifies the type of write

license issued. This attribute corresponds to the License
Type field in the BMC Remedy AR System User form. If
the attribute is not specified, the specified default or a
system default is applied.
Page 1240 of 4705
Home
Option
Description
AREA-LDAP-Lic-Default 2
Maps to
AREA-LDAP-Lic attribute is not specified or has no value

for the user.
AREA-LDAP-LicApp 2
Name of the attribute that identifies the type of application

license issued. If the attribute is not specified, the
specified default or a system default is applied.
AREA-LDAP-LicApp-Default 2

AREA-LDAP-LicApp attribute is not specified or has no
value for the user.
AREA-LDAP-LicMask
Attribute that specifies how to mask the license

information returned from the AREA LDAP plug-in.
The License Mask
Values are
and Mapping
field in the Defaults

Attributes to User
0--No licenses returned from the AREA LDAP

plug-in are used.
1--Write license from the plug-in is used.
4--Reserved license from the plug-in is used.
5--Reserved license and Write license from the
plug-in are used.
8--Application license from the plug-in is used.
9--Application and Write licenses from the plug-in
are used.
12--Application and Reserved licenses from the
plug-in are used.
13--All licenses from the plug-in are used.
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
If the license is not used from the plug-in, the license

information in the user's User entry is used.
AREA-LDAP-LicMask-Default 2

AREA-LDAP-LicMask attribute is not specified or has no
value for the user.
AREA-LDAP-LicRes1 2
Name of the attribute that specifies the type of reserved

license issued. If the attribute is not specified, the
specified default or a system default is applied.
AREA-LDAP-LicRes1-Default 2

AREA-LDAP-LicRes1 attribute is not specified or has no
value for the user.
AREA-LDAP-Notify-Meth 2
Name of the attribute that specifies the default notification

mechanism for the user. This attribute corresponds to the
Default Notification Mechanism field in the AR System
User form. If the attribute is not specified, the specified
default or a system default is applied.
AREA-LDAP-Notify-Meth-Default 2

AREA-LDAP-Notify-Meth attribute is not specified or has
no value for the user.
AREA-LDAP-Port
Port number on which the directory service listens for

clients.
The Port Number

field in the
Directory Service
Information area
Page 1241 of 4705
Home
Option
Description
Maps to
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
AREA-LDAP-SSL-AUTH-OPTION 2
Flag indicating how the secure connection is established.

By default, AREA-LDAP-SSL-AUTH-OPTION is set to
true and will continue to authenticate the server certificate
when opening the secure connection. If you set
AREA-LDAP-SSL-AUTH-OPTION to false, the server
certificate is not authenticated and multiple secure server
connections can be established concurrently.
AREA-LDAP-Use-Groups
Flag indicating whether to retrieve group information from

the LDAP server. If this parameter is not set, group
information from the AR System Group form is used.
The Group
Membership field in
the User and
Group Information
area on the AREA
LDAP Configuration
form. (See
Configuring the
AREA LDAP plug-in
.)
AREA-LDAP-User-Base
User base in the LDAP directory to search for the user.
The User Base field
To determine the option's values at runtime, use these

keywords:
in the User and

$\DN$ User's distinguished name. This only
Group Information
area on the AREA
LDAP Configuration
form. (See
Configuring the
AREA LDAP plug-in
.)

AREA-LDAP-User-Filter
LDAP search filter used to locate the user in the directory
The User Search
from the base that the AREA-LDAP-User-Base option

specifies. To determine the option's values at runtime,
use these keywords:
Filter field in the

$\DN$ User's distinguished name. This only
User and Group

Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)

Page 1242 of 4705
Home
Option
Description
Maps to
AREA-LDAP-UseSSL
Flag indicating whether to establish a secure socket layer
The Use Secure
(SSL) connection to the directory service. Values are T
Socket Layer? field
and F. If you use LDAP over SSL, you must also specify
the file name of the certificate database used to establish
the connection.
in the Directory
Service
Information area
on the AREA LDAP
Configuration form.
(See Configuring
the AREA LDAP
plug-in.)
Arerror-Exception-List 2
List of errors that trigger a dump of the current stack in

the arerror.log file. Separate each error number with a
semicolon (for example, 123;345;).
ARF-Java-Class-Path 2
Obsolete as of release 7.5.00.
ARF-Java-VM-Options 2
Java command options for a virtual machine (VM). The

options are documented in the online AR System Java
API documentation.
ASJ-Thread-Count
Specifies the total number of worker threads that process

various approval requests.
The minimum value is 1. The maximum value is 4. The
default value is 4.
Note: If the specified value is not within the maximum
and minimum value, the default value is applied. If a
value is not specified, this option is set to the default
value.
Attachment-Exception-List
Parameter which allows you to override the Attachment

Security functionality implemented in the AR System
Administration: Server Information form. To override the
attachment restrictions, you can specify the Form name
with Field ID and upload attachments only for that field ID.
Note: Field ID is the numeric value of the field that
contains an attachment on the form. You can get the
value for a Field ID from the Developer Studio.
For example,
If attachments of the type PDF have been disabled in the
AR System Administration: Server Information >
Attachment Security > Attachment criteria, it should still
be possible for PDF based reports to be scheduled and
published. To solve such a problem, in the AR System
Administration: Server Information > Attachment Security
> Attachment exception list, enter form name and field ID
combination, such as AR System Publish Report(90104),
to override the attachment security setting. The PDF
attachments will now be allowed for field ID 90104 on the
AR System Publish Report form, even if PDF attachments
are disallowed globally. Similar entry can be made for
Page 1243 of 4705
Home
Option
Description
Maps to
other forms like the AR System Resource Definitions form

, and for the field ID 41103 as AR System Resource
Definitions(41103).
For multiple form and field ID entries, enter a comma
separated list like AR System Publish Report (90104), AR
System Resource Definitions(41103) in the Attachment
exception list field.
For more information, see Setting security restrictions on
file uploads
Authentication-Chaining-Mode
Mode that enables the administrator to use more than

one type of authentication on the same system. Values
are
0 (Off)--Use the default behavior. Users are
authenticated based on the settings of
Crossref-Blank-Password and
Authenticate-Unregistered Users.
1 (ARS - AREA) Use internal authentication as
the primary method; use external authentication
via the AREA plug-in as the secondary method.
2 (AREA - ARS) Use external authentication via
the AREA plug-in as the primary method; use
internal authentication as the secondary method.
3 (ARS - OS- AREA) If authentication fails in AR
System (internal authentication), use the operating
system authentication (for example, NT domain
authentication). If the operating system fails, try
external authentication (AREA).
4 (ARS - AREA - OS) If authentication fails in
AR System, try AREA. If AREA fails, try the
operating system authentication.
If the value is not 0, the settings of the
Crossref-Blank-Password and
Authenticate-Unregistered Users parameters are
ignored.
If the value is not 0 and the Crossref-Blank-Password
parameter is enabled, users who have a blank password
in the User form must provide a valid password (that is, a
non-NULL password) during login.
Values 3 and 4 provide greater flexibility. For example,
your external users might be authenticated with an AREA
plug-in, and internal users might be authenticated by the
NT domain.
ARSYS.ARF.ATSSOCONFIRMPWD
Name of a plugin used by the BMC Remedy AR System

server to confirm the user password information from the
BMC Atrium Single Sign-On server.
Page 1244 of 4705
Home
ar.cfg or ar.conf options C-D

This table contains the options for the ar.cfg (ar.conf) file that begin with the letters C and D.
ar.cfg (ar.conf) file options (C-D)
Tips
text box.
For example, to search for the Cache-Mode parameter, select it from the Option
list, or type the parameter name in the Option text box.
For example, to search for all Cache parameters, type Cache in the Option text
box.
For example, to search for the parameters which have ARCreateEntry() in the
description, type ARCreateEntry() in the Description text box.
Option
Description
Cache-Display-Properties 2
The way that the server caches form display properties.

The form display property is the background image of the
form view and the display property of each form field. Valid
values:
Maps to
T (Default) Cache all form-display properties.

F Cache only server-display properties. (This can
negatively impact the performance of the server if a
form is changed, but it reduces the amount of
memory used in the server cache.)
Cache-Mode
Flag indicating whether a cache mode optimized for

application development is on. In this mode, user
operations might be delayed when changes are made to
forms and workflow. Valid values:
1 Development cache mode is on.
0 (Default) Development cache mode is off, and
the server is in production cache mode.
The Development
Cache Mode field on
the Configuration tab
of the AR System
Administration: Server
Information form. (See
options.)
Note: Development cache mode is intended for a
Page 1245 of 4705
Home
Option
Description
Maps to
development server, not a production server. In this

mode, administrative operations cannot begin until
in-progress user operations are completed.
Subsequent user operations are blocked until the
administrative operation is completed. Hence, the
server often gives the false impression that it has
stopped responding. (See Configuring a server's
cache mode.)
Cancel-Query-Option 2
Flag indicating whether the cancel query functionality in a

browser is enabled. Valid values:
0 Inactive
1 (Default) Active
Changed-By-Another-Check
Flag indicating whether the system checks whether another

user changed an entry after you retrieved the entry. If you
try to save modifications to an entry, you receive a warning
and must confirm the save. Valid values:
T (Default) Perform the check and issue a
warning.
F Do not perform the check.
Client-Managed-Transaction-Timeout
Maximum time (in seconds) to hold a transaction before a

timeout occurs. The default is 60 seconds, and there is no
maximum. If a timeout occurs, the server automatically rolls
the transaction back, and the client receives an error on the
next operation that uses the transaction handle.
The Transaction
Timeout (seconds)
field in the
Transaction Control
area on the
Advanced tab of the
AR System
Setting performance
and security options.)
Clustered-Index
Flag indicating whether indexes for the database are

clustered. Valid values:
T (Default) Use a clustered index.
F Do not use a clustered index.
You must set this option before you start the BMC
CMDB-Cache-Refresh-Interval 2
Frequency, in seconds, at which the BMC Atrium CMDB

cache is refreshed. The default value is 300 seconds (5
minutes). For more information about the cache refresh
interval, see Setting the cache refresh interval.
Create-Entry-DeadLock-Retries 2
Number of times to retry the ARCreateEntry() function

during deadlock situations. Value is an integer.
Create-Entry-DeadLock-Retries-Delay 2
Delay, in seconds, between each retry of a deadlocked

ARCreateEntry() function. Value is an integer.
Page 1246 of 4705
Home
Option
Description
Crossref-Blank-Password
Flag indicating how the system responds when a user's

logon name is not assigned a password in the User form.
Maps to
Valid values:
T The system tries to validate the password in the
Windows server domain (or through the External
Authentication API if external authentication is on) or
against the UNIX server /etc/passwd file.
F (Default) Blank passwords are not
cross-referenced.
This option enables you to manage group
membership and other support information with AR
System while managing passwords with the /etc/
passwd file (UNIX) or the server domain security
model (Windows).
Currency-Ratio-Client-Refresh-Interval 2
Number of minutes between each refresh of currency

conversion ratios on the client.
Db-Case-Insensitive 1
Flag indicating whether to perform case-insensitive queries

on Run If qualifications for active links, filters, and
escalations. (For Oracle databases, ensure that this option
matches the behavior of your Oracle database so that all
queries are consistent.) Valid values:
T Performs case-insensitive search. Setting this
parameter in the ar.cfg (ar.conf) file causes special
session parameters (NLS_SORT and NLS_COMP)
to be set to support case-insensitive searches and
invalidate existing database indexes.
By default, the AR System server creates regular
indexes when you add an index to a form. To
support case-insensitive searches on Oracle
databases, functional indexes are required instead of
regular indexes. To change the AR System server's
default behavior for index creation, set the
Db-Functional-Index parameter to T. For more
information, see Db-Functional-Index.
F (the default) Performs case-sensitive queries.
To learn how to enable case-insensitive search for
fixed-length text fields in BMC Remedy AR System version
8.1 on Oracle, see the BMC Knowledge Base article
KA406947.
Db-Character-Set 2
Option that initializes an internal variable that the server

uses for various purposes, such as informing the
ARGetServerInfofunction's
AR_SERVER_INFO_DB_CHAR_SET server option
request or adjusting the database short column size so that
the number of characters in a datum does not exceed the
number of bytes in the database field. Valid values:
Unicode (UTF-16) UTF-16 UCS-2
Unicode (UTF-8) UTF-8
Page 1247 of 4705
Home
Option
Description
Maps to
Note: The installer sets this option's value.

Db-Connection-Retries 2
Number of times the BMC Remedy AR System server tries

to reestablish a lost connection to the database. The default
is 100. The server retries the connection once every 15
seconds up to the specified number of times. For example,
when this option is set to 100, the server retries the
connection once every 15 seconds for a duration of 25
minutes.
Db-Functional-Index 1
Option to change the AR System server's default behavior
for index creation. To change the AR System server's
default behavior for index creation, set the
Db-Functional-Index parameter to T. Then, when a new
index is added to a form, the AR System server creates a
functional index for the form. This parameter helps to avoid
performance degradation that can result from not using
database indexes.
The Db-Functional-Index parameter is ignored if
Db-Case-Insensitive is set to F or if it is absent from the
ar.cfg file.
The Db-Case-Insensitive and Db-Functional-Index
parameters handle new indexes. In the database (outside
of the AR System server), you must manually convert any
existing indexes to functional indexes. BMC provides an
unsupportedOracleFunctionalIndexHelper.bat utility to
manage these existing indexes and to convert them from
regular to functional indexes. You can find this unsupported
utility in the ARServerInstallDirectory\Arserver\api\lib
folder.
Due to known issue with Oracle, set cursor sharing to
EXACT so that the query optimizer can use functional
indexes for LIKE queries. For help, see your database
administrator.
Note: While running the
OracleFunctionalIndexHelper.bat utility for existing forms,
you might see the following error:
Error message ERROR (552): The SQL database operation
failed.; ORA-00942: table or view does not exist.
This occurs because indexes are not applicable on vendor,
view, display-only, and join forms.
For optimal performance when using database indexes for
case-insensitive searches on Oracle, ensure that:
The Oracle client is at least version 11.2.
The database administrator sets cursor sharing to
EXACT for the functional indexes that Oracle
Optimizer will use (otherwise, performance can be
severely degraded due to full table scans).
Note: Depending on the volume of data, creating functional
indexes may take a long time.
Db-Max-Attach-Size2
Page 1248 of 4705
Home
Option
Description
Maps to
Maximum size (in bytes) of compressed attachments that

the AR System server can retrieve from Oracle databases.
The default value is 2 GB. This value is limited by your
server operating system and configuration.
Note: To limit the size of compressed attachments that can
be sent to the database server from AR System server, see
AR-Max-Attach-Size.
Db-Max-Text-Size 2
(Oracle, Microsoft SQL Server, and Sybase) Maximum size

for long character text data in databases. For Oracle
databases, this value is also used for memory allocation
during the processing of long text data; therefore, use it
conservatively. The default for an Oracle database is
4,194,308 bytes. For SQL Server and Sybase, the default is
2,147,483,647 bytes. The maximum value for either
database is 2,147,483,647 bytes.
Db-name 1
For Oracle, the name of the tablespace that the AR System

server uses. For all other supported databases, the name
of the underlying SQL database. The default value is
ARSystem.
Db-password
(DB2, Microsoft SQL Server, Oracle, and Sybase)

Database password associated with the ARSystem
database and table space. The password can be modified
by using the ARSetServerInfo function and is stored in
encrypted form. If you change the password manually,
specify this option by using clear text, and change the
password by using the AR System Administration: Server
Information form to encrypt it.
Db-user 1
(Microsoft SQL Server, Oracle, and Sybase) User name

that AR System uses to access the underlying database.
The default is ARAdmin.
DB2-Database-Alias
DB2 database alias name for the AR System database.
DB2-Server-Name
DB2 database server name.
Dbhome-directory 1
(SQL databases on UNIX only) Full path name of the home

directory for the underlying database.
Debug-GroupId
Name of the group to which a user must belong to use

logging options such as API, database, and filter logging in
BMC Remedy AR System clients. Logging options are
disabled for users who are not members of the specified
group. The group name can be Public, Administrator, Sub
Administrator, or Browser. You can also set this option in
the Client-Side Logging Group field on the Log Files tab.
Debug-mode
Bitmask indicating the server logging modes. To activate

one bit, set this option to its value (see the following list). To
activate two or more bits, add their values, and set this
option to the total. For example, to activate bits 1 and 3, set
this option to 5 because bit 1 has a value of 1 and bit 3 has
a value of 4. To deactivate a bit, subtract its value from the
value of this option. Unless otherwise specified in the
Page 1249 of 4705
Home
Option
Description
Maps to
following list, this option turns on logging for the arserverd

process. Default log files are in the directory specified by
the Server-directory option.
Bit 1 (value = 1 ) (SQL databases only) Turns on
SQL logging in the default arsql.log file. To specify a
different file, use the SQL-Log-File option.
Bit 2 (value = 2 ) Turns on filter logging in the
default arfilter.log file. To specify a different file, use
the Filter-Log-File option.
Bit 3 (value = 4 ) Turns on user logging in the
default aruser.log file. To specify a different file, use
the User-Log-File option.
Bit 4 (value = 8 ) Turns on escalation logging in
the default arescl.log file. To specify a different file,
use theEscalation-Log-File option.
Bit 5 (value = 16 ) Turns on API logging in the
default arapi.log file. To specify a different file, use
the API-Log-Fileoption.
Bit 6 (value = 32 ) Turns on thread logging in the
default arthread.log file. To specify a different file,
use the Thread-Log-File option.
Bit 7 (value = 64 ) Turns on alert logging in the
default aralert.log file. To specify a different file, use
the Alert-Log-File option.
Bit 8 (value = 128 ) Turns on arforkd logging in
the default arforkd.log file. To specify a different file,
use the arfork-Log-File option.
Bit 9 (value = 256 ) Turns on server group logging
in the default arsrvgrp.log file. To specify a different
file, use theServer-Group-Log-File option.
Bit 10 (value = 512 ) Turns on logging for full text
indexing in the default arftindx.log file. To specify a
different file, use the Full-Text-Indexer-Log-File
option.
Bit 16 (value = 32768 ) Turns on DSO server
logging in the default ardist.log file. To specify a
different file, use theDistrib-Log-File option.
Bit 17 (value = 65536 ) Turns on Approval Server
logging. To specify the location for the arapprov.log
file, use the Approval Menu > Server Settings > AP:
Admin-Server Settings form.
Bit 18 (value = 131072 ) Turns on plug-in logging
in the default arplugin.log file. To specify a different
file, use thePlugin-Log-File option.
Default-Allowable-Currencies
Default allowable currency types for currency fields in

clients.
Default-Functional-Currencies
Default functional currency types for currency fields in

clients.
Default-Order-By 2
Flag indicating whether to apply the default sort order to

search results. Valid values:
Page 1250 of 4705
Home
Option
Description
Maps to
T (Default) Use the default sort order, which is to

sort by request ID.
F No default sort order exists, and no order by
clause is added to the command if a sort order is not
specified.
Default-Web-Path
URL to the directory path for the default web server pointing
to the BMC Remedy AR System server.
Maps to: The Default Web Path field on the Advanced tab
of the AR System Administration: Server Information form. (
See Setting performance and security options.)
Delay-Recache-Time
Number of seconds before the latest cache is made

available to all threads. Valid values: 0 to 3600 seconds. If
this option is set to 0, every API call gets the latest cache (
that is, the cache is copied for every administrator call).
Setting the option to 0 causes slower performance for
cache operations.
The default value is 5 seconds. The recommended value is
The Recache Delay

field on the
Configuration tab of
the AR System
options.)
300 (5 minutes).
Disable-Admin-Ops
Flag indicating whether administrative operations are

allowed on the server. Valid values:
F (Default) Disabled
T Enabled
If the Server Groups check box is selected, this
option is ignored. Server groups can be configured in
the BMC Remedy AR System Server Group
Operation Ranking form to make sure that only one
server performs the operation. See Configuring
server groups.
Disable-Alerts
Flag indicating whether alerts are sent when alert events

are created. Valid values:
T No threads are started in the alert queue, and
no alerts are sent.
F (Default) Alerts are enabled.
Changes to this setting do not take effect until the
server is restarted.
Disable-Archive
Switch that disables (T ) or enables (F ) the archive when

the server starts.
The Disable Admin

Operations field on
of the AR System
options.)
The Disable Alerts

field on the
the AR System
options.)
Maps to: The Disable

Archive field on the
the AR System
options.)
Disable-ARSignals
Page 1251 of 4705
Home
Option
Description
Maps to
Flag indicating whether automatic signals triggered by

changes to the following data on a server group's
The Disable
administrative server are disabled:

of the AR System
options.)
Archive definitions
Escalation definitions
ARSignals field on
The signals can be generated by arsignald or the

database. Signals triggered by changes to user,
licensing, and computed group information are not
disabled. Valid values:
T The specified signals are disabled.
F (Default) Automatic signaling remains in effect
for all object definition changes.
To send the disabled signals manually, use the
arsignal program (See arsignal.exe or arsignal. See
Configuring the server group signaling option.)
Disable-Audit-Only-Changed-Fields
Flag indicating whether to audit all records (T ), or to audit
The Disable Audit
only those records whose field values have changed ( F, the

default).
Only Changed Fields

field on the
the AR System
options.)
Disable-Client-Operation 2
Option that restricts time-consuming operations (such as

reporting) during busy times, improving overall performance
. The syntax is
Disable-Client-Operation: <tagNumberToDisable> [[<

startTime>]-[<stopTime>]] [<groupIDList>]
The tag number identifies the client whose

operations are restricted. It is defined in the ar.h file.
See the list at the end of this description.
(Optional) To specify start and stop times for the
restriction, enter them in 24-hour format ( hh:mm ).
The times are include times. For example, 00:00-13:
59 disables the operations from midnight until 1:59
P.M.
If you do not specify a start or stop time, the syntax
looks like this: Disable-Client-Operation: 2 18:0010
To disable operations from midnight until 6:00 A.M.,
enter this: Disable-Client-Operation: 2 -6:00 10
If no start and stop times are specified, the
operations are disabled all the time.
Page 1252 of 4705
Home
Option
Description
Maps to
(Optional) The groupIDList is a list of groups whose

users can run the operations during the specified
time period. For example, you can allow only the
administrator to run reports during busy hours. Enter
none, one, or multiple group IDs delimited by spaces
. For example, to exempt group 10, enter this:
Disable-Client-Operation: 1 13:00-17:59 10
If no groups are specified, all users are barred from
running the operations during the specified time
period. You can enter multiple
Disable-Client-Operation lines.
For more information on the list of Client types, see
List of Client Type ID.
Disable-Escalations
Disable-Non-Unicode-Clients
Flag indicating whether escalations are allowed on the
The Disable
server. Valid values: T and F (default). If the Server Group

Member check box is selected, this option is ignored.
Server groups can be configured in the BMC Remedy AR
System Server Group Operation Ranking form to make
sure that only one server performs the operation. (See
Configuring server groups.)
Escalations field on
Flag indicating whether Unicode servers can refuse

requests from non-Unicode clients (for example, not Mid
Tier 7.0.00). This option does not affect non-Unicode
servers. Valid values:
The Disable
T Unicode servers refuse requests from

non-Unicode clients.
F (Default) Unicode and non-Unicode clients can
contact Unicode servers.
Disable-User-Cache-Utilities

of the AR System
options.)
Escalations field on
of the AR System
options.)
Flag that prevents unauthorized users from using User

Cache commands. Valid values:
T The *arreload* and arcache utilities are
disabled for the AR System server.
F (Default) Cache utilities are enabled.
Display-General-Auth-Message2
Flag indicating whether to display a message when user

authentication fails. Valid values:
T (Default) A generic message is displayed for
user name and password errors:
ARERR 623 Authentication failed
ARERR9388Authentication failed
F Each authentication error displays a different
message:
ARERR 624 User account locked out
due to too many bad password
attempts
ARERR9381No such user is
registered with this server
Page 1253 of 4705
Home
Option
Description
Maps to
ARERR9382Invalid password or
authentication string for existing
user
This parameter can be used in conjunction with

Max-Password-Attempts. (See ar.cfg or ar.conf options
E-M.)
Distrib-Log-File
Full path name of the file to use if DSO server logging is on

(See Debug-mode).
Distributed-RPC-Socket
The BMC Remedy AR System server to use for the DSO

server. By default, the DSO server runs in queues like any
other user.
Obsolete. (See Assigning an RPC program number to DSO
.)
Domain-Name 2
New domain name portion of the fully qualified server name

. By default, a server determines the domain name from the
network interface. In rare cases, this method does not
produce the desired result because of unexpected network
card configurations. In those cases, you can use this option
to override the domain name derived from the network
interface.
DSO-Cache-Check-Interval
Number of seconds between occurrences of these

operations:
DSO checks for changes to the source and target
forms
By default, this option is set to 1800 seconds (30
minutes). The maximum value is 43200 seconds (12
hours).
DSO-Error-Retry-Option
DSO server retry behavior after an error:

0 (Default) Retry after standard connection and
transmission errors.
1 Never retry after any error.
2 Retry after every error.
3 Retry after standard connection and
transmission errors and after database errors.
DSO-Host-Name 2
Name to use for the From (source) server in distributed

mappings. This setting enables you to use an alias for the
From server in distributed operations.
DSO-Local-RPC-Socket
RPC program number that DSO uses. This setting is

optional.
The DSO Local RPC

Program Number
field in the DSO
Server area on the
the AR System
Page 1254 of 4705
Home
Option
Description
Maps to
Setting server
passwords, RPC
options, and plug-in
timeouts.)
DSO-Log-Level
Level of logging for all DSO logs (ardist.log,

ardist.log.default, ardist. poolName.log, and ardist.log.
poolName ):
0 Logs only errors. Includes contextual
information.
1 Logs errors and warnings. Includes contextual
information.
2 Logs errors, warnings, and other information to
provide a step-by-step record of DSO activities.
(See BMC Remedy Distributed Server Option logging and
Setting log files options.)
DSO-Log-Max-Backup-Index 2
Number of indexed backup files saved for each DSO Java

log file. If you do not specify a value for this option, 5
indexed backups are saved for each DSO Java log file.
DSO-Main-Thread-Polling-Interval
Interval at which the DSO server queries the distributed

pending queue for pending distributed items. Enter any
integer from 0(no polling) to 3600 seconds (1 hour).
DSO-Mark-Pending-Retry-Flag
Flag indicating whether to set the status of items in the

DSO distributed pending queue to Retry after an attempt to
perform the associated operation fails. (Failure must be due
to a recoverable error. Items that fail because of
nonrecoverable errors are removed from the queue.) Valid
values:
T (Default) Does not set the status to Retry.
Instead, the status remains set to New. Depending
on the number of pending items that the DSO server
processes, this setting might improve the server's
performance.
F Sets the status to Retry. Use this to differentiate
items in the queue that have never been processed (
status = New) from items that were processed but
failed because of recoverable errors (status = Retry).
Note: Regardless of this option's value, the pending
item is retried based on its retry configuration.
DSO-Max-Pending-Records-Per-Query
Maximum number of records in the Distributed Pending

form that DSO reads in a single database query. Minimum
value is 1. Maximum value is unlimited. If no value is
specified, the default is 1000.
DSO-Merge-DupID-Overwrite 2
The way the DSO server behaves when it finds a duplicate

request ID on the target server. Valid values:
Page 1255 of 4705
Home
Option
Description
Maps to
T Updates mapped fields and sets unmapped

fields to NULL.
F (Default) Updates only the mapped fields on the
target request.
DSO-Placeholder-Mode
Mode that disables the DSO server installed on the same

host as the AR System server. Use this when setting up a
DSO server outside a firewall to support an AR System
server running behind a firewall.
DSO-Polling-Interval
Interval (in seconds) at which the DSO server checks the

distributed pending queue for pending distributed items.
This is used as a backup when no signals are received
from workflow. The value can be any integer between 15
and 7200. By default, the backup polling interval is disabled
.
DSO-Source-Server
The AR System server for a DSO server to support when

that AR System server is different from the one installed
with the DSO server. Use this when setting up a DSO
server outside a firewall to support an AR System server
running behind a firewall.
Note: Use this entry to configure DSO for load balancing.
DSO-Supress-No-Such-Entry-For-Delete
Flag indicating whether to log AR System server error 302 (

entry does not exist in database) in the*arerror.log* file
when performing distributed delete operations. Valid values:
T Do not log ARERR 302 during distributed
deletes.
F (Default) Log ARERR 302 during distributed
deletes except when the DSO-Error-Retry-Option is
set to 2 (retry after every error).
Note: When this option is set to T, errors caused by
valid problems might also be omitted from the log.
DSO-Target-Connection
Information for the target BMC Remedy AR System server.
The Target
Use this format:DSO-Target-Connection:serverName:
connection settings
RPCNumber portNumber
tables field in the

DSO Server area on
of the AR System
Setting server
passwords, RPC
options, and plug-in
timeouts.)
DSO-Target-Password
Password used to access the target BMC Remedy AR

System server through the DSO server. Use this format:
DSO-Target-Password: serverName:encryptedPassword
DSO-Timeout-Normal
Page 1256 of 4705
Home
Option
Description
Maps to
Timeout (in seconds) that the DSO server applies during

communication with the AR System server. Enter an integer
between60 (1 minute) and 21600 (6 hours). If no value is
specified, the system uses the default timeout (120
seconds).
DSO-User-Password
Password for the local DSO server user.
ar.cfg or ar.conf options E-M

This section of the table includes the options for the ar.cfg (ar.conf) file that begin with the letters E
through M.
ar.cfg (ar.conf) file options (E-M)
Tips
text box.
For example, to search for the Escalation-Log-File parameter, select it from the
For example, to search for all Email parameters, type Email in the Option text box.
For example, to search for the parameters which have Security in the description,
type Security in the Description text box.
Option
Description
Email-Notify-From 2
Sender name to use for filter-generated email

notifications in which no subject is specified. The value
is limited to 29 characters.
Maps to
Page 1257 of 4705
Home
Option
Description
Email-Timeout2
Obsolete in version 5.1.0 and later.
Enable-Unlimited-Log-Line-Length
Flag indicating whether log files display complete lines

into log files or not. Values are:
Maps to
T AR System server logs complete lines into

log files without truncation.
F (Default) AR System server logs only 4093
characters per line, including the header
information.
For more information, see BMC Knowledge Base
article KA308638.
Encrypt-Data-Encryption-Algorithm
Integer indicating the encryption algorithm of the data

key. Use the following values.
Standard Security
1 56-bit DES using CBC mode (default)
Performance Security
2 128-bit RC4 key (default)
6 128-bit AES CBC key (FIPS noncompliant)
8 128-bit AES CBC key (FIPS compliant)
Premium Security
For more information, see the Encryption Security
section.
Encrypt-Public-Key-Algorithm
Integer indicating the encryption algorithm of the public

key. Values are
4 512-bit RSA key (default for Standard
Security)
5 1024-bit RSA key (default for Performance
Security)
6 2048-bit RSA key (default for Premium
Security)
section.
Encrypt-Public-Key-Expire
Integer specifying the life span (in seconds) of the

public key. At the end of the specified time, the key
expires, and the server generates a new key. The
default is 86400 seconds (24 hours).
Integer indicating whether encryption is on or off.

Values are
0 (Default) Optional: Clients with and without
encryption installed can communicate with the
server. Network traffic is encrypted only if the
Page 1258 of 4705
Home
Option
Description
Maps to
client supports the server encryption

configuration. Otherwise, network traffic is
exchanged in plain text.
1 Required: Only clients with encryption
installed can communicate with the server. The
encryption level installed on the client (standard
, performance, or premium) must be compatible
with the encryption algorithms used by the
server.
2 Disabled: Whether encryption is installed
on a client or not, communication with the
server is not encrypted. Network traffic is
section.
Encrypt-Session-Hash-Entries 2
Size of the hash table that holds the encrypted session

information. The default is 509; there is no maximum.
Encrypt-Symmetric-Data-Key-Expire
Integer specifying the life span (in seconds) of the data

key. At the end of the specified time, the key expires,
and a new key exchange occurs. The default is 2700
seconds (45 minutes).
Escalation-Log-File
Full path name of the file to use if escalation logging is

on (See Debug-mode).
Exception-Diagnostic-Option 2
Integer value controlling the diagnostic output when

the server crashes. Values are
0 AR_EXCEPTION_DIAG_ALL ; includes all
diagnostic output when an exception occurs.
1 AR_EXCEPTION_EXCLUDE_STACK ;
excludes the stack trace in the diagnostic output
when an exception occurs.
External-Authentication-Group-Mapping 2
Mapping of LDAP groups to BMC Remedy AR System

groups for external authentication. The value of this
option consists of one or more pairs of group names
separated by semicolons. For example:"LDAP-1" "
ARS-1";"LDAP-2" "ARS-2";"LDAP-3" "ARS-3" Use
mapping as an alternative to creating an BMC Remedy
AR System group corresponding to each LDAP group.
You can map each LDAP group to an BMC Remedy
AR System group (as in the example) or multiple
LDAP groups to a single BMC Remedy AR System
group. If you try to map a single LDAP group to
multiple BMC Remedy AR System groups, only the
first mapping expression is valid. This option can be
used with the
External-Authentication-Ignore-Excess-Groups
option.
External-Authentication-Ignore-Excess-Groups 2
Flag used by AR System during external

authentication. Values are
Page 1259 of 4705
Home
Option
Description
Maps to
0 (Default) Users are authenticated when a

match exists between every LDAP group to
which a user belongs and a corresponding
group in AR System.
1 Users are authenticated when any single
LDAP group to which a user belongs matches a
group in BMC Remedy AR System. Excess
LDAP groups are ignored.
This option can be used with the
External-Authentication-Group-Mapping option.
External-Authentication-Return-Data-Capabilities 2
Bit mask that specifies the return data capabilities for

the current AREA plug-in. This option does not control
the AREA plug-in; it merely describes the behavior of
the plug-in, enabling server optimization. Values are
0 (Default) The server tries to retrieve this
information from AREA.
Bit 1 (value = 1 ) No email address is
provided.
Bit 2 (value = 2 ) No notify mechanism is
provided.
Bit 3 (value = 4 ) No group identifiers are
provided.
7--The server potentially can reduce the
number of AREA related calls during notification
processing.
Bit 4 (value = 8 ) No license information is
provided.
Bit 5 (value = 16 ) No notification user
validation should occur. This enables the server
to avoid using AREA for notification user
validation and information retrieval. Use this
setting for sites using a form of AREA that
applies user names as email addresses and
where accessing an authentication database
provides no benefit.
External-Authentication-RPC-Socket
RPC socket number on which an external

authentication server awaits requests for
authentication. The default value is 0 (external
authentication is not used). The RPC program number
for the plug-in server is 390695.
External-Authentication-RPC-Timeout
RPC timeout (in seconds) used when calling the

authentication (AREA) server. The default value is 40
seconds.
External-Authentication-Sync-Timeout
Internal timeout (in seconds) that the BMC Remedy

AR System server uses to invoke the external
authentication server's AREANeedToSyncCallback()
function periodically. This function instructs the BMC
Remedy AR System server to renew its internally
stored user information in case the source used to
authenticate users is changed. A value of 0 means
Page 1260 of 4705
Home
Option
Description
Maps to
that the BMC Remedy AR System server does not

invoke the call to the AREA server. The default value
is 300 seconds.
Filter-Api-Timeout
Time limit (in seconds) for the Filter API RPC to

respond to the server's request before an error is
returned. The minimum value is 1. The maximum is
300. The default is 40.
Filter-Log-File
Full path name of the file to use if filter logging is on (

See Debug-mode).
Filter-Max-Stack
Maximum number of recursion levels allowed for an
The
operation. The data modification performed by an
Maximum
AR_FILTER_ACTION_FIELDP filter action might

trigger a second set, or level, of filters, one of which
might trigger a third level of filters and so on. This
option limits the number of times such recursion can
happen, preventing the server crash that would occur
if the recursion continued indefinitely. The default
value is 25.
Stack of
Maximum number of filters that the server executes for

a given operation. The default value is 10000.
The
Filter-Max-Total
Filters field in
the Filters
area on the
Advanced tab
of the AR
System
Administration
: Server
Information
form. (See
Setting
performance
and security
options)
Maximum
Filters for an
Operation
field in the
Filters area
on the
Advanced tab
of the AR
System
Administration
: Server
Information
form. (See
Setting
performance
and security
options)
Flush-Log-Lines
Flag indicating whether logged lines are buffered or

written directly to disc. Values are:
T (Default) Logged lines are written to disc.
F Logged lines are buffered.
Full-Text-Case-Option
Page 1261 of 4705
Home
Option
Description
Maps to
Flag indicating whether full text searching is case

sensitive or case insensitive. This setting affects all
The Case field

in the Filters
area on the
fields indexed for full text search and affects how the
indexes are built. Therefore, changes to this setting
FTS tab of the

AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options)
trigger an automatic re-index. Values are

0 Full text search is case sensitive
1 (Default) Full text search is case
insensitive
Full-Text-Collection-Directory 1
Location in the file system where search engine index
The FTS
files are stored.
Collection
Directory field
on the AR
System
Administration
FTS
Configuration
form and on
the FTS tab of
the AR
System
Administration
: Server
Information
form. (See
FTS tab
configuration
options and
FTS
Configuration
form in the AR
System
Administration
Console.)
Full-Text-Configuration-Directory
Location in the file system where search engine

configuration files are stored.
The FTS
Configuration
Note: If you change the directory in this option, update

the pluginsvr_config.xml file with the correct
directory path. This file is in ARSystemInstallDir\
pluginsvr\fts.
Directory field
on the AR
System
Administration
FTS
Configuration
form and on
the FTS tab of
the AR
System
Administration
: Server
Information
form. (See
FTS tab
Page 1262 of 4705
Home
Option
Description
Maps to
configuration
options and
FTS
Configuration
form in the AR
System
Administration
Console.)
Full-Text-Disable-Indexing
Flag indicating whether the server processes pending
The Disable
indexing tasks. Values are
Full Text
Indexer field
T Disable indexing. Pending indexing tasks

are recorded for processing later when indexing
is enabled.
F (Default) Do not disable indexing.
Full-Text-Disable-Searching
Flag indicating whether the server uses the full text

search engine for searching. Values are
T Disable the full text search engine. The
server uses the search capability of the
underlying database whether or not a user has
a full text license.
F (Default) Use the full text search engine.
on the FTS
tab of the AR
System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
The Disable
Full Text
Searching
field on the
FTS tab of the
AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Full-Text-Indexer-Log-File
Full path name of the file to use if full text indexer

logging is on (See Debug-mode).
Full-Text-Indexer-Recovery-Interval
Number of minutes that the server waits between
The Indexing
periodic attempts to index entries that failed to index

for an unexpected reason in a prior attempt. The
default value is 60 minutes.
Failure
Recovery
Interval field
on the FTS
tab of the AR
System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Full-Text-Match-Option
The way the server modifies qualifications from the

client. Values are
Page 1263 of 4705
Home
Option
Description
Maps to
0 Force leading and trailing wildcards.

1 Ignore leading and force trailing wildcards.
The Search
2 Ignore leading wildcards.

3 Remove leading and trailing wildcards.
on the FTS
tab of the AR
System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Options field
4 (Default) Leave query unchanged.
Full-Text-Search-Threshold
The maximum number of search results returned from
The Full Text
the search engine. The default value is 10,000. To limit
Search
the number of search results (because of constraints
Threshold
field on the
on the computer where the search engine is running),

reduce the threshold. If you change this option, you
must restart the BMC Remedy AR System server for
the change to take effect.
Full-Text-Search-Threshold-High
Full-Text-Search-Threshold-Low
FTS tab of the

AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
During the processing of search results, the server

combines results from subqueries to arrive at the final
result set. If the number of rows created during
processing exceeds this value, the server returns an
error message indicating the search is too complex.
The default value is 1,000,000.
The Complex
While processing search results, the server creates a

temporary table if the number of FTS matches reaches
this value. If the number of FTS matches is under this
value, the server uses the SQL IN operator for a query
on an existing table. The default value is 200.
The
Search
Threshold
field on the
FTS tab of the
AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Temporary
Table
Threshold
field on the
FTS tab of the
AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Page 1264 of 4705
Home
Option
Description
Maps to
Full-Text-Signal-Delay
(Server groups only) Number of seconds before a

signal is sent to the server that owns the full text
The Indexer
indexing operation (if no signal is pending). When a

server is not the owner of the full text indexing
Signal Delay
field on the
operation and generates indexing work, that server

signals the server that is the owner of indexing. To
FTS tab of the
Server Group
AR System
Administration
reduce the frequency of signals sent, the signaling is

conducted on a delayed basis. When indexing is
: Server
Information
generated, the server checks whether a signal is

pending. If a signal is pending, the server does not
form. (See
FTS tab
need to take any action. If a signal is not pending, the

server creates a pending signal to be sent in the
configuration
options.)
specified amount of time. If the full text signal delay

configuration value is changed, the duration of any
pending delay interval does not change. The change
takes effect the next time a delay interval is started.
The default number of seconds for
Full-Text-Indexer-Signal-Delay is 10 seconds. The
minimum is 1 second; there is no maximum.
GetListEntry-Server-Date-Format 2
Flag indicating where to format the GetListEntry date.

This option is used mainly for backward compatibility
purposes. Values are
T Format date on server.
F (Default) Format date on client.
Guest-Restricted-Read
Flag indicating whether guest users receive a
The Give
restricted read license when they log in to BMC

Remedy AR System. Values are
Guest Users
Restricted
Read field on
the
T
F
Configuration
tab of the AR
If this option is not specified, guest users receive a

read license.
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
GUID-Prefix 2
Character string used as a prefix for GUID strings

generated by filters.
Homepage-Form
Path to the systemwide default home page. This home

page is used only if
The current server is designated as the server
for the home page in the BMC Remedy AR
System User Preference form.
Or
The Default
Home Form
field on the
Configuration
tab of the AR
System
Administration
: Server
Information
form. (See
Page 1265 of 4705
Home
Option
Description
Maps to
The current server is designated as the home

page server on the General Settings page in
Setting
administrative
Mid Tier Configuration Tool (See Configuring

the General Settings page.)
options.)
And
No home page is specified in the BMC Remedy
AR System User Preference form.
Note: If the home page is deleted, this option is
cleared, and the default home page must be reentered
.
Informix-DBServer-Name 1
(Informix databases only) Name of the server where

the underlying database is located.
Informix-Relay-Module 1
(Informix databases only) Environment setting for the

path for the Informix relay module.
Informix-TBConfig 1
(Informix databases only) Name of the configuration

file for the underlying database. The default name is
onconfig.
Internal-User-Info-Hash-Lists2
Number of shared, linked lists that hold all user-related

information. This number must be a power of 2. The
default setting is 128. The minimum number is 2.
There is no maximum.
Note: BMC Remedy AR System does not verify that
this number is a power of 2. If the number is not a
power of 2, the AR System server might behave in
unexpected ways.
Internal-User-Instance-Timeout 2
Time, in minutes, that the AR System server waits

before removing inactive user instances from its
internal memory cache. Use this option in an LDAP
environment to reduce the frequency of checks against
an outside authenticator (if a user's record is in server
memory, the server does not need to check the user's
password outside the system). The default is 2 hours (
120 minutes), and the minimum is 30 minutes.
Note: This value must be greater than or equal to the
value of the Floating License Timeout on the AR
System Administration: Server Information form's
Timeouts tab (by default, 2 hours). If you specify a
value that is less than the Floating License Timeout,
you will not receive an error. Inactive user instances,
however, will not be removed in less than the time
specified by the Floating License Timeout. If you do
not set this option, the persistence of inactive user
instances is controlled by the Floating License Timeout
.
IP-Name
Option used to specify that a server has multiple

names. This option can appear in the configuration file
more than once. When checking workflow and
Page 1266 of 4705
Home
Option
Description
Maps to
connections against itself, the server compares its

server name, host name, IP aliases, and any names
specified by this option to the name passed to it. If the
name matches any of those names, the server
concludes that the workflow or connection is for itself.
This option can be used for servers with variable
length domains or for servers on computers with
multiple internet addresses. For example, to connect
to a computer named tix as tix,tix.company.com, or
tix.eng.company.com, an administrator would create
three IP-Name entries, one for each connection name.
To connect to a computer with multiple internet
addresses such as tix.company.com,
tix.biggercompany.com, and tix.evenbigger.com,
an administrator would create an IP-Name entry for
each of those addresses.
License-Timeout
Number of hours the BMC Remedy AR System server

waits before disconnecting inactive users. If a user is
holding a floating license, the system also frees the
license. The default value is two hours.
Locale-List
The installed language packs. Some sample values

are
de German
en English
es Spanish
fr French
it Italian
ja Japanese
ko Korean
pt_br Brazilian Portuguese
ru Russian
zh_cn Simplified Chinese
Localized-Messages-To-Cache
A semicolon-separated list of message numbers used

to modify the server's default caching behavior for
localized system messages.
To cache all localized system messages the first time
they are retrieved from the AR System Message
Catalog form (the default), do not use this option in the
configuration file.
To not cache any localized system messages, use this
option without any message numbers, for example:
Localized-Messages-To-Cache:
To restrict the caching of localized system messages
to a specific subset of message numbers, use this
option with a semicolon-separated list of message
numbers, for example:
Localized-Messages-To-Cache: 66;72;302;314
Localized-Server
Page 1267 of 4705
Home
Option
Description
Maps to
Flag indicating whether the server is running in

localized support mode. Values are
The Localize
Server field
on the
T Run in localized support mode, and use

localized messages if available.
F (Default) The server does not search for or
use localized strings.
Locked-Workflow-Log-Mode 2
Advanced tab
of the AR
System
Administration
: Server
Information
form. (See
Setting
performance
and security
options.)
Mode that causes the server to record locked workflow

actions in workflow logs. These actions are written as
encrypted strings.
Log-DSO-Errors-To-Form
Flag indicating whether to log failed pending

distributed operations to the Distributed Pending
Errors form. Values are
T Log errors to the form.
F Do not log errors to the form.
Log-DSO-Field-Values 2
Flag indicating whether to include a list of source entry

field/value pairs for errors and warnings in the DSO log
files when the DSO log level is set to Error or Warning.
Values are
T Include the list.
F Do not include the list.
Log-File-Append
Flag indicating whether to create a separate *.bak file

or to append to the existing log file. Values are
T Append new log information to the existing
file.
F (Default) Create a *.bak file.
Log-Form-Selected
Bitmask indicating the type of information to log in the

common log form (AR System Log:ALL). To activate
one bit, set this option to its value (values are listed
under the Debug-mode option). To activate two or
more bits, add their values, and set this option to the
total. For example, to activate bits 1 and 3, set this
option to 5 because bit 1 has a value of 1 and bit 3 has
a value of 4. To deactivate a bit, subtract its value from
the value of this option. This option does not apply to
the following bits because information about their
corresponding applications is not logged to a form:
Bit 8 (value = 128 ) for ARFORK.
Bit 16 (value = 32768 ) for the DSO server.
Page 1268 of 4705
Home
Option
Description
Maps to
Bit 17 (value = 65536 ) for Approval Server.

Bit 18 (value = 131072 ) for the plug-in server.
Log-To-Form
Bitmask indicating the information to log in predefined

forms (for example, AR System Log: API and AR
System Log: Filter). To activate one bit, set this option
to its value (values are listed under theDebug-mode
option). To activate two or more bits, add their values,
and set this option to the total. For example, to activate
bits 1 and 3, set this option to 5 because bit 1 has a
value of 1 and bit 3 has a value of 4. To deactivate a
bit, subtract its value from the value of this option. This
option does not apply to the following bits because no
log form is created for their corresponding applications
:
Map-IP-Address 2
IP address mappings that enable alerts to work

through firewalls when Network Address Translation (
NAT) is on. You must set up a mapping for each client
computer that has access through the firewall where
the client IP address is translated from an internal
address to a valid external address. In addition, a
mapping is required for the AR System server IP
address if the host where the server resides is also
translated. Here is a multiple line example:
Map-IP-Address: 123.45.67.89 10.5.119.83

Map-IP-Address: 123.45.55.90 10.26.55.65
Maximum number of requests returned by a search.

Because users can also specify the maximum number
of requests returned through Search Preferences in
the BMC Remedy AR System User Preference form,
the actual maximum is the lower of these values. The
default value is no server-defined maximum.
The Max
Entries
Returned by
GetList field
on the
Configuration
BMC recommends always setting a value for this

parameter as unqualified searches can yield enormous
results resulting in unpredictable system behavior.
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
Max-Log-File-Size
Page 1269 of 4705
Home
Option
Description
Maps to
Maximum size in bytes for system log files. If the

maximum is reached, the logging cycle restarts at the
beginning of the file, overwriting existing information.
The default value is 0 (no limit). This option does not
apply to the Arfork-Log-File.
Max-Log-History
Maximum number of backup (.bak) log files to be

allowed when the log file reaches the
Max-Log-File-Size value and a new log file is created.
By default, the number of backup log files allowed is 1
and the maximum number of backup log files allowed
is 999.
Max-Notify-Mail-Line-Len 2
Maximum number of bytes that can be in a line of a

mail notification.
Max-Password-Attempts
Maximum number of consecutive bad password retries
The Max
a user can make. If this option is set to 3, the user has

3 chances to log in. If all 3 attempts have bad
Number of
passwords, the user account is markedINVALID.

Values are 0 (which turns this feature off) and all
positive integers.
Attempts field
on the
Password
Configuration
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)

Display-General-Auth-Message. (See ar.cfg or
ar.conf options C-D. See also the description for error
624.)
Max-Recursion-Level
For forms that contain hierarchical data, such as

manager and employee relationships, the maximum
number of levels in the hierarchy that a recursive
query retrieves. Values are any integer greater than 0.
The default is 25. (See
ARGetListEntryWithMultiSchemaFields.)
The
Maximum
Depth for
Hierarchical
Query field on
the Advanced
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
performance
and security
options.)
Max-Vendor-Temp-Tables
Maximum number of temporary tables that can exist

on an AR System server for a single vendor form. The
The
ARGetListEntryWithMultiSchemaFields function
Vendor Temp
stores data from vendor data sources in these tables.

By default, only one temporary table can exist for each
vendor form. This setting applies to all vendor forms
Tables field
on the
Maximum
Advanced tab
of the AR
System
Page 1270 of 4705
Home
Option
Description
Maps to
on the server. It is overridden by the value of an

individual vendor form's Maximum Vendor Temp
Administration
: Server
Tables property. Enter any integer greater than 0. (See

ARGetListEntryWithMultiSchemaFields.)
Information
form. (See
Setting
performance
and security
options.)
Maximum-Concurrent-Client-Managed-Transactions
Maximum number of concurrent client-managed

transactions. The default is 10, and the maximum
value you can enter is 100.
Mid-Tier-Service-Password
Password that administrators use to access the mid

tier.
The Mid-Tier
Administrator
Password
field on the
Connection
Settings tab
of the AR
System
Administration
: Server
Information
form. (See
Setting server
passwords,
RPC options,
and plug-in
timeouts.)
Minimum-API-Version
Minimum-CMDB-API-Version
Oldest API version with which the server

communicates. The default value is 0, which means
that the server communicates with all API versions. If
the client's API version is less than the specified value,
the server refuses to talk with the client, and the client
receives a decode error. (A AR System client is any
program that accesses the AR System server through
API calls, for example, BMC Remedy Developer
Studio, plug-ins loaded by the plug-in server, and so
on.)
Maps to: The

Minimum API
Version field
on the
Configuration
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
Oldest CMDB API version with which the server

communicates. The default value is 3. If the version of
a CMDB call is less than the specified value, the
server refuses the call. This option is independent of
the Minimum-API-Version option.
Multiple-ARSystem-Servers
Flag indicating whether other AR System servers can

run on this server's host computer. Values are
T (Default) Other servers can run on this
server's host computer.
Page 1271 of 4705
Home
Option
Description
Maps to
F Other servers cannot run on this server's

host computer.
To run multiple servers on the same host computer,
this option must be set to T in the configuration file of
each server.
Note: To add a 7.5.00 or later AR System server to an
environment in which a 7.1.00 or earlier AR System
server is already installed, you must first change the
value of this option from F toT. Otherwise, the 7.5.00
or later server installation will fail.
Multiple-Assign-Groups
Flag indicating whether multiple assignee groups can

be stored in row-level security field ID 112. This
enables users from multiple groups to access the
same request. In the past, only one group could be
stored in Field 112. Values are
The Enable
Multiple
Assign
Groups field
on the
T (Default) Allow multiple groups in field ID

112.
F Do not allow multiple groups in field ID 112
.
Configuration
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
2. Options you cannot set or view using the AR System Administration: Server Information form
ar.cfg or ar.conf options N-R

This section of the table includes the options for the ar.cfg (ar.conf) file that begin with the letters N
through R.
ar.cfg (ar.conf) file options (N-R)
Tips
text box.
For example, to search for the Next-ID-Block-Size parameter, select it from the
Page 1272 of 4705
Home
For example, to search for all ID parameters, type ID in the Option text box.
For example, to search for the parameters which have Configuration in the
description, type Configuration in the Description text box.
Option
Description
Next-ID-Commit 2
Flag indicating whether to perform a new commit transaction when
Maps to
the system generates the next ID for a record in the database.

Values are
T Perform a new commit transaction. To increase
efficiency and for debugging, use this value.
F (Default) Include the transaction to generate the next ID
in the create entry transaction.
Note: Next-ID-Block-Size replaced Next-ID-Commit, but
Next-ID-Commit is available for backward compatibility.
Next-ID-Block-Size
Option that allocates next IDs in blocks instead of one at a time.

Allocating in blocks increases performance during create operations.
Values are any positive number up to 1000. The default value is 25.
(A value of 1 disables the feature.) You can also disable it by
removing it from the configuration file. You do not need to restart the
server for the change to take effect.
This setting is always disabled on the Distributed Pending form so
that DSO can operate correctly.
Warning: The use of this option might result in unpredictably large
The Next Request

ID Block Size field
on the
Configuration tab
of the AR System
Administration:
Server Information
form. (See Setting
administrative
options.)
Next-ID sequence gaps. The likelihood of this occurring increases

with the use of multiple servers that share a database. The BMC
Remedy AR System server will not malfunction because of this gap,
and it should not be considered a defect.
Notification-Web-Path
Base URL that appears in email notifications. If this option is not

used, the Default-Web-Path option is used. (Notification-Web-Path
is available because the Default-Web-Path is specified for other
applications such as Flashboards, and it might be different from the
mid tier web path for opening requests in a notification.)
Num-Preload-Schema-Segments
Total number of preload segments loaded by the preload threads

when preload threads are configured. SeeSetting the Preload Tables
Configuration option.
The Number of
Preload Segments
field on the
Advanced tab of
the AR System
Administration:
Page 1273 of 4705
Home
Option
Description
Maps to
Server Information
form. (See Setting
performance and
security options.)
Num-Preload-Threads
Number of preload threads to use when preload threads are

configured. A value of 0 indicates that preload threads are not used.
The maximum value is 30 or twice the number of preload segments,
whichever is lower. See Setting the Preload Tables Configuration
option.
The Number of
Preload Threads
field on the
Advanced tab of
the AR System
Administration:
Server Information
form. (See Setting
performance and
security options.)
Oracle-Bulk-Fetch-Count 2
Number of data rows simultaneously fetched from the result set

when an Oracle database is queried. The minimum is 1, the
maximum is 100, and the default is 50. The higher the value, the
more memory is used during data retrieval.
Oracle-Clob-Storage-In-Row
(Oracle databases only) Flag controlling Oracle CLOB storage.

Values are
T CLOBs are created "in row." In-row CLOBs can degrade
CPU performance.
F (Default) CLOBs are created "out row." Out-row CLOBs
can cause the database to grow rapidly.
Oracle-Cursor-Sharing 2
Database setting that matches the setting in the Oracle initialization

file (initARS.ora if the BMC Remedy AR System database SID is
ARS). Values are
FORCE Use this value if the initARS.ora file includes the
following line:CURSOR_SHARING=FORCE.
SIMILAR Use this value if your Oracle database is set for
SIMILAR.
EXACT Use this value if your Oracle database is set to
perform case insensitive search (by setting the value of
Db-Case-Insensitive to T, in the ar.cfg (ar.conf) file).
For more information, see Db-Case-Insensitive.
Oracle-Dblink-Character-Set2
Option that enables BMC Remedy AR System to support remote

databases with different character sets. You can enter this option
multiple times in the configuration file for multiple view forms on
different remote databases with different link names. The syntax is
Oracle-Dblink-Character-Set: linkName charset
linkName should match LINK in

OWNERNAME.TABLENAME@LINK in the table name of the
view form on the remote database.
charset can be utf-8, utf-16, ucs-2, euc, and shift-jis.
For example:Oracle-Dblink-Character-Set: eng.remedy.com
shift-jis For information about view forms, see Security
administration.
Page 1274 of 4705
Home
Option
Description
Oracle-Search-On-Clob 2
Flag indicating whether CLOBs can be searched. Values are
Maps to
T (Default) Allow searches on CLOBs. When a search is

performed, the qualification can include all the diary and
character fields stored in the database as CLOB columns.
Including these fields affects performance, and indexes
cannot be used for this type of query.
F Searching on diary and character fields stored in the
database as CLOB columns returns an error.
CLOBs can use the operator LIKE, but not =.
Oracle-SID 1
(Oracle databases only) System ID for the underlying database.
Oracle-Two-Task 1
(Oracle databases only) Two-task environment setting for the

underlying database.
Overlay-mode2
Specifies the default overlay group for the server. Clients that use
the default overlay group (all clients other than Developer Studio) will
retrieve and use objects from the default group.
0 Clients will only retrieve and operate on origin objects.
Custom objects and overlays of origin objects will not be
visible to clients, and the server will execute only origin filters
and escalations. In this mode, customizations are ignored.
1 Clients will retrieve non-overlaid origin objects, overlays,
and custom objects. All customizations will be visible, and the
server will execute non-overlaid escalations, overlays of
escalations, and custom escalations.
See Ignoring overlay and custom objects at runtime.
Per-Thread-Logging
Flag indicating whether to create per-thread log files. Values are

T Create per-thread log files.
F (Default) Do not create per-thread log files.
Plugin 2
File name of one or more plug-ins that the plug-in server loads. The
file name of the DLL or shared object is provided. The file name
might be an absolute file name or might be relative to the BMC
Remedy AR System installation directory. Add as many entries for
this option to the server configuration file as needed, but specify only
one file name in each option.
Plugin-ARDBC-Threads 2
Number of threads dedicated to handling ARDBC requests from the

BMC Remedy AR System server. You must specify a minimum
number. Optionally, you can also specify a maximum number (the
plug-in server increases the number of threads for a plug-in as
needed up to the specified maximum). The syntax is
Plugin-ARDBC-Threads: <minimumNumberOfThreads>[<
maximumNumberOfThreads>]
By default, 1 thread is initiated if this option is not specified.

Plugin-AREA-Threads 2
Page 1275 of 4705
Home
Option
Description
Maps to
Number of threads dedicated to handling AREA requests from the

BMC Remedy AR System server. You must specify a minimum
number. Optionally, you can also specify a maximum number (the
plug-in server increases the number of threads for a plug-in as
needed up to the specified maximum). The syntax is
Plugin-AREA-Threads: <minimumNumberOfThreads> [<


Plugin-Disable-Remote 2
Flag indicating whether the plug-in server accepts calls from remote
servers. Values are
T The plug-in server accepts calls only from an BMC
Remedy AR System server running on the local computer.
F (Default) The plug-in server accepts call from remote
servers.
Plugin-Filter-API-Threads 2
Number of threads dedicated to handling BMC Remedy AR System

Filter API requests from the BMC Remedy AR System server. You
must specify a minimum number. Optionally, you can also specify a
maximum number (the plug-in server increases the number of
threads for a plug-in as needed up to the specified maximum). The
syntax is
Plugin-Filter-API-Threads:
<minimumNumberOfThreads> [

Plugin-Log-File
Full path name of the file to use if plug-in logging is on (see

Debug-mode).
Plugin-Log-Level
Option that specifies the type of information printed to plug-in log

files. Values are
10000 No information (ARPLUGIN_OFF ).
1000 (Default) Only severe messages (
ARPLUGIN_SEVERE ).
900 Severe and warning messages (
ARPLUGIN_WARNING ).
800 Status, severe, and warning messages (
ARPLUGIN_INFO ).
700 Configuration, status, severe, and warning messages (
ARPLUGIN_CONFIG ).
600 Internal exceptions (ARPLUGIN_FINE ).
500 Trace logs that log tasks as they are executed (
ARPLUGIN_FINER ).
400 Code-level information (ARPLUGIN_FINEST ).
100 All log information (ARPLUGIN_ALL ).
Plugin-Loopback-RPC-Socket
RPC socket number for the private server queue to which loopback
plug-in API calls should be directed. Values are in the following
ranges:
The Plugin
Loopback RPC
Program Number
Page 1276 of 4705
Home
Option
Description
Maps to
390621-390634
390636-390669
390680-390694
Loopback plug-ins (such as the Report Creator plug-in) that call back
into BMC Remedy AR System use this number to determine the
queue to request. By default, plug-in API calls are directed to a
queue that corresponds to the call type. To be effective, the server
must be configured to have a designated private queue for this
option.
Plugin-Password
field on the Ports

and Queues tab of
the AR System
Administration:
Server Information
form.
Plug-in password. If this option is specified, the plug-in server

accepts connections only from BMC Remedy AR System servers
whose Server-Plugin-Target-Password option is set to the same
password. If this option is not specified, the plug-in server accepts
connections from BMC Remedy AR System servers that are not
configured to use a plug-in password.
Plugin-Path 2
Search path used to load a plug-in. The path is appended to the

current value of LD_LIBRARY_PATH (AIX, Linux, Oracle Solaris),
SHLIB_PATH (HPUX), or PATH (WINNT). Multiple paths can be
specified for this option; each path is appended in the order it
appears in the configuration file. The syntax is
Plugin-Path:
<pathName> [<delimiter>]\[<pathName>]
Insert no spaces between the delimeter and the path. For example:
UNIX
Plugin-Path: /usr/ar/bin:/usr/ar/common/xyz
Windows
Plugin-Path: C:\Program Files\AR System\arserver;

C:\Program Files\BMC Remedy AR System\common\xyz
Plugin-Port 2
The port number on which the plug-in server waits for incoming
requests.
Preference-Server-Option
Option that specifies whether users must use centralized

preferences. Values are
1 Users can choose to use a preference server if one is
available.
2 Users must use the specified preference server.
3 Users must use a preference server, but they cannot use
this server as a preference server. If users choose a server
that is not a preference server, a warning is returned.
Preload-At-Init-Only
Flag indicating when preload threads (if configured) are used. Values
are
T Preload threads are used only during server startup.
The Preference
Server Option field
on the Advanced
tab of the AR
System
Administration:
Server Information
form. (See Setting
performance and
security options.)
The Preload
Tables At Init Only
field on the
Advanced tab of
Page 1277 of 4705
Home
Option
Description
F (Default) Preload threads are used whenever the cache
is loaded from the database.
For information about how to determine whether to use preload
threads, see Setting the Preload Tables Configuration option.
Private-RPC-Socket
RPC program number that determines the type of queue to which

requests are routed and the number of threads running on that
queue.
Maps to
the AR System
Administration:
Server Information
form. (See Setting
performance and
security options.)
The Server Queue
field on the Ports
and Queues tab of
the AR System
Administration:
Server Information
form. (See Setting
ports and RPC
numbers.)
Private-RPC-Socket (for debug

queue)
Option that designates debug queues. A debug queue is a type of

private queue used by the BMC Remedy AR System Workflow
Debugger. To make any private queue a debug queue, use this
syntax:Private-RPC-Socket: rpcNumberDebug For example:
Private-RPC-Socket: 390666 Debug Alternatively, you can make a
private queue a debug queue by selecting its Debug check box in
the list of queues in the Ports and Queues tab of the Administration
Console.
RE-Log-File-Location 2
Location of the Reconciliation Engine log file.

For more information on modifying the reconciliation engine system
parameters, see Configuring Reconciliation Engine system
parameters.
Read-Only-Tran-Off 2
Option that causes BMC Remedy AR System not to create database

transactions when only reading data.
The default value is (T) true.
This setting is applicable for SQL Server and Sybase databases only
.
Record-Object-Relationships
Flag indicating whether the BMC Remedy AR System server records

the relationships between workflow objects.
Note: If using a server group, all servers within the same server
group must have the same setting for this option. If they do not, the
servers in the group inconsistently populate and un-populate the
object relationship database should they be the highest ranked
server for the Administration operation when they are restarted. Only
the highest ranked server for the Administration operation in the
server group will perform the required object relationship actions
The Record Object

Relationships field
on the
Configuration tab
of the AR System
Administration:
Server Information
form. (See Setting
administrative
options.)
when restarted.
Values are
T The server creates entries in a database table to track
the relationships between many types of workflow objects.
Page 1278 of 4705
Home
Option
Description
Maps to
When you set this option to T and restart the server, it records the
relationships of all server objects before it accepts connections from
clients. Therefore, the first time you restart the server after selecting
this option, you cannot connect to the server with any clent for a
period of time, depending on how many objects are defined on the
server. With a large number of objects, such as with an ITSM
application installed, this could take as long as an hour depending
on the performance of the database. (Subsequent server startups
are not affected by this setting.) When you can connect, the
recording of object relationship data is complete.
F (Default) The server does not record relationships.
When you set this option to F or remove it and restart the server, all
the recorded relationships are removed from the database. You must
restart the BMC Remedy AR System server before a change to this
option takes effect.
Note: BMC recommends that you set this option by using the
Record Object Relationships option on the Configuration tab of the
BMC Remedy AR System Administration: Server Information form
instead of setting it manually in the configuration file. (See Viewing
and sorting related objects.)
Record-Server-Events
Server events to log in the Server Events form, which makes

server-related changes available to workflow and API programs.
Enter the following values, separated by semicolons, for the events
to record.
1 Form
2 Field
3 Menu
4 Filter
5 Import
6 Active link
7 Escalation
8 View
9 Container
10 User
11 Group
12 Server setting
14 Archive
15 Server group actions
For example:Record-Server-Events: 4;8;9;12;14; For information
about the Server Events form, viewing recorded server events, and
using server events in workflow, see Understanding the Server
Events form.
Register-With-Portmapper
Flag that prevents the BMC Remedy AR System server from
The Register with
registering with a portmapper. Use this feature in conjunction with

setting specific ports to enable you to run servers on computers that
Portmapper field
on the
do not have a portmapper. Values are
Configuration tab
of the AR System
Administration:
Server Information
T (Default) Register with portmapper.

F Do not register with portmapper.
Page 1279 of 4705
Home
Option
Description
Maps to
No more than one server should try to register with AR System

Portmapper in an environment with multiple servers on one
form. (See Setting

ports and RPC
computer.
numbers.)
Registry-Admin-Password
Password of the BMC Atrium Web Services Registry admin user.

Used by workflow for the BMC Remedy AR System Web Services
Registry form.
Registry-Admin-User
User name of the BMC Atrium Web Services Registry admin user.
Used by workflow for the BMC Remedy AR System Web Services
Registry form.
Registry-Location
URL of the BMC Atrium Web Services Registry. Used by workflow

for the BMC Remedy AR System Web Services Registry form.
Remedy-App-Service-Password
Encrypted password that AR System application services such as
The Application
Approval Server use to access the BMC Remedy AR System server.
Service Password
field on the
Connection
Settings tab of the
AR System
Administration:
Server Information
form. (See Setting
server passwords,
RPC options, and
plug-in timeouts.)
Required-Field-Identifier
Character to add to the label of a field whose entry mode is Required

. The default is an asterisk.
The Required Field

Identifier field on
the Configuration
tab of the AR
System
Administration:
Server Information
form. (See Setting
administrative
options.)
Required-Field-Identifier-Location
Position to add the character that identifies a Required field. Values

are
0 Add the character to the beginning of the field label.
1 (Default) Add the character to the end of the field label.
Restrict-Log-Client-Type
The Required Field

Identifier field on
the Configuration
tab of the AR
System
Administration:
Server Information
form. (See Setting
administrative
options.)
A list of semicolon-separated client types (or IDs if the client type is

not known). Restricts logging only for specified client types.
For example, Mid-tier;Developer Studio;Remedy Administrator
Restrict-Log-RPC-Queue
Restrictions are applied to the API, SQL, and Filter logs only for
specified RPC Queues.
Page 1280 of 4705
Home
Option
Description
Maps to
For example, 390600;390680;390620

Restrict-Log-Users
A list of semicolon-separated user names. Restricts the logging only

for specified users.
For example, Allen;Mike
Restrict-Logging
Controls which type of logging restriction is enabled. The value of

the Restrict-Logging parameter depends on the combination of
logging restrictions that you select.. Possible values of the restriction
parameters are as follows:
Users 1
Client Type 2
RPC Queues 8
You can have combinations of Users, Client Type and RPC Queues
restrictions. For example, if you select Users and Client Type
restrictions, the value of the Restrict-Logging parameter is set to 9 (1
+8).
Notes:
The default value of Restrict-Logging parameter is 0.
The Restrict-Logging parameter has an additional reserved
value of 4.
RPC-Non-Blocking-IO 2
Flag that enables BMC Remedy AR System on compliant systems to

receive remote procedure calls in a nonblocking mode. The mode
prevents
Remote attackers from disabling RPC services.
Invalid or corrupt packets from temporarily disabling the
arserverd process. Values are
T Run in RPC nonblocking mode. The system can process
multiple headers at the same time.
F (Default) The server must receive an entire RPC header
before processing a different one.
To make value changes take effect, restart your AR System server.
Windows and Linux operating systems do not support this feature.
Important: To enable your system to use this feature, you must
install the following patches. If these patches are not installed, you
see an error message or most of your RPC calls are blocked.
HP
PHNE_29210 - HPUX 11.0 or later
PHNE_29211 - HPUX 11i or later
Solaris
108993-38 - Solaris 8 or later
113319-19 - Solaris 9 or later
IBM Does not specify a patch number. Multiple file sets might be
required. (If you do not obtain an IBM patch, your server might
crash.)
Page 1281 of 4705
Home
Option
Description
Maps to
Fix for Authorized Problem Analysis Report (APAR) IY61602 AIX 5.3 or later
Fix for APAR IY61409 - AIX 5.2 or later
ar.cfg or ar.conf options S-Z

This section of the table includes the options for the ar.cfg (ar.conf ) file that begin with the letters
S and Z.
ar.cfg (ar.conf) file options (S-Z)
Tips
text box.
For example, to search for the SCC-Enabled parameter, select it from the Option
list, or type the parameter name in the Option text box.
For example, to search for all SCC parameters, type SCC in the Option text box.
For example, to search for the parameters which have NOLOCK in the description,
type NOLOCK in the Description text box.
Option
Description
Maps to
Save-Login
Flag indicating whether users must log in to

client tools. This option enables users to save a
previous login of their choice. Values are
0 (Default) Login is controlled by user
.
Page 1282 of 4705
Home
Option
Description
Maps to
1 Do not force a login controlled by

the administrator.
2 Force a login controlled by the
administrator.
This option does not apply to the mid tier.
SCC-Comment-Checkin
Flag indicating whether a source code control

integration requires you to enter a comment at
checkin. Values are
0 (Default) No comment is required.
1 A comment is required.
SCC-Comment-Checkout

integration requires you to enter a comment at
checkout. Values are
SCC-Enabled

system is being used with BMC Remedy AR
System. Values are
0 (Default) Source code control
system is disabled.
1 Source code control system is in
use.
SCC-Integration-Mode
Flag indicating the level of source code control

integration. Values are
0 (Default) Advisory level.
1 Enforced level.
SCC-Provider-Name
Name of the source code control provider. For

example: Visual Source Safe.
SCC-Target-Dir
Character string for the source code control

system target directory. If none is present, this
value is NULL. This string is limited to 255
characters.
Select-Query-Hint 2
Text to use in a query hint in the WITH clause

of a SELECT statement when queries are
supplied to Microsoft SQL Server databases.
This option works only for queries triggered by
GLE,GLEWF, and GME API calls. If this option
is an empty string or is not present, no WITH
clause is generated. To determine the
appropriateness of using this feature in your
environment, consult your SQL Server
documentation. This option is commonly used
with a NOLOCK setting for allowing queries to
execute without being blocked by simultaneous
Page 1283 of 4705
Home
Option
Description
Maps to
updates, thereby improving performance. For

example, to allow SQL Server to read data
being updated and avoid blocking, use this
syntax:Select-Query-Hint: NOLOCK
Server-Connect-Name 2
Name of the computer where the AR System

server is installed. By default, a server in a
server group uses a fully qualified server name
with domain to identify itself. Others servers in
the group use this name to communicate. To
change the server name, add this option to the
configuration file:
Server-Connect-Name: <myComputerName.
Server-Connect-Name: <
myComputerName.domain.com>
If a common server alias is specified, this

option is required.
This name must be resolvable by DNS and is
used exactly as specified. (See Configuring
server groups.)
Server-directory1
Full path name of the AR System data directory

. This directory contains support and log files
for the AR System server.
Server-Group-Email-Admin-Port 2
Port number (RMIPort ) for email

administration in Email Engine. If RMIPort is
different from the default (1100 ), set this option
to the new, port number to enable the server to
communicate email administration information
to Email Engine during server group processing
. For example, in a single Email Engine
configuration, use this syntax:
Server-Group-Email-Admin-Port: 2020
If multiple Email Engines are configured for the

server, each engine must have a unique
RMIPort. For a multiple Email Engine
configuration, use semicolons to separate the
RMIPort numbers. For example:
Server-Group-Email-Admin-Port: 2020;2030
;2040
Server-Group-Flashboards-Admin-Port 2
Port number (RMIRegistryPort ) for

Flashboards administration in the Flashboards
server. If the default Flashboards port number
is changed, set this option to the new port
Page 1284 of 4705
Home
Option
Description
Maps to
number to enable the server to communicate

Flashboards administration information to the
Flashboards server during server group
processing. For example:
Server-Group-Flashboards-Admin-Port: 202
1
Server-Group-Log-File
Name and location of the server group trace

log file. The default name is arsrvgrp.log. For
example: Server-Group-Log-File: c:\temp\
servgroup.log
Server-Group-Member
Flag indicating whether the server is a member
The Server
of a server group. Values are T and F (default).
Group
Member field
on the
Configuration
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
Server-Group-Signal-Option 2
Method that a server in a server group uses to

notify other members of the group about object
definition cache changes. Values are
T The server uses arsignald to notify
other members about all object definition
cache changes.
F (Default) The server uses a
combination of signaling and database
posting to indicate that definition
changes have occurred. The database
postings are read by other servers in the
group at their preset check intervals.
Because an intentional delay is used to
avoid multiple recaches, the servers do
not recache until after a check interval
cycle that has no new recache signals.
The combined signaling and database posting
method reduces server activity but does not
notify other servers as quickly as the allarsignald method. (See Configuring the server
group signaling option.)
Server-Name
Page 1285 of 4705
Home
Option
Description
Maps to
An alias that is always interpreted as the

current server. This option is used in multiple
server installations to differentiate servers. In a
server group, Server-Name refers to the load
balancer name.
If you specify a value for this option, enter the
value after the -h option when you use the
arreload command-line utility. Otherwise,
arreload uses the default server name rather
than the name specified by this option. Do not
specify a fully qualified name for this option.
For example, use alpha instead of
alpha.remedy.com.
Note: If this server belongs to a server group
and you use a common server alias, you must
also specify the Server-Connect-Name option.
(See Server-Connect-Name.)
Server-Plugin-Alias 2
Alias of a plug-in server. When the BMC

Remedy AR System server calls a plug-in
server, it must determine whether the plug-in
server name is an alias. Aliases can direct the
BMC Remedy AR System server to access a
plug-in server running on a different host or
listening at a specified port number. The syntax
is
Server-Plugin-Alias: <aliasName> <

realName> <hostName>[:<portNumber>]
Workflow (that is, references to AR Filter API

and ARDBC plug-ins) references a plug-in
name. This name can be an alias. This enables
you to run a plug-in on a remote host or to run
more than one instance of a plug-in on a host.
For example, to run the RMDY.ARDBC.XML
plug-in on the remote host foo at port number
12345, add the following entry to the AR
System server configuration file:
Server-Plugin-Alias: RMDY.ARDBC.XML
RMDY.ARDBC.XML foo:12345The alias and
real plug-in names can be identical if you run
the plug-in on a remote host. To run more than
one instance of the plug-in on the same or
different hosts, create different aliases that
reference the same plug-in on its respective
hosts.
Number of seconds in which the plug-in server

must respond to a call before an error is
returned. The minimum value is 0. The
maximum is 600. The default is 60.
Server-Plugin-Target-Password
Page 1286 of 4705
Home
Option
Description
Maps to
Encrypted password used to call a plug-in

server. The BMC Remedy AR System server
uses this password whenever it communicates
with a plug-in server running on the specified
host and port. The syntax is {{
Server-Plugin-Target-Password: <hostName>:
<portNumber>: <encryptedPassword>
For server-side table fields, the number of

requests (or size of the chunk) that the server
The Server
retrieves at one time from the database and

stores in memory to process during filter or
Chunk Size
field on the
filter guide actions. The server then retrieves,

stores, and processes the next chunk until all
Configuration
requests are processed. The value 0 causes

the server to retrieve an unlimited number of
requests. The default is 1000 requests.
Specifying a lower value causes the server to
process smaller chunks, which reduces server
memory use but results in slower processing
because the server must access the database
many times, especially for large tables.
Specifying a higher value causes the server to
retrieve and process large chunks of data and
access the database fewer times. This results
in improved performance at the cost of
increased memory use.
Server-Stats-Rec-Interval
Interval (in seconds) at which the server

records server statistics. The default is 60
seconds.
Table Field
tab of the AR
System
Administration
: Server
Information
form. (See
Setting
administrative
options.)
The
Recording
Interval field
on the Server
Statistics tab
of the AR
System
Administration
: Server
Information
form.
Server-Stats-Rec-Mode
Server statistics recording mode. This option

determines what information is recorded in the
server statistics form. Values are
The Server
Recording
Mode field on
the Server
0 (Default) Recording is off.

1 The server records only cumulative
queue statistics (the sum of all the
individual queue statistics).
2 The server records both cumulative
and individual queue statistics. One
entry is written for the cumulative
statistics and a separate entry is written
for each queue.
Statistics tab
of the AR
System
Administration
: Server
Information
form.
To see the statistics, open the Server Statistics

form. (See Server statistics for baseline data.)
Page 1287 of 4705
Home
Option
Description
Maps to
Set-Process-Timeout
Number of seconds the BMC Remedy AR

System server waits before ending a Set Fields
process that did not finish. Values are 1
through 60. The default value is 5.
SQL-Log-File
Full path name of the file to use if SQL logging

is on (See Debug-mode).
SQL-Secure-Connection
(Microsoft SQL Server only) Flag indicating the

type of authentication to use to connect BMC
Remedy AR System to a Microsoft SQL Server
database. Values are
T Windows Authentication
F SQL Authentication
SQL-Server-Set-ANSI-Defaults 2
Option that causes the server to issue a SET

ANSI_NULLS ON command.
Submitter-Mode
Flag indicating whether the Submitter field can

be changed and whether the submitter of a
request must have a write license to modify it.
Values are
1 Locked mode. The Submitter field
cannot be changed after a request is
submitted. If the Submitter group has
change permission, the request can be
modified by submitters with a read or
write license but not by users with a
restricted read license.
2 (Default) Changeable mode. The
Submitter field can be changed after a
request is submitted. If the Submitter
group has change permission, the
submitter must have a write license to
modify the request.
Suppress-warnings 2
A series of zero or more message numbers (

separated by spaces) that identify informational
or warning messages that the system should
suppress. Only server warnings and notes can
be suppressed.
Sybase-Character-Set 1
(Sybase databases only) Alternative character

set to use for communications between BMC
Remedy AR System and the underlying
database.
Sybase-Server-Name 1
(Sybase and Microsoft SQL Server only)

Logical server name of the underlying database
. The default value is SYBASE.
System-Logging-Options 2
Bitmask that sets logging options for the

operating system. Values are
Page 1288 of 4705
Home
Option
Description
Maps to
0 (Default) Use normal operating

system logging.
Bit 1 (value = 1 ) Suppress logging to
the operating system log file.
System-Messages-Displayed
Flag to specify whether system messages

appear in the prompt bar or a pop-up box.
Values are
0 (Default) Notes and warnings
appear in the prompt bar, but errors will
1 All system messages willl appear in
the prompt bar.
2 No messages will appear in a
prompt bar. All messages will appear in
a pop-up box.
Alternatively, you can specify how system
messages appear by changing the value in the
Use Prompt Bar For field on the Configuration
tab of the Server Information form.
TCD-Specific-Port
TCP port for the arserver process. If this option

is not set, the dispatcher is randomly assigned
to an available port. (TCD stands for
transaction control daemon.)
The Server
TCP/IP Port
field on the
Ports and
Queues tab of
the AR
System
Administration
: Server
Information
form. (See
Setting ports
and RPC
numbers.)
Thread-Log-File
Full path name of the file to use if thread

logging is on (See Debug-mode).
Track-Admin-Op-Progress 2
Flag indicating whether the BMC Remedy AR

System server populates progress information (
if any) during long-running administrative
operations, such as definition imports.
T Track progress.
F (Default) Do not track progress.
To retrieve the progress information, clients
can use the GetServerInfo function with the
AR_SERVER_INFO_ADMIN_OP_PROGRESS
request tag.
Two-Digit-Year-Cutoff 2
Integer that specifies the cutoff year for

interpreting a two-digit year as a four-digit year.
For example, if the two-digit cutoff year is 2040:
Page 1289 of 4705
Home
Option
Description
Maps to
Two-digit years fall between 1941 and

2040.
1/1/55 is interpreted as 1/1/1955.
If a two-digit year cutoff is not specified, a
rolling two-digit year is used: Two-digit years
are the years between the current year plus 29
years and the current year minus 70 years. For
example, if the current year is 2002, two-digit
years are the years between 1922 and 2031.
Use-FTS-In-Workflow
Use-Password-File
Controls whether the server will use full text

searches when executing queries during
workflow that have full text indexed fields in the
qualification. If this option is not used, the
server will use the search capability of the
database. The options are T (use FTS in
workflow) and F (do not use FTS in workflow).
The Use FTS

in Workflow
field on the
FTS tab of the
AR System
Administration
: Server
Information
form. (See
FTS tab
configuration
options.)
Validation mechanism for unregistered AR

System users. To set this value, use the
Authenticate Unregistered Users check box in
the EA tab of the AR System Administration:
Server Information form. Windows Indicates
whether the Windows domain service is used
to validate users not registered with BMC
Remedy AR System. Values are
T Use domain service. Users in the
Windows domain are considered valid
users of BMC Remedy AR System and
are assigned to the Public group.
F (Default) Do not use domain
service.
UNIX and Linux Indicates whether the /etc/
passwd file is used to validate users not
registered with BMC Remedy AR System.
Values are
T (Default) Use password file. Users
in /etc/passwd are considered valid
users of BMC Remedy AR System and
are assigned to a group identified by the
UNIX group ID.
F Do not use password file.
Use-Server-Connect-Name-In-Stats 2
Page 1290 of 4705
Home
Option
Description
Maps to
Flag indicating whether the server name

specified by the Server-Connect-Name option
is used as the value for the Server Name field
when Server Statistics form entries are created.
Values are
T Use the Server-Connect-Name.
This provides server-specific statistics
when the server runs in a server group
because the server enters a unique
server name into the Server Statistics
form.
If the Server-Connect-Name is not configured,
the default behavior occurs.
F (Default) Use the host name (or
server alias if configured) with the
domain name appended.
When a common server alias is specified for all
servers in a server group, the same server
name is used for the servers, effectively
combining the statistics for all servers in the
group.
User-Log-File
Full path name of the file to use if user logging

is on (See Debug-mode).
VersionControl-Object-Modification-Log-Mode
Option indicating whether the object

modification log is enabled or disabled. When
the log is enabled, it records every change to
AR System objects in your system (See
Version control in BMC Remedy AR System).
Values are
0 (Default) Disabled
10 Enabled
The Object
Modification
Log field on
the Version
Control tab in
the AR
System
Administration
: Server
Information
form. (See
Setting
version control
options.)
Option indicating whether the AR System
The Save
server writes a definition file each time an

object is created or changed (See Version
Definition
Files field on
control in BMC Remedy AR System). This

option is effective only when the object
the Version
Control tab in
modification log is enabled. Values are
the AR
System
0 (Default) Yes, a definition file is

created.
10 No, a definition file is not created.
Administration
: Server
Information
Page 1291 of 4705
Home
Option
Description
Maps to
form. (See
Setting
version control
options.)
VersionControl-Object-Reservation-Mode
Option indicating whether object reservation is

enforced or disabled. When object reservation
is enforced, users can reserve server objects,
and BMC Remedy AR System prevents other
users from modifying the reserved objects (See
Version control in BMC Remedy AR System).
Values are
10 Enforced
The Object
Reservation
field on the
Version
Control tab in
the AR
System
Administration
: Server
Information
form. (See
Setting
version control
options.)
Workflow-Encryption-Algorithm
BMC Remedy Developer Studio provides the

ENCRYPT and DECRYPT functions to encrypt
and decrypt data in filters and escalations,
securing the operations. By default, only the 56
-bit DES algorithm is used for encryption, but
you can specify the 256-bit AES algorithm for
better security. To enable the 256-bit AES
algorithm, add this parameter with the value
that identifies the algorithm:
Workflow-Encryption-Algorithm:
1 Enter 1 to use the 56-bit DES
algorithm.
Workflow-Encryption-Algorithm:
7 Enter 7 to use the 256-bit AES
algorithm.
This algorithm is applied only when you use
ENCRYPT function in BMC Remedy Developer
Studio.
Note: BMC recommends that you use the 256bit AES algorithm for better security.
ardb.cfg or ardb.conf
The ardb.cfg (ardb.conf) file contains SQL clauses that administrators can append to SQL
statements issued by BMC Remedy AR System when a form, field, or index is created or modified.
Create this file in your configuration directory:
Page 1292 of 4705
Home
(Windows default) ARSystemServerInstallDir\Conf

(UNIX default) ARSystemServerInstallDir/conf
When you create a form, field, or index, BMC Remedy AR System references the ardb
configuration file for clauses to append to the SQL statement. If it finds no matching information,
BMC Remedy AR System creates the form, field, or index as it normally would. If it finds matching
information, it appends the specified clause to the SQL statement that creates the form, field, or
index.
To create an ardb.cfg (ardb.conf) file
Synopsis
Scenarios
Warning
BMC Remedy AR System does not verify that the SQL clauses in your ardb configuration
file are correct or safe. BMC Remedy AR System merely attaches a SQL clause to the
statement used when a form or index is created. Because you can append any valid SQL
clause to the CREATE statement for a form, field, or index, use this feature wisely.
The format of this file is organized by forms.
To create an ardb.cfg (ardb.conf) file

1. Enter a line in the file for the name of the form and a line for the clause you want added to
the CREATE statement:
Form: formName
Clause: clause
Note
When you use BMC Remedy Developer Studio to change the name of a form, the
ardb configuration file is automatically updated to match the new name.
2. Include field clause information below the applicable form information:
a.
Page 1293 of 4705
Home
a. Add a field line with an open brace:

Field {
Include a space between Field and the open brace.
b. Add a line for the field ID:
Id: fieldID
c. Add a line for the SQL clause:
Clause: clause
The clause must be on one line because no new-line characters are allowed.
d. Place the closing brace in its own line below the SQL clause line.
3. Include index clause information:
a. Add an index line with an open brace:
Index {
Include a space between Index and the open brace.
b. Add a line for the field IDs in the index:
Id: indexID
If an index contains multiple fields, add several field ID lines before the clause for that
index.
c. Add a line for the SQL clause:
Clause: clause
The clause must be on one line because no new-line characters are allowed.
Clauses that you specify for the tables of a form are not automatically attached to any
index you create for that form. You must specify the clause in the index clause. For
example, if you specify that a form is to reside in a specific part of your database and
you want an index for that form to reside in the same space, you must specify the
clause for both the form and index.
d. Place the closing brace in its own line below the index clause line.
The file looks something like this:
Form: formName
Clause: clause
Field {
Id: fieldID
Page 1294 of 4705
Home
Clause: clause
}
Index {
Id: index_ID
Id: index_ID
Clause: clause
}
Leading spaces in the ardb configuration file are ignored, so you might want to add
them to keep your file organized.
When you create or update the ardb.cfg (ardb.conf) file, the changes do not occur
immediately. They occur when the table (or index) is restructured.
Synopsis
Windows: ARSystemServerInstallDir\Conf\ardb.cfg
UNIX: ARSystemServerInstallDir/conf/ardb.conf
Scenarios
The following example shows ardb configuration file information for the HD-Answer form on an
Oracle database. The tables for the HD-Answer form are built on segment two. The indexes include
the Submitter (ID 2), Status (ID 7), and Assigned To (ID 4) fields. The clauses for the indexes
instruct the database to leave 70 percent of each index free for updates and insertions.
Form:HD-Answer
Clause:TABLESPACE seg2
Field {
Id:536870913
Clause: NOT FOR REPLICATION
}
Index {
Id:2
Id:7
Clause:PCTFREE 70
}
Index {
Id:4
Clause:PCTFREE 70
Page 1295 of 4705
Home
}
The following examples show how you can use the ardb.cfg (ardb.conf) file to create indexes
using the Oracle UPPER function:
To specify that all indexes created for a form should be functional indexes, use this syntax:
Form: formName
Index {
Oracle-All-Upper-Index
}
To create a single functional index on a specific field, use this syntax:
Form: formName
Index{
Id: fieldID
Oracle-Upper-Index
}
To create a functional composite index, use this syntax:
Form: formName
Index {
Id: field_ID
Id: field_ID
Oracle-Upper-Index
}
armonitor.cfg or armonitor.conf
The armonitor.cfg (armonitor.conf) file is read by the armonitor.exe (armonitor) binary, which
executes the commands listed in the configuration file.
Synopsis
Options
Synopsis
Windows: ARSystemServerInstallDir\Conf\armonitor.cfg
UNIX: /etc/arsystem/serverName/armonitor.conf
Options
This file contains the following types of entries:
Page 1296 of 4705
Home
Two fields separated by a space or tab:
parameter value
Each parameter represents a particular configuration option. The available configuration
options and their settings are described in the following table. Lines that do not begin with
one of these options are ignored.
The associated value represents the current setting for that option. All numeric values are in
a base 10 system.
A command issued by armonitor to start various server processes. Lines with a pound sign
(# ) in column 1 are treated as comments and ignored.
The armonitor configuration options are listed in the following table.
armonitor configuration options
Option
Description
Environment-variable
Defines environment values established for armonitor. You can include many instances of this option in
the file. Before initiating any processes, armonitor sets any values specified through this option in its
environment. Then, any processes that armonitor initiates inherits these values. This is a
platform-independent way of defining environment variables. With this option, you can
Overwrite the existing value of an environment variable:
Environment-variable: EnvVariableName= value
Prepend the existing value of an environment variable:
Environment-variable: EnvVariableName+= value
Append a value to the existing value of an environment variable:
Environment-variable: EnvVariableName=+ value
For example: Environment-variable: ARDATEONLY=MM/dd/yyyy
Monitor-directory
Specifies the armonitor directory. Initially, the installer enters this value, and the value is the same as
the installation directory.
SNMP-Agent-Enabled
Permits armonitor to start the BMC Remedy SNMP Agent and to establish a link to it. Values are
T Start and link to the BMC Remedy SNMP Agent.
F (Default) Do not start and link to the BMC Remedy SNMP Agent
AR System server components and external

utilities
This section describes some BMC Remedy AR System server components. Each item is listed by
its UNIX name. If a Windows equivalent exists, it appears in parentheses after the UNIX name.
AR System server components
Page 1297 of 4705
Home
External utilities
AR System server components

arforkd
armonitor.exe or armonitor
arplugin.exe or arplugin
arserver.exe or arserverd
arsystem
Java plug-in server
arforkd
This topic describes the arforkd process, which is for UNIX environments only.
arforkd description
The arforkd process reduces the amount of memory an BMC Remedy AR System server uses
when forking new processes as a result of filters that run processes, set fields to values returned
from processes, or send email notifications. This small process runs new processes on behalf of
the server. The BMC Remedy AR System server starts the arforkd process and restarts the
arforkd process if it dies.
The ar.conf file contains configuration information for arforkd. See ar.cfg or ar.conf.
armonitor.exe or armonitor
In this topic:
Description
Synopsis
Options
Description
The armonitor process starts and restarts the BMC Remedy AR System server, BMC Remedy AR
System plug-in server, DSO server, and processes specified in the armonitor.cfg (armonitor.conf
) file.
On Windows, armonitor.exe automatically runs as a service called BMC Remedy Action Request
System Server.
On UNIX, the arsystem script usually controls armonitor. See arsystem for more information.
If a process terminates, armonitor restarts the server. If the server dies more than four times in 30
seconds, armonitor stops restarting that server.
Page 1298 of 4705
Home
Synopsis
Windows: armonitor -c pathToArmonitorConfigFile -m
UNIX: armonitor -c pathToArmonitorConfigFile -s serverName
Options
You can specify the following options on the command line:
-c Instructs the monitor to load information from the specified configuration file, usually
armonitor.cfg (armonitor.conf).
-m (Windows only) Runs the process in manual mode, not as a Windows service. To start
armonitor.exe from a command line, you must include this option.
-s (UNIX only) Specifies the name of the server that you specified during the installation of BMC
Remedy AR System. When multiple monitors are running on the same host, this option can be
used to identify a monitor process.
arplugin.exe or arplugin
In this topic:
Description
Synopsis
Options
Environment
Description
The arplugin process executes the C plug-in server, which implements and deploys several
server-side APIs. The armonitor process initiates arplugin.
The C plug-in server supports only C plug-ins. See also Java plug-in server.
Synopsis
arplugin [-i ARSystemServerInstallDir] [-m] [-s serverName]
Options
-i Specifies the directory in which the BMC Remedy AR System server was installed.
-m (Windows only) Runs the process in manual mode, not as a Windows service. If you run the
process in a command window, you must use this option.
-s Specifies the name of the server that contains the plug-in.
Page 1299 of 4705
Home
Environment
ARCONFIGDIR
(UNIX only) Specifies the directory in which the ar.conf file and other BMC Remedy AR System
configuration files are stored. The -i option takes precedence over this environment variable.
The arsystem script sets ARCONFIGDIR to ARSystemServerInstallDir/conf, and you should not
need to change this value. However, arsystem does not modify ARCONFIGDIR if a preset value is
found.
arserver.exe or arserverd
In this topic:
Description
Synopsis
Options
Environment
Files
Description
The arserver.exe executable (Windows) or arserverd process (UNIX) is the main component of
BMC Remedy AR System. It handles all interactions between clients and the database, making all
access to the system dependent on it.
On Windows, arserver.exe is usually started by armonitor.exe, which runs automatically as a
service called BMC Remedy Action Request System Server. Normally, you should use this service
to control arserver.exe.
On UNIX, the arsystem script usually controls arserverd through armonitor. Normally, you should
use arsystem to start the arserverd process (see arsystem).
If arserver.exe or arserverd is shut down for any reason, you can restart it at any time.
On UNIX systems, the arsignal command causes arserverd to load or reload information (see
arsignal.exe or arsignal). Generally, these signals are sent after a manual repair or restore
operation is performed. However, they do not cause damage or adversely affect users accessing
Synopsis
arserverd [-s serverName] [-i ARSystemServerInstallDir] [-l
licenseDirectory] [-m] [-t] [-checkdb [logFileNameWithAbsolutePath]]
Note
Page 1300 of 4705
Home
The -checkdb option is a standalone option. When you use this option, the process
checks the consistency of the BMC Remedy AR System server database, reports the
results in the checkdb log file, and then quits. Therefore, do not include the -checkdb
option with arserver/arserverd in the armonitor.conf file.
Options
You can specify the following options in any order on the command line:
-i pecifies the directory in which the BMC Remedy AR System server was installed.
-l Specifies the directory in which BMC Remedy AR System license files are stored.
-s Specifies the name of the server that you specified during the installation of BMC Remedy AR
System. When multiple monitors are running on the same host, this option can be used to identify a
monitor process.
-t Logs all startup and initialization activities and writes the information to the arstartup _number
.log file. This file is in

(UNIX) ARSystemServerInstallDir/bin
(Windows) ARSystemServerInstallDir
-checkdb Runs the server instance in the database consistency checker mode. See Checking
the database tables.
Note
Running arserverd with the checkdb option starts only the database consistency checker
, not the main AR System server.
Environment
ARCONFIGDIR
(UNIX only) Directory in which the ar.conf file is stored. The arsystem script sets ARCONFIGDIR
to ARSystemServerInstallDir/conf, and you should not need to change this value. However,
ARDATE
Page 1301 of 4705
Home
Format used for date-time fields.
(Windows only) This value consists of a string of operators defined by Regional Settings. If you do
not set this variable, the system uses the date format specified in the Regional Settings of the user
account that runs the service.
(UNIX only) This value consists of a string of operators defined by the strftime library call. Some
combinations are successfully displayed but cannot be translated for input. If you do not set
ARDATE, the system uses the date format for the language specified by the LANG variable.
ARDATEONLY
Format used by the program for date fields.
not set this variable, the system uses the date format specified in the Regional Settings of the user
account that runs the service.
ARDATEONLY, the system uses the date format for the language specified by the LANG variable.
ARTIMEONLY
Format used by the program for time-of-day fields.
not set ARTIMEONLY, the system uses the date format specified in the Regional Settings of the
user account that runs the service.
ARTIMEONLY, the system uses the time format for the language specified by the LANG variable.
LANG
(UNIX only) This value establishes the locale for BMC Remedy AR System, based on information
obtained during installation. Normally, this setting is managed by the arsystem script.
Page 1302 of 4705
Home
LC_ALL
(UNIX only) This value establishes the locale for BMC Remedy AR System, based on information
obtained during installation. Normally, this setting is managed by the arsystem script.
Files
Windows
ARSystemServerInstallDir\Conf\ar.cfg
WindowsSystemDir\drivers\etc\services
UNIX
ARSystemServerInstallDir/conf/ar/
ARSystemServerInstallDir/conf/ar.conf
/etc/services
arsystem
In this topic:
Description
Synopsis
Options
Environment
Description
The arsystem script starts the BMC Remedy AR System server and sets the system environment
appropriately. The script launches the armonitor process which, in turn, launches the arserverd
process. Normally, you do not need to start armonitor or arserverd manually.
Using the arsystem script ensures that the server starts with the correct environment variables,
such as those representing library search path and locale.
The script is in the ARSystemServerInstallDir/bin directory.
Synopsis
arsystem
{start | stop | restart | env [ <ARSystemCommandAndOptions> ] | setenv [ <
ARSystemCommandAndOptions> ]}
Page 1303 of 4705
Home
Options
You can specify one of the following options on the command line:
start Starts the BMC Remedy AR System server and sets the environment accordingly.
stop Stops the BMC Remedy AR System server.
restart Stops the BMC Remedy AR System server, and then starts it and resets the
environment.
env Calls the UNIX env command, and runs the specified BMC Remedy AR System command
in a subshell. The env option can be used to invoke
BMC Remedy AR System commands, including arserverd, arsignal, and produse, as follows:
cd <ARSystemServerInstallDir>/bin./arsystem env ./
commandOption2> ...
<commandName> <commandOption1> <
To display environment settings that pertain to the BMC Remedy AR System server, use the
following syntax:
arsystem env
setenv
Equivalent to the env option.
Environment
ARCONFIGDIR
Specifies the directory in which the ar.conf file is stored. The arsystem script sets ARCONFIGDIR
to ARSystemServerInstallDir/conf, and you should not need to change this value. However,
LD_LIBRARY_PATH
(Solaris and Linux only) Specifies the location of one or more shared libraries. API libraries,
database client libraries, and other third-party libraries are included. Normally, this variable is
managed by the arsystem script.
LIBPATH
(IBM AIX only) Specifies the location of one or more shared libraries. API libraries, database client
libraries, and other third-party libraries are included. Normally, this variable is managed by the
arsystem script.
Page 1304 of 4705
Home
SHLIB_PATH
(HP-UX only) Specifies the location of one or more shared libraries. API libraries, database client
libraries, and other third-party libraries are included. Normally, this variable is managed by the
arsystem script.
Java plug-in server

In this topic:
Java plug-in server description
Java plug-in server synopsis
Java plug-in server options
Java plug-in server files
Java plug-in server description

The Java plug-in server supports only Java plug-ins that use the Java plug-in API. The armonitor
process initiates the Java plug-in server.
Note
If users try to use the Java plug-in server to load C plug-ins, they receive this error
message: Java plug-in server does not support C plug-ins. Contact Customer
Support for details.
Java plug-in server synopsis

java -Xmx512m -classpath classPath
com.bmc.arsys.pluginsvr.ARPluginServerMain -x hostName -i
ARSystemServerInstallDir -m
Java plug-in server options

-x Specifies the host name of the BMC Remedy AR System server.
-i Specifies the directory in which the BMC Remedy AR System server was installed.
Java plug-in server files

log4j_pluginsvr.xml
These configuration files must be in the class path. For descriptions of the configuration options,
see the sample log4j_pluginsvr.xml and pluginsvr_config.xml.
Page 1305 of 4705
Home
For information about locating the log4j_pluginsvr.xml and pluginsvr_config.xml files, see
Installed plug-in components.
External utilities
This section describes some BMC Remedy AR System server external utilities. Each item is listed
by its UNIX name. If a Windows equivalent exists, it appears in parentheses after the UNIX name.
arcache.exe or arcache
arreload.exe or arreload
arsignal.exe or arsignal
ImageExtractor.jar (ImageExtractor.bat)
arcache.exe or arcache
In this topic:
Description
Synopsis
Options
Environment
Scenarios
Description
The arcache utility executes the AR System interface that lets you update an entry in the access
control cache for a user or group, and lets you distribute your change to the specified AR System
servers. This program is generally used in a multiple server environment with centralized access
control. The program is also used for error recovery in a single server environment.
Filters that execute on submit and modify to the User and Group forms are typically used to run this
program. Changes to those forms update the local cache automatically. The filters make sure that
all changes to user or group information are distributed across the system.
If the server is running on a specific port and arcache cannot obtain the port information from the
portmapper, you must set the ARTCPPORT variable. For example, if the port number is 2020, type
the following command at a command prompt:
set ARTCPPORT=2020
At a UNIX prompt, type:
setenv ARTCPPORT 2020
Page 1306 of 4705
Home
Synopsis
arcache {-U|-G}{a|d} -e entryID [-g groupList] [-i groupID]
[-c groupCategory] [-q "computedGroupQqualification"]
[-t groupType] [-lw writeLicense] [-m mailAddress] [-n name]
[-p password] [-x notifyMech] [-d] [-u authenticationAliasName]
[-r authenticationAliasString][-H groupID] [-V overlayid]
Options
You can specify the following options in any order on the command line:
-e Specifies the Request ID associated with the user or group in the access control cache
(required). If you are adding a user or group, you can specify any value that does not already
exist in the cache.
-g Specifies the set of groups to which the user belongs (applicable for adding or updating
users only). Group membership defines the permissions the user has in the system. Use the
group ID to identify each group (separated by semicolons). Special group IDs are 1 (
Administrator), 2 (Customize), and 5 (Subadministrator). For example, if the group ID for the
Technical Support group is 43, and you want to assign the user to the Customize and
Technical Support groups, specify this option as -g "2;43;".
-G Specifies the type of group cache operation. Valid values for this option are a (add or
update group) and d (delete group). The -G and -U options are mutually exclusive.
-i Specifies the group ID (applicable for adding or updating groups only).
-c Specifies the group category. Valid values for this option are 0 (regular group), 1 (
dynamic group), or 2 (computed group). The default value is 0.
-q Specifies the qualification for a computed group only. Specify this option as "\ "A\ " OR
121 ", "121 OR 'Demo' " .
-t Specifies the group type (applicable for adding or updating groups only). Valid values
for this option are 0 (none), 1 (view only), or 2 (view/change). The default value is 0.
-lw Specifies the type of write license to assign (applicable for adding or updating users
only). Valid values for this option are 0 (read), 1 (fixed), or 2 (floating). The default value is 0.
-m Specifies the default email address for sending messages (applicable for adding or
updating users only).
-n Specifies the name of the user or group (required for add operations, recommended for
delete operations).
-p Specifies the password to assign (applicable for adding or updating users only).
-U Specifies the type of user cache operation. Valid values for this option are a (add or
update user) or d (delete user). The -U and -G options are mutually exclusive.
-x Specifies the default alert mechanism to use (applicable for adding or updating users
only). Valid values for this option are 0 (none), 1 (notifier), or 2 (email). The default value is 1
.
Page 1307 of 4705
Home
-d Runs the program in debug mode. Messages that detail the progress of each operation
being performed are printed to a log. Use this mode to diagnose problems with the arcache
process only.
-u Specifies the user name of the authentication alias.
-r Specifies the authentication string of the authentication alias. See Setting up an
authentication alias for more information about authentication aliases.
-H Specifies the parent group for the group being created (applicable in hierarchical group
permissions). If not specified, the value is 0 (new group has no parent).
-V Specifies the overlay group property for the group being created. Valid values for this
options are 0 (group gives permissions only to base mode objects) or 1 (group gives
permissions only to overlay and custom objects). If not specified, the value is NULL (new
group does not restrict access to base or overlay mode objects).
Environment
ARCONFIGDIR
(UNIX only) Specifies the directory where the ar.conf file and other AR System configuration files
are stored. The arsystem script sets ARCONFIGDIR to ARSystemServerInstallDir/conf,
and you should not need to change this value. However, arsystem does not modify
ARCONFIGDIR if a preset value is found.
Scenarios
Add a user, Sam Johnson, to the access control cache of all AR System servers. Use
000000000000104 as the Request ID, samj@bmc.com as the default email address, and
notifier as the default alert mechanism. The syntax is as follows:
arcache -Ua -e000000000000104 -n "Sam Johnson" -m "samj@bmc.com" -x 1
No password or group membership is specified for this user.
Add an admin user with a fixed license. The syntax is as follows:
arcache -Ua -eTEMP999 -lw 1 -n "TEMPADMIN" -p "" -g "1;"
To add a group ID, group type, and specify a computed group with a qualification, the syntax is as
follows:
arcache -Ga -e000000000000106 -n "TEMPADMIN" -i 8989 -t 2 -c 2 -q "\ "
Administrator\ " OR 'Sunnyvale' "
Note
Page 1308 of 4705
Home
You can disable arcache with a setting in the ar.conf (ar.cfg) file. When the setting
is active you can still run arcache, but it has no effect on the server, and the cache does
not get flushed. For more information, see Disable-User-Cache-Utilities at ar.cfg or
ar.conf options C-D.
arreload.exe or arreload
In this topic:
arreload description
Synopsis
Options
Environment
arreload scenarios
arreload description
The arreload utility executes the BMC Remedy AR System interface that enables you to empty
the access control cache on one or more BMC Remedy AR System servers and reload it from a
particular User or Group form.
If you experience problems with permissions or behaviors in the Group or User form, the cache
might need to be emptied and reloaded. Run arreload to reload the cache.
This process must run on the BMC Remedy AR System server that contains the source form (the
source computer). It deletes cached requests on the specified target computers and reloads the
cache from the form on the source computer, synchronizing the cache with the available users and
groups defined in the User and Group forms.
Synopsis
arreload -a "adminUser" [-o portNumber] {-u|-g} "schema"
[-f] [-p " adminPassword"] [-h " serverNameValue"] [-d]
Options
You can specify the following options in any order on the command line. Enclose attributes in
double quotation marks:
-a (Required) Specifies a user with Administrator permission on the target servers.
-o Specifies the port number for the server.
-f Deletes all user or group requests from the cache on the specified target computers
before reloading from the source computer. This option is useful for clearing out obsolete
definitions that are no longer recognized as related to the local server and that would
otherwise not be removed. This helps prevent duplicate records that can corrupt the cache.
Page 1309 of 4705
Home
-g Specifies the name of the source form for reloading group requests (required if you do
not specify the -u option).
-h Specifies the name of the server if a Server-Name value is set in the AR System
server configuration file. If Server-Name has a value and you use arreload without the h option, arreload uses the default server name rather than the name specified by
Server-Name.
-p Specifies the password for the user specified by the -a option (required if a password
is defined for that user).
-u Specifies the name of the source form for reloading user requests (required if you do
not specify the -g option).
-d Runs the program in debug mode. Messages are printed to stdout and detail the
progress of each operation being performed. Use this mode to diagnose problems with the
arreload process only.
Environment
ARCONFIGDIR
UNIX only Specifies the directory where the ar.cfg (ar.conf) file and other BMC Remedy AR
System configuration files are stored. The arsystem script sets ARCONFIGDIR to
arreload scenarios
Connect as Admin (using the password fun4me) and delete all user requests from the access
control cache of all AR System servers. Reload the cache on all computers from the User form on
the current computer. In this example, the attributes are enclosed in double quotation marks:
arreload -u "User" -a "Admin" -p "fun4me" -f
Reload the cache on all computers from the Group form and the User form on the current computer
. In this example, the attributes are enclosed in double quotation marks:
arreload -u "User" -g "Group" -a "Admin" -p "fun4me" -f -d
Note
You can disable arreload with the setting in the ar.cfg (ar.conf) file. (See
Disable-Client-Operation on ar.cfg or ar.conf options C-D.) When the setting is active,
you can still run arreload, but it has no effect on the server, and the cache does not get
flushed.
Page 1310 of 4705
Home
arsignal.exe or arsignal
In this topic:
Description
Synopsis
Options
Description
The arsignal utility forces an AR System server to load or reload information. The process can
be run on any computer.
Synopsis
arsignal {-a | -b | -c | -d | -e | -g | -l | -m | -p | -r | -u }
serverName[:port][sigArgument]
The server name identifies the server that is to reload information. If a TCP port is to be specified
as well (needed if the server does not register with AR System Portmapper), it is appended to the
server name, separated by a colon. The string sigArgument is applicable when using the -a, -d,
-p, or -u options.
Options
You can specify one of the following options:
-a Causes the server to update internal Alert user information based on the details provided in
sigArgument. See Configuring a hardware load balancer with BMC Remedy AR System.
-b Causes the server to recache and reload archive definitions.
-c Causes the server to reload information from its ar.cfg (ar.conf) file.
-d Causes the server to transfer the signal to a DSO process.
-e Causes the server to recache and reload escalation definitions.
-g Causes the server to reload group and data dictionary information from the database.
-l Causes the server to reload license information.
-m Causes the server to reload computed group information.
-p Causes the server to transfer the signal to an application process.
Page 1311 of 4705
Home
-r Causes the server to recache definitions from the database.

-u Causes the server to reload user information.
ImageExtractor.jar (ImageExtractor.bat)
In this topic:
Description
Synopsis
Options
Environment
Files
Description
The ImageExtractor is a Java utility that enables you to convert individually stored images
contained in existing field display properties to BMC Remedy AR System shared images. Shared
images are server objects that you can manage in BMC Remedy Developer Studio.
Note
Before BMC Remedy AR System 7.5.00, a separate copy of each image was stored in the
database for every field with which it is associated. By converting multiple copies of each
image to a single image retrieved by reference, this utility reduces database storage
space and cache requirements.
The utility can convert all images associated with a specified set of forms, or all images in the
database, to shared images and image references. The utility uses an image checksum to identify
images already present in the server. If an image is found, that reference is used. Otherwise, a
shared image object is created.
The ImageExtractor.jar utility is installed with the AR System server. On Windows, a batch file
(ImageExtractor.bat) is provided to ensure the correct environment settings are configured when
you run the utility. Both files are in the ARServerInstallDir\api\lib directory. On UNIX,
ImageExtractor.java is in the ARServerInstallDir/api/JavaDriver/ directory.
Synopsis
{{java -jar ImageExtractor.jar}}
Options
The utility prompts you for the following input:
Server host Enter the host name of the AR System server.
Page 1312 of 4705
Home
Server port If not using the AR System portmapper, enter the TCP port for the AR
System server. If using a portmapper, press ENTER to leave this option blank.
User name Enter the AR System user name of a user who is a member of the
Administrator group.
Password Enter the password for the user.
Image file containing the form names Enter the name of the text file, if any, that lists
the form names for which to convert images (see the Environment information). To convert
all images on the AR System server, leave this option blank.
Environment
You must have a supported Oracle Java runtime environment (JRE) installed and available in the
server environment.
To convert images for a specified list of forms, create a text file that contains one form name per
line. For example, the ImageExtractor utility would use the following text file to convert all images in
the Sample application forms listed:
Sample:Cities
Sample:ClassCentral
Sample:Classes
Sample:DialogYesNo
Sample:Enrollments
Sample:GetWeather
Files
ImageExtractor.jar
Configuration data is stored in the centralized configuration forms and reflected in the ar.cfg
configuration file (for backward compatibility). Centralized configuration not only simplifies the
management of configuration data, but also simplifies the sharing of configuration settings across
servers. Also, because configuration data is stored directly in the database, the data is more secure
.
The following topics provide detailed information about centralized configuration:
Backing up and restoring centralized configuration settings
Centralized configuration system forms
Notifications about changes to centralized configuration settings
Page 1313 of 4705
Home
The configuration data for the following components is centralized:

BMC Remedy Mid Tier
Notes
You can continue to change the configuration settings for the following components
by using the listed form or tool:
BMC Remedy AR System server AR System Administration:Server
Information form
BMC Remedy Approval Server AP-Admin-ServerSettings form
BMC Remedy Mid Tier Mid Tier Configuration Tool
You can use the AR System Administration:Plugin Server Information form form to
change the configuration settings for Java plug-in server.
You can use the AR System Configuration Generic UI form form for BMC Remedy
Email Engine configuration settings and any other configuration settings that are
not available in the preceding forms.
Backing up and restoring centralized configuration settings

You can now maintain copies of your centralized configuration data and restore any copy to revert
to old customized settings at any time.
This topic provides the following procedures:
To create a backup
To restore a selected backup
To delete a selected backup
Note
The backup functionality copies all the centralized configuration data. You cannot create a
component-specific or setting-specific backup.
Page 1314 of 4705
Home
To create a backup
> General > Centralized Configuration Backups.
2. In the AR System Configuration Backup Management form, in the Backup Name field, enter
a name for the backup.
3. Click Backup.
Note
When you create a backup, the data is backed up in the following forms:
AR System Configuration Component_Backup
AR System Configuration Component-Setting Mapping_Backup
AR System Configuration Setting_Backup
To restore a selected backup

2. In the AR System Configuration Backup Management form, from the Available Backups
section, select the required backup, and click Restore Selected Backup.
When you restore a selected backup, it replaces all the current configuration settings with
the settings from the backup.
To delete a selected backup

2. In the AR System Configuration Backup Management form, from the Available Backups
section, select the required backup, and click Delete Selected Backup.
Centralized configuration system forms

In centralized configuration, configuration information is stored in the following system forms:
AR System Configuration Component form Defines the name of the component (for
example, the server name) and the type of component. Examples of components are an AR
System server, a mid tier, Email Engine, and so on. The convention for naming component
types is similar to that of Java, for example, com.bmc.arsys.server.
AR System Configuration Setting form Defines the configuration parameters for the server
.
Page 1315 of 4705
Home
AR System Configuration Component Setting form Displays all of the properties of a

component. This join form contains data from the AR System Configuration Component and
AR System Configuration Setting forms.
The centralized configuration forms contain the configuration settings or options for the following
components:
BMC Remedy Mid Tier
BMC Remedy Shared (Shared parameters for all components)
When you change a configuration setting in the AR System Administration:Server Information form
(AR System server), the AP:Admin-ServerSettings form (Approval Server), or the AR System
Administration: Plugin Server Information form (BMC Remedy Java plug-in server), the
configuration settings and their new values appear in the centralized configuration forms. You can
also change the configuration settings using the AR System Configuration Generic UI form.
Notes
Changes to the ar.cfg (ar.conf) file for some settings are reflected in the
centralized configuration forms for backward compatibility, and changes to those
settings in the centralized configuration forms are reflected in the ar.cfg (ar.conf)
file .
BMC recommends that you update the configuration settings by using the UI where
possible.
For information about configuring mid tier properties, see Settings in the
For a list of all configuration settings, see:

Configuration settings A-B
Configuration settings E-M
Configuration settings N-R
Configuration settings S-Z
Page 1316 of 4705
Home
Note
While upgrading the BMC Remedy AR System server, the value of the
Configuration-Name setting is mapped to the Server-Connect-Name setting. If the
Server-Connect-Name setting is not present, then the value is mapped to the
Server-name setting.
Configuration settings A-B

The centralized configuration forms store configuration settings as name value pairs in the following
format:
<Setting Name>: <Setting Value>
Each setting represents a particular configuration option. The associated value represents the
current setting for the option. All numeric values are in a base 10 system. Default behavior occurs
either when an option is set to the default value or when the option is not in the centralized form.
The following tables lists the options available for centralized configuration.
Note
You can also modify the settings using the AR System Configuration Generic UI form. The
settings are case- and space-sensitive.
Configuration options (A-B)

Option
Description
Active-Link-Dir
Directory in which active link server run processes are stored. Only commands in the
specified directory can be run. This is a security feature that ensures clients or API programs
use only a safe set of server processes.
Maps to: The Security area on the Advanced tab of the AR System Administration: Server
Information form. (See Setting performance and security options.)
Active-Link-Shell
(UNIX only) Parent shell of any active link server process. This parameter causes the server
to start the shell with the specified process as a parameter. This is a security feature. The
specified shell might be a security shell that verifies a path or runs with a user ID other than
the one the server uses. For example, if the server runs as root and an administrator
specifies a shell that runs as a lower user privilege, an active link invokes the shell that runs
as a user instead of as root. Because the AR System server passes the shell command to
the Active-Link-Shell as a single string without any other command-line arguments, the
command parameters can often get interpreted incorrectly. The AR System server does not
know which custom shell is supposed to be used for active link processing, so it does not
know how to supply all of the necessary arguments. In order to avoid this and use the
Active-Link-Shell Feature correctly, follow the steps listed below:
1.
Page 1317 of 4705
Home
Option
Description
1. Determine what your desired shell is, and how to invoke it passing a single command
line. If the desired shell is /bin/csh, the correct way to invoke with a single command
line is
"/bin/csh" "-c" "process command"
2. Write a /bin/shscript that invokes your custom shell in the required manner, as shown
below:
#!/bin/sh
# Usage:
#
/path/to/arsystem-csh-helper process-command
# Pass process-command as a command line to /bin/csh.
#
# use "$*" preserve argument as a single string
exec /bin/csh -c "$*"
3. Put the script in a location where the AR System server will be able to call it. For
example, local utilities are often installed in a directory named /usr/local or /usr/local/
bin. Another good location might be the AR System server installation directory. Be
sure to mark the new program executable:
# cp arsystem-csh-helper /usr/local/arsystem-csh-helper
# chmod 755 /usr/local/arsystem-csh-helper
4. In the AR System server configuration, change the Active-Link-Shell to be the new

program /usr/local/arsystem-csh-helper.
Maps to: The Security area on the Advanced tab of the AR System Administration: Server
Admin-Only-Mode
Flag indicating whether only administrators and subadministrators can access the server.
Values are
T Admin-only mode is on.
F (Default) Admin-only mode is off.
Maps to: The Administrator-Only Mode field on the Configuration tab of the AR System
Administration: Server Information form. (See Setting administrative options.)
Allow-Backquote-In-Process-String
Option that enables the server to run a process with a backquote in the process name or in
its arguments. Values are T and F (default).
Allow-Guest-Users
Flag indicating whether the BMC Remedy AR System server accepts guest users (users not
registered with BMC Remedy AR System in a User form). Values are
T (Default) Allow guest users. Unregistered users have no permissions but can
perform some basic operations. For example, they can submit requests to forms to
which the Public group has access and whose fields allow any user to submit values.
F Do not allow guest users. Unregistered users have no access to the system.
Maps to: The Allow Guest Users field on the Configuration tab of the AR System
Page 1318 of 4705
Home
Option
Description
Flag indicating whether unqualified searches can be performed on the BMC Remedy AR
System server. Unqualified searches are ARGetListEntry or ARGetListEntryWithFields
calls in which the qualifier parameter is NULL or has an operation value of 0 (
AR_COND_OP_NONE ). Such searches can cause performance problems because they
return all requests for a form. This is especially problematic for large forms. Values are
T (Default) Allow unqualified searches.
F Do not allow unqualified searches.
Maps to: The Allow Unqualified Searches field on the Configuration tab of the AR System
Alternate-Approval-Reg
Flag indicating how applications such as Approval Server or Reconciliation Engine listen for
the BMC Remedy AR System server's signal. Values are
T (Default) Listen for the application dispatcher to signal.
If your application relies on the application dispatcher, set this option to T. To verify
that arsvcdsp is configured to start with the BMC Remedy AR System server, check
the armonitor.cfg (armonitor.conf ) file.
F Listen for the server's signal directly.
Note:
The BMC Remedy AR System server installation creates this entry and sets the value
to T.
You should change the value to F only when the application dispatcher is not working.
This provides an alternative method to receive signals from the AR System server.
API-Log-File
Full path name of the file to use if API logging is on (see Debug-mode).
Maps to: The API Log field on the Log Files tab of the AR System Administration: Server
Information form. (See Setting log files options.)
API-Recording-Client-Type
Indicates the client types for which you want to monitor the API calls. By default, this field
does not have any value set which means that the calls from all client types are monitored.
Use this format:
<clientType>;<ipAddressExpression>;<clientType>;<ipAddressExpression>
clientType Indicates the client type to be monitor. This takes an integer value and a
* value in this field indicates that API calls from any client type are monitored. For
information on supported client types and their values, see Client types.
ipAddressExpression Indicates a regular expression used to match the source
address. This is an optional value to specify. If you do not specify any value, all source
addresses are matched by default.
For example, you might add the following values:
0;1;2 API calls from client types 0, 1, and 2 (all source addresses are
matched).
0 ^10\..;1;2* API calls from client types 1 and 2 included (all source
addresses are matched as the regular expression is not specified). API calls
from client type 0 included if the source address is from an IP address starting
with 10.
0;* ^(?!10\.) API calls from client type 0 ("unknown") are recorded (all source
addresses are matched as the regular expression is not specified). API calls
from all clients with a source address that does not start with 10 are included.
^(?!10\.)(?!11\.) API calls from all clients with a source address that does not
start with 10 or 11 are included.
Page 1319 of 4705
Home
Option
Description
API-Recording-Enable
Specifies whether you want to enable the system for monitoring API calls. Values are:
Yes Indicates that monitoring is enabled.
No (Default) Indicates that monitoring is disabled.
Approval-Debug-Type2
This setting specifies the log level for approval server. Values are:
0 (Default) The minimum logging level for BMC Remedy Approval Server is
NORMAL (or INFO).
1 The highest logging level for BMC Remedy Approval Server is ALL (or DEBUG).
Approval-Defn-Check-Interval 2
Interval (in seconds) at which Approval Server checks for changed or updated data in the
data definition forms.
Approval-Due-Soon2
The duration after which the approval requests that are due for action are highlighted on
Approval Central.
Approval-Log-File 2
Full path of the Approval Server log file.
Approval-Notify 2
Flag indicating whether approval notifications are configured from the Server Settings dialog
box. An Approval-Notify entry exists for each ID.
Warning : Do not change this option in the AR System Configuration Component Setting
form . Instead, from the AP:Administration form, click the Server Settings link to open a
dialog box with configuration settings for the Approval Server.
Approval-Polling-Interval 2
Interval at which the Approval Server polls the AR System server for pending work. This
setting is intended as a backup method, not the primary contact method. Under normal
circumstances, the AR System server or the Application Dispatcher (depending on the
configuration) contacts the Approval Server when work is pending. When this option is
specified, the Approval Server polls the AR System server only if it does not receive a signal
from the AR System server in the specified time. Specify the interval in seconds. Minimum is
30 seconds. Maximum is 3600 seconds (one hour).
Approval-Recent-History2
The duration within which a user can see in the recent history an approval request that was
submitted or acted upon.
Approval-RPC-Socket 2
RPC Program Number that Approval Server uses when contacting BMC Remedy AR System
. This enables you to specify a private BMC Remedy AR System server for Approval Server.
AR-Max-Attach-Size 2
Maximum size (in bytes) of compressed attachments that can be sent to the AR System
database from the AR System server. By preventing large attachments from being sent to the
database, you can prevent excessive memory growth and reduce transmission time. This
limit does not apply to attachments retrieved from the database by the AR System server.
This option applies to all databases.
Note: To limit the size of compressed attachments that the server can retrieve from Oracle
databases, use Db-Max-Attach-Size.
Arerror-Exception-List 2
List of errors that trigger a dump of the current stack in the arerror.log file. Separate each
error number with a semicolon (for example, 123;345;).
ARF-Java-VM-Options 2
Java command options for a virtual machine (VM). The options are documented in the online
AR System Java API documentation.
Archive-Interval
Specifies the number of hours scheduled to run the global archive for all forms.
In a server group environment:
1.
Page 1320 of 4705
Home
Option
Description
1. This configuration setting is shared among all the servers.
2. If you set this parameter on any of the server, it will be applicable for all the servers.
For information about setting, archive interval, see Setting global archive interval for forms.
ASJ-Thread-Count
Authentication-Chaining-Mode
Specifies the total number of worker threads that process various approval requests.
Mode that enables the administrator to use more than one type of authentication on the same
system. Values are
0 (Off)--Use the default behavior. Users are authenticated based on the settings of
Crossref-Blank-Password and Authenticate-Unregistered Users.
1 (ARS - AREA) Use internal authentication as the primary method; use external
authentication via the AREA plug-in as the secondary method.
2 (AREA - ARS) Use external authentication via the AREA plug-in as the primary
method; use internal authentication as the secondary method.
3 (ARS - OS- AREA) If authentication fails in AR System (internal authentication),
use the operating system authentication (for example, NT domain authentication). If
the operating system fails, try external authentication (AREA).
4 (ARS - AREA - OS) If authentication fails in AR System, try AREA. If AREA fails,
try the operating system authentication.
If the value is not 0, the settings of the Crossref-Blank-Password and
Authenticate-Unregistered Users parameters are ignored.
If the value is not 0 and the Crossref-Blank-Password parameter is enabled, users who
have a blank password in the User form must provide a valid password (that is, a non- NULL
password) during login.
Values 3 and 4 provide greater flexibility. For example, your external users might be
authenticated with an AREA plug-in, and internal users might be authenticated by the NT
domain.

The following table explains the configuration options for centralized configuration.
Configuration options (C-D)
Option
Description
Cache-Display-Properties 2
The way that the server caches form display properties. The form display
property is the background image of the form view and the display property
of each form field. Valid values:
T (Default) Cache all form-display properties.
F Cache only server-display properties. (This can negatively impact
the performance of the server if a form is changed, but it reduces the
amount of memory used in the server cache.)
Cache-Mode
Flag indicating whether a cache mode optimized for application development

is on. In this mode, user operations might be delayed when changes are
made to forms and workflow. Valid values:
Page 1321 of 4705
Home
Option
Description
1 Development cache mode is on.
0 (Default) Development cache mode is off, and the server is in
production cache mode.
Note: Development cache mode is intended for a development server
, not a production server. In this mode, administrative operations
cannot begin until in-progress user operations are completed.
Subsequent user operations are blocked until the administrative
operation is completed. Hence, the server often gives the false
impression that it has stopped responding.
See Configuring a server's cache mode.
Maps to: The Development Cache Mode field on the Configuration tab of
the AR System Administration: Server Information form. (See Setting
administrative options.)
Cancel-Query-Option 2
Flag indicating whether the cancel query functionality in a browser is enabled

. Valid values:
0 Inactive
1 (Default) Active
Changed-By-Another-Check
Flag indicating whether the system checks whether another user changed an
entry after you retrieved the entry. If you try to save modifications to an entry,
you receive a warning and must confirm the save. Valid values:
T (Default) Perform the check and issue a warning.
F Do not perform the check.
Client-Managed-Transaction-Timeout
Maximum time (in seconds) to hold a transaction before a timeout occurs.

The default is 60 seconds, and there is no maximum. If a timeout occurs, the
server automatically rolls the transaction back, and the client receives an
error on the next operation that uses the transaction handle.
Maps to: The Transaction Timeout (seconds) field in the Transaction
Control area on the Advanced tab of the AR System Administration: Server
Clustered-Index
Flag indicating whether indexes for the database are clustered. Valid values:
T (Default) Use a clustered index.
F Do not use a clustered index.
You must set this option before you start the BMC Remedy AR
System server.
com.bmc.arsys.emaildaemon.level 2
Specifies the log level for email engine based on which the logs are
generated in the email.log file
Valid values:
Off
Severe (Default)
Warning
Info
Config
Page 1322 of 4705
Home
Option
Description
Fine
Finer
Finest
Related functionality: Incoming and Outgoing
Related protocol: All Supported
Specifies the log level for email engine based on which the logs are saved in
ARSystemHandler.level 2
the AR System Email Error Logs form

Valid values:
Off (Default)
Severe
Warning
Info
Config
Fine
Finer
Finest
AdditionalMailHeaders 2
Specifies additional email headers. Separate the additional email headers

with commas. See Adding extra custom headers to outgoing SMTP emails .
Default value: X-Loop-Detect
Related functionality: Outgoing
Related protocol: SMTP
com.bmc.arsys.emaildaemon.ARDATE 2
Specifies the date and time format that the BMC Remedy Email Engine uses
for parsing date and time strings given in the incoming mails. MMMMM dd,
yyyy HH:mm:ss z is equivalent to December 21, 2009 12:08:56 PDT.
Related functionality: Incoming
com.bmc.arsys.emaildaemon.ARDATEONLY 2
Specifies the date format that BMC Remedy Email Engine uses for parsing
date strings given in incoming mails. MMMMM dd, yyyy is equivalent to
December 21, 2009.
com.bmc.arsys.emaildaemon.ARTIMEONLY 2
This setting lets you specify the time format used by BMC Remedy Email
Engine for parsing time strings given in incoming mails. HH:mm:ss z is
equivalent to 12:08:56 PDT.
Page 1323 of 4705
Home
Option
Description
This setting indicates whether to send the charset property in the
ContentTypeWithCharset 2
Content-Type header of an outgoing message. If you do not want the

charset string to be present in the Content-Type header, set this property to
False.
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon.ChunkSize 2
Specifies the number of entries to return when the BMC Remedy Email
Engine makes a call to the AR System server.
Default value: 100
Note: The maximum value is also 100.
Specifies whether you can use a comma as a separator when entering
CommaValidAddressSeparator 2
multiple addresses in the To and CC fields. If user names in the mail server
contain commas, set this property to false (usually needed only when using
the MAPI protocol). For example, if names are stored on the mail server as:
Smith, John and
Cho, Rick
You would need to use semicolons to separate the addresses:
Smith, John; Cho, Rick
Valid values:
True (Default)
False
Exchange-Wait-Time 2
Specifies the amount of time in milliseconds for which the BMC Remedy
Email Engine waits before processing the next incoming message, when
there are more messages residing on the Exchange Server.
Default value: 1
FetchUserGroupInfoOnDemand 2
Specifies whether to fetch the user and group information about demand as
opposed to loading all users and groups at startup. If there are many users
or groups, you might want to set this property to true to reduce the startup
time for email.
Valid values:
True
Page 1324 of 4705
Home
Option
Description
False (Default)
Determines whether the outgoing message header should contain the Reply
getReplyToWithFromAddress 2
To field and what its value should be.getReplyToWithFromAddress is not

used by default. If you want the email engine to use this property, you must
add it to EmailDaemon.properties and set its value to true. If you add the
property but do not specify a value, it is considered as false. The effect of
using this property is as follows:
If no values are provided in the Reply To Address field of the
outgoing mailbox configuration form and the Reply To field of the
messages form, andthe value of this property is:
false (or not provided) The Reply To field is not included in
the outgoing message header.
true The Reply To field is included in the outgoing message
header, and its value is the address in the From field of the
messages form.
If the Reply To Address field of the outgoing mailbox configuration
form or the Reply To field of the messages form contains a value, the
message header will contain the Reply To header value as set in the
message, regardless of value of this property.
Valid values:
True (Default)
False
IncomingConnectionRecycleSize 2
Specifies the default number of email messages the email engine receives
before the connection is closed and reopened. In the 5.1 and 5.1.1 releases
of the email engine, the connection with the mail server was closed only after
reading all incoming messages. Consequently, if the email engine crashed or
hung before the connection was closed, it was possible that messages
marked for deletion would not be deleted from the mail server. This property
helps you avoid that situation.
Default value: 100
IncomingMessagesQueueSize 2
Specifies the message queue size (number of emails). The Receiver module
writes messages to the queue, and the Execution module reads messages
from this queue to parse and execute. The Receiver module still writes
messages to the server in AR System Email Messages form, but the
Execution module reads the message from the message queue instead of
from the server. This reduces the traffic to the AR System server and
improves the performance.
Default value: 100
Page 1325 of 4705
Home
Option
Description
instructionCacheSize 2
Specifies the number of instructions to be stored in the cache, which is used

to improve performance. If the value of this property is set to 15, the cache
already contains 15 instructions, and another instruction is to be added, then
the oldest instruction is removed to accommodate the newest one.
Note: If any changes are made to the BMC Remedy AR System Email
Instructions form, the instruction cache is flushed based on the setting of the
serverName.Interval property.
Default value: 20
com.bmc.arsys.emaildaemon.Mailboxes 2
If you run multiple instances of the email engine on a single server, this
property specifies which mailboxes should the email engine process. The
value of this property should contain comma-separated mailbox names; the
email engine only processes these mailboxes. If you do not specify a value,
the email engine processes all of the mailboxes configured for the server.
MailboxPollingUnitIsMinutes 2
Specifies whether the polling interval is to be considered in minutes (as

configured in AR System Email Mailbox Configuration form) or seconds. The
email engine interprets the value of this property as follows:
true Consider the polling interval in minutes.
false Consider the polling interval in seconds.
Note: Whatever measure of unit you select applies to all configured
mailboxes that are enabled.
Valid values:
True (Default)
False
MaxAttachSize and
MaxAttachSizeFileExtensions 2
Specifies the attachment types that you want to permit in an email message
and the maximum size of each attachment. MaxAttachSize specifies the
maximum size limit for attachments, whereas
MaxAttachSizeFileExtensions specifies the file types by using
comma-separated extensions. These properties must be used together to
impose limits on email attachments of specific file types. For example, to set
the maximum size of .doc, .pdf, and .xls attachments to 1000000 bytes (1
MB), use the following syntax:
com.bmc.arsys.emaildaemon.MaxAttachSize=1000000
com.bmc.arsys.emaildaemon. MaxAttachSizeFileExtensions=doc,pdf,
xls The size limit is not imposed on files whose extensions are not specified
Page 1326 of 4705
Home
Option
Description
by using MaxAttachSizeFileExtensions. Email messages with attachments
that exceed this limit are logged to the AR System Email Error Logs form.
Optionally, you can create workflow for this form to process such messages
separately.
Valid values:
True
False (Default)
The email engine interprets the value of this property as follows:
MBOXFromLineWith-At-The-Rate-Sign 2
true BMC Remedy Email Engine fetches only those messages that
contain the @ sign in the "from line" (from address).
false BMC Remedy Email Engine fetches all the messages.
Valid values:
True
False (Default)
Related protocol: MBOX
com.bmc.arsys.emaildaemon.Monitor 2
Specifies the interval in minutes between checks to see if all the threads are
functioning properly.
Note: If the monitoring system detects that a thread has failed, it restarts the
thread.
Default value: 30 minutes
NumberOfSenderThreads 2
Specifies the number of sender threads that the email daemon uses for each
outgoing mailbox. The optimum number of threads depends on many factors
including the number of mailboxes, the hardware configuration, and so on.
Valid values: 1 through 20
Default value: 4
OutgoingMessagesQueueSize 2
Specifies the size of the queue that the email daemon maintains for outgoing
messages. The optimum number of message queue size to be specified
depends on the load on the email daemon.
Note: This value is used to determine when to query the database. If you set
a very high value, the database is queried too often, which might reduce the
performance.
Default value: 100
Page 1327 of 4705
Home
Option
Description
SaveSentItem 2
Specifies whether to retain messages in the Email Messages form after

sending. To delete sent messages from the Email Messages form, set this
property to False.
Valid values:
True (Default)
False
securityCacheSize 2
Specifies the number of security keys to be stored in the cache. If the value
of this property is set to 15, the cache already contains 15 security keys, and
another key is to be added, then the oldest key is removed to accommodate
the newest one.
Security form, the security cache is flushed based on the setting of the
Default value: 20
SendEmailSetSize 2
Specifies the number of outgoing emails to query at a time.

Default value: 100
Specifies whether to wait before cancelling an attempt to connect to the mail
SMTPTimeout 2
server and generating an error. In case of an SMTP timeout, the email

engine waits for the timeout interval and then marks the queued message as
erroneous.SMTPTimeout is not used by default. If you want the email
engine to use this property, you must add it to EmailDaemon.properties
and set its value to true. If you add the property but do not specify a value, it
is considered as false.
Valid values:
True
False (Default)
SMTPTimeoutPeriod 2
Specifies the duration in number of seconds to wait before cancelling an

attempt to connect to the mail server and generating an error. In case of an
SMTP timeout, the email engine waits for this interval and then marks the
queued message as an erroneous.SMTPTimeoutPeriod is not used by
default. If you want the email engine to use this property, you must add it to
Page 1328 of 4705
Home
Option
Description
EmailDaemon.properties and set its value to any positive integer (upper
limit depends on the platform). If you add the property but do not specify a
value, it is considered as half the polling interval that is set for outgoing
mailboxes.
Note:SMTPTimeoutPeriod is dependent on SMTPTimeout ; it works only
when SMTPTimeout is set to true.
com.bmc.arsys.emaildaemon.SortMessages 2
Specifies whether to process messages with a higher priority setting first.

Valid values:
True
False (Default)
com.bmc.arsys.emaildaemon.StoreInstructions
Specifies whether to store instructions and instruction parameters in the AR
System server. If set to true, the email engine retains data in the Email
Instructions and Instruction Parameters forms for troubleshooting. Then, you
must delete this data explicitly. The Execution module in the BMC Remedy
Email Engine handles both the parsing and execution of messages. There
will be one message queue created for each Incoming mailbox. By default,
instructions are not stored in the server.
Valid values:
True
False (Default)
This property is not available by default. You can add it if required. If this
SynchronizedLoggingMode 2
property is not present in EmailDaemon.properties, or if it is present but set

to false, the bulk API logging mode is used. If this property is present in
EmailDaemon.properties and its value set to true, then the synchronized
logging mode is used.
Note: The email engine's performance might degrade when synchronized
logging is enabled, because all the email engine threads are suspended
while processing the synchronized logs. Synchronized logging continues to
occur periodically, and control is restored to the threads only after the
logging is over.
Valid values:
True
False (Default)
Page 1329 of 4705
Home
Option
Description
Specifies the number of email templates to be stored in the cache to improve

the performance. If the value of this property is set to 15, the cache already
templateCacheSize 2
contains 15 templates, and another template is to be added, then the oldest

template is removed to accommodate the newest one.
Templates form, the templates cache is flushed based on the setting of the
Default value: 20
com.bmc.arsys.emaildaemon.URLWithHrefTag
Specifies whether an <a href> tag is placed around a URL in an HTML
message. If the setting is true, the <a href> tag is used. If the setting is false
, the URL is not enclosed in an <a href> tag.
Valid values:
True (Default)
False
Specifies whether to retain display names that do not have email addresses
UseNameIfNoEmailAddress 2
associated with them in the To, CC, or BCC fields. If the setting is true, the
display names are not removed from the To, CC, or BCC fields. If the setting
is false, the display names are removed from the To, CC, or BCC fields.
Note: The email engine checks for email addresses associated with display
names only on the User form and not on the Exchange server.
Valid values:
True (Default)
False
com.bmc.arsys.emaildaemon.UserChunkSize 2
Specifies the number of users (records from the User form) to retrieve from
the AR System server at one time. This setting can be used to tune the email
engine's performance.
Default value: 5000
com.bmc.arsys.emaildaemon.AdminAddresses
2
Specifies the email address of the administrator. If a database transaction

fails while storing an incoming message, the email engine forwards the
original mail to this email address, so that it is retained. An example of a
transaction failure could be when the database is full and cannot save
anymore incoming email messages. You can specify multiple addresses
separated by commas.
Page 1330 of 4705
Home
Option
Description
Note: This property can be used only when the BMC Remedy Email Engine
does not capture the error out incoming email messages in the BMC
Remedy AR System Email Error Messages Form.
Default value: Default value is set to the administrator address specified
during installation.
Configuration-Name 2
Name of the component.

AR System server uses this option to identify the active component in the
database.
Create-Entry-DeadLock-Retries 2
Number of times to retry the ARCreateEntry() function during deadlock

situations. Value is an integer.
Create-Entry-DeadLock-Retries-Delay 2
Delay, in seconds, between each retry of a deadlocked ARCreateEntry()

function. Value is an integer.
Crossref-Blank-Password
Flag indicating how the system responds when a user's logon name is not
assigned a password in the User form. Valid values:
T The system tries to validate the password in the Windows server
domain (or through the External Authentication API if external
authentication is on) or against the UNIX server /etc/passwd file.
F (Default) Blank passwords are not cross-referenced.
This option enables you to manage group membership and other
support information with AR System while managing passwords with
the /etc/passwd file (UNIX) or the server domain security model (
Windows).
Currency-Ratio-Client-Refresh-Interval 2
Number of minutes between each refresh of currency conversion ratios on

the client.
Db-Case-Insensitive 1
Flag indicating whether to perform case-insensitive queries on Run If

qualifications for active links, filters, and escalations. (For Oracle databases,
ensure that this option matches the behavior of your Oracle database so that
all queries are consistent.) Valid values:
T Performs case-insensitive search. Setting this parameter in the
ar.cfg (ar.conf) file causes special session parameters (NLS_SORT
and NLS_COMP) to be set to support case-insensitive searches and
invalidate existing database indexes.
By default, the AR System server creates regular indexes when you
add an index to a form. To support case-insensitive searches on
Oracle databases, functional indexes are required instead of regular
indexes. To change the AR System server's default behavior for index
creation, set the Db-Functional-Index parameter to T. Then, when a
new index is added to a form, the AR System server creates a
functional index for the form. This parameter helps to avoid
performance degradation that can result from not using database
indexes.
The Db-Functional-Index parameter is ignored if
Db-Case-Insensitive is set to F or if it is absent from the ar.cfg file.
Page 1331 of 4705
Home
Option
Description
The Db-Case-Insensitive and Db-Functional-Index parameters
handle new indexes. In the database (outside of the AR System
server), you must manually convert any existing indexes to functional
indexes. BMC provides an unsupported
OracleFunctionalIndexHelper.bat utility to manage these existing
indexes and to convert them from regular to functional indexes. You
can find this unsupported utility in the ARServerInstallDirectory\
Arserver\api\lib folder.
Due to known issue with Oracle, set cursor sharing to EXACT so that
the query optimizer can use functional indexes for LIKE queries. For
help, see your database administrator.
Note: While running the OracleFunctionalIndexHelper.bat utility for
existing forms, you might see the following error:
Error message ERROR (552): The SQL database
operation failed.; ORA-00942: table or view does
not exist.
This occurs because indexes are not applicable on vendor, view,
display-only, and join forms.
F (the default) Performs case-sensitive queries.
For optimal performance when using database indexes for case-insensitive
searches on Oracle, ensure that:
The Oracle client is at least version 11.2.
The database administrator sets cursor sharing to EXACT for the
functional indexes that Oracle Optimizer will use (otherwise,
performance can be severely degraded due to full table scans).
Note: Depending on the volume of data, creating functional indexes may
take a long time.
Db-Character-Set 2
Option that initializes an internal variable that the server uses for various
purposes, such as informing the ARGetServerInfo function's
AR_SERVER_INFO_DB_CHAR_SET server option request or adjusting the
database short column size so that the number of characters in a datum
does not exceed the number of bytes in the database field. Valid values:
Unicode (UTF-16) UTF-16 UCS-2
Unicode (UTF-8) UTF-8
Note: The installer sets this option's value.
Db-Connection-Retries 2
Number of times the BMC Remedy AR System server tries to reestablish a

lost connection to the database. The default is 100. The server retries the
connection once every 15 seconds up to the specified number of times. For
example, when this option is set to 100, the server retries the connection
once every 15 seconds for a duration of 25 minutes.
Db-Host-Name 2
Logical server name of the underlying database.
Db-Max-Attach-Size 2
Maximum size (in bytes) of compressed attachments that the AR System

server can retrieve from Oracle databases. The default value is 2 GB. This
value is limited by your server operating system and configuration.
Note: To limit the size of compressed attachments that can be sent to the
database server from AR System server, see AR-Max-Attach-Size.
Page 1332 of 4705
Home
Option
Description
Db-Max-Text-Size
(Oracle, Microsoft SQL Server, and Sybase) Maximum size for long
character text data in databases. For Oracle databases, this value is also
used for memory allocation during the processing of long text data; therefore
, use it conservatively. The default for an Oracle database is 4,194,308 bytes
. For SQL Server and Sybase, the default is 2,147,483,647 bytes. The
maximum value for either database is 2,147,483,647 bytes.
Db-name 1
For Oracle, the name of the tablespace that the AR System server uses. For
all other supported databases, the name of the underlying SQL database.
The default value is ARSystem.
Db-password
(DB2, Microsoft SQL Server, Oracle, and Sybase) Database password

associated with the ARSystem database and table space. The password
can be modified by using the ARSetServerInfo function and is stored in
encrypted form. If you change the password manually, specify this option by
using clear text, and change the password by using the AR System
Administration: Server Information form to encrypt it.
Db-Type 1
The type of database the AR System server is connecting to. Valid values:
DB2
Oracle
Sybase
Mysql
Db-user 1
(Microsoft SQL Server, Oracle, and Sybase) User name that AR System
uses to access the underlying database. The default is ARAdmin.
DB2-Database-Alias
DB2 database alias name for the AR System database.
DB2-Server-Name
DB2 database server name.
Debug-GroupId
Name of the group to which a user must belong to use logging options such
as API, database, and filter logging in BMC Remedy AR System clients.
Logging options are disabled for users who are not members of the specified
group. The group name can be Public, Administrator, Sub Administrator, or
Browser. You can also set this option in the Client-Side Logging Group field
on the Log Files tab.
Debug-mode
Bitmask indicating the server logging modes. To activate one bit, set this
option to its value (see the following list). To activate two or more bits, add
their values, and set this option to the total. For example, to activate bits 1
and 3, set this option to 5 because bit 1 has a value of 1 and bit 3 has a
value of 4. To deactivate a bit, subtract its value from the value of this option.
Unless otherwise specified in the following list, this option turns on logging
for the arserverd process. Default log files are in the directory specified by
the Server-directory option.
Bit 1 (value = 1 ) (SQL databases only) Turns on SQL logging in
the default arsql.log file. To specify a different file, use the
SQL-Log-File option.
Bit 2 (value = 2 ) Turns on filter logging in the default arfilter.log
file. To specify a different file, use the Filter-Log-File option.
Bit 3 (value = 4 ) Turns on user logging in the default aruser.log
file. To specify a different file, use the User-Log-File option.
Page 1333 of 4705
Home
Option
Description
Bit 4 (value = 8 ) Turns on escalation logging in the default
arescl.log file. To specify a different file, use the Escalation-Log-File
option.
Bit 5 (value = 16 ) Turns on API logging in the default arapi.log file.
To specify a different file, use the API-Log-File option.
Bit 6 (value = 32 ) Turns on thread logging in the default
arthread.log file. To specify a different file, use the Thread-Log-File
option.
Bit 7 (value = 64 ) Turns on alert logging in the default aralert.log
file. To specify a different file, use the Alert-Log-File option.
Bit 8 (value = 128 ) Turns on arforkd logging in the default
arforkd.log file. To specify a different file, use the arfork-Log-File
option.
Bit 9 (value = 256 ) Turns on server group logging in the default
arsrvgrp.log file. To specify a different file, use the
Server-Group-Log-File option.
Bit 10 (value = 512 ) Turns on logging for full text indexing in the
default arftindx.log file. To specify a different file, use the
Full-Text-Indexer-Log-File option.
Bit 16 (value = 32768 ) Turns on DSO server logging in the default
ardist.log file. To specify a different file, use the Distrib-Log-File
option.
Bit 17 (value = 65536 ) Turns on Approval Server logging. To
specify the location for the arapprov.log file, use the Approval Menu
> Server Settings > AP: Admin-Server Settings form.
Bit 18 (value = 131072 ) Turns on plug-in logging in the default
arplugin.log file. To specify a different file, use the Plugin-Log-File
option.
Default-Allowable-Currencies
Default allowable currency types for currency fields in clients.
Default-Functional-Currencies
Default functional currency types for currency fields in clients.
Default-Order-By 2
Flag indicating whether to apply the default sort order to search results. Valid
values:
T (Default) Use the default sort order, which is to sort by request ID
.
F No default sort order exists, and no order by clause is added to
the command if a sort order is not specified.
Default-Web-Path
URL to the directory path for the default web server pointing to the BMC
Maps to: The Default Web Path field on the Advanced tab of the AR
System Administration: Server Information form. (See Setting performance
and security options.)
Delay-Recache-Time
2
Number of seconds before the latest cache is made available to all threads.
Valid values: 0 to 3600 seconds. If this option is set to 0, every API call gets
the latest cache (that is, the cache is copied for every administrator call).
Setting the option to 0 causes slower performance for cache operations. The
default value is 5 seconds.
Page 1334 of 4705
Home
Option
Description
Maps to: The Recache Delay field on the Configuration tab of the AR
System Administration: Server Information form. (See Setting administrative
options.)
Dev-Studio-Development-Mode
Indicates whether you can use BMC Remedy Developer Studio in the Best
Practice Mode, Base Mode or both. Valid values:
1 Allows you to work in the Base Mode
2 (Default) Allows you to work in the Best Practice mode
3 Enable both the modes
Disable-Admin-Ops
Flag indicating whether administrative operations are allowed on the server.

Valid values:
F Enabled (Default)
T Disabled
If the Server Groups check box is selected, this option is ignored. Server
groups can be configured in the BMC Remedy AR System Server Group
Operation Ranking form to make sure that only one server performs the
operation. See Configuring server groups.
Maps to: The Disable Admin Operations field on the Configuration tab of
the AR System Administration: Server Information form. (See Setting
administrative options.)
Disable-Admin-Ops-Global
Flag indicating whether administrative operations are allowed on all the

servers. Valid values:
F Enabled (Default)
T Disabled
This configuration setting is shared among all the servers.
If you set this parameter on any of the servers, it will be applicable for
all the servers.
For non-server group environment, this parameter is same as
Disable-Admin-Ops. If you configure this parameter, Disable-Admin-Ops
is automatically updated with the same value.
You can set the parameter value from the AR System Administration
Console using the following steps:
1. Open AR System administration console.
2. Click System > General > Centralized Configuration.
3. Select com.bmc.arsys.server.shared > shared. The list of already
added shared parameters appears.
4. Add new parameter with name Disable-Admin-Ops-Global and set
the value as F or T to enable or disable admin operations.
Note: You can also update the parameter using these steps, if it already
exists.
Disable-Alerts
Flag indicating whether alerts are sent when alert events are created. Valid
values:
Page 1335 of 4705
Home
Option
Description
T No threads are started in the alert queue, and no alerts are sent.
F (Default) Alerts are enabled.
Changes to this setting do not take effect until the server is restarted.
Maps to: The Disable Alerts field on the Configuration tab of the AR
options.)
Disable-Archive
Switch that disables (T ) or enables (F ) the archive when the server starts.
Maps to: The Disable Archive field on the Configuration tab of the AR
options.)
Disable-Archive-Global
Switch that disables (T ) or enables (F - default) the archive when the server
starts.
all the servers.
Disable-Archive. If you configure this parameter, Disable-Archive is
automatically updated with the same value.
4. Add the parameter with name Disable-Archive-Global and set the
value as F or T to enable or disable archive operations.
exists.
Disable-ARSignals
2
Flag indicating whether automatic signals triggered by changes to the

following data on a server group's administrative server are disabled:
Archive definitions
Escalation definitions
The signals can be generated by arsignald or the database. Signals
triggered by changes to user, licensing, and computed group
information are not disabled. Valid values:
T The specified signals are disabled.
F (Default) Automatic signaling remains in effect for all object
definition changes.
To send the disabled signals manually, use the arsignal program (
see arsignal.exe or arsignal). See Configuring the server group
signaling option.
Page 1336 of 4705
Home
Option
Description
Maps to: The Disable ARSignals field on the Configuration tab of the AR
options.)
Disable-Audit-Only-Changed-Fields
Flag indicating whether to audit all records (T ), or to audit only those records
whose field values have changed (F, the default).
Maps to: The Disable Audit Only Changed Fields field on the
Configuration tab of the AR System Administration: Server Information form
. (See Setting administrative options.)
Disable-Client-Operation
2
Option that restricts time-consuming operations (such as reporting) during

busy times, improving overall performance. The syntax is
Disable-Client-Operation: <tagNumberToDisable> [[<startTime>]-[<

stopTime>]] [<groupIDList>]
The tag number identifies the client whose operations are restricted. It
is defined in the ar.h file. See the list at the end of this description.
(Optional) To specify start and stop times for the restriction, enter
them in 24-hour format (hh:mm ). The times are include times. For
example, 00:00-13:59 disables the operations from midnight until 1:59
P.M.
If you do not specify a start or stop time, the syntax looks like this:
Disable-Client-Operation: 2 18:00- 10
To disable operations from midnight until 6:00 A.M., enter this:
Disable-Client-Operation: 2 -6:00 10
If no start and stop times are specified, the operations are disabled all
the time.
(Optional) The groupIDList is a list of groups whose users can run the
operations during the specified time period. For example, you can
allow only the administrator to run reports during busy hours. Enter
none, one, or multiple group IDs delimited by spaces. For example, to
exempt group 10, enter this: Disable-Client-Operation: 1 13:00-17:
59 10
If no groups are specified, all users are barred from running the
operations during the specified time period. You can enter multiple
Disable-Client-Operation lines.
Following are the Disable-Client-Operation tag numbers:
1 AR System clients prior to the 5.0 version
2 BMC Remedy Administrator (pre-7.5.00)
4 BMC Remedy Import (pre-7.5.00)
5 AR System Distributed Server Option
6 AR System ODBC
7 AR System Approval Server
8 ---AR System web server (waserver)
9 Mid tier (version 5.0 and later)
10 Palm Pilot
11 Flashboards
12 Flashboards mid tier
13 Enterprise integration
14 arreload
15 arcache
16 ardist
Page 1337 of 4705
Home
Option
Description
17 runmacro
18 armaild, armailex (pre-5.1)
20 Report creator plug-in
36 BMC Remedy Developer Studio
4000 Driver (sample program)
4001 Distributor of application
4002 arhelp
4003 arjanitor
4004 armenu
4005 arstruct
4006 artext
4007 arsqled
4008 archgsel
Disable-Escalations
Switch that disables (T ) or enables (F - default) the escalations when the

server starts. If the Server Group Member check box is selected, this option
is ignored. Server groups can be configured in the BMC Remedy AR System
Server Group Operation Ranking form to make sure that only one server
performs the operation. See Configuring server groups.
Maps to: The Disable Escalations field on the Configuration tab of the AR
options.)
Disable-Escalations-Global
Switch that disables (T ) or enables (F - default) the escalations when the

server starts..
all the servers.
Disable-Escalations. If you configure this parameter, Disable-Escalations
is automatically updated with the same value.
4. Add new parameter with name Disable-Escalations-Global and set
the value as F or T to enable or disable escalations.
exists.
Disable-Non-Unicode-Clients
Flag indicating whether Unicode servers can refuse requests from

non-Unicode clients (for example, not Mid Tier 7.0.00). This option does not
affect non-Unicode servers. Valid values:
T Unicode servers refuse requests from non-Unicode clients.
F (Default) Unicode and non-Unicode clients can contact Unicode
servers.
Page 1338 of 4705
Home
Option
Description
Maps to: The Disable Escalations field on the Configuration tab of the AR
options.)
Disable-User-Cache-Utilities
Flag that prevents unauthorized users from using User Cache commands.
Valid values:
T The *arreload* and arcache utilities are disabled for the AR
System server.
F (Default) Cache utilities are enabled.
Display-General-Auth-Message 2
Flag indicating whether to display a message when user authentication fails.

Valid values:
T (Default) A generic message is displayed for user name and
password errors:
ARERR 623 Authentication failed
ARERR9388Authentication failed
F Each authentication error displays a different message:
ARERR 624 User account locked out due to too
many bad password attempts
ARERR9381 No such user is registered with this
server
ARERR9382Invalid password or authentication
string for existing user
This parameter can be used in conjunction with Max-Password-Attempts.
See Configuration settings E-M.
Distrib-Log-File
Full path name of the file to use if DSO server logging is on (see
Debug-mode).
Domain-Name 2
New domain name portion of the fully qualified server name. By default, a
server determines the domain name from the network interface. In rare
cases, this method does not produce the desired result because of
unexpected network card configurations. In those cases, you can use this
option to override the domain name derived from the network interface.
DSO-Cache-Check-Interval
Number of seconds between occurrences of these operations:

DSO checks for changes to the source and target forms
By default, this option is set to 1800 seconds (30 minutes). The
maximum value is 43200 seconds (12 hours).
DSO-Error-Retry-Option
DSO server retry behavior after an error:

0 (Default) Retry after standard connection and transmission errors
.
1 Never retry after any error.
2 Retry after every error.
3 Retry after standard connection and transmission errors and after
database errors.
DSO-Local-RPC-Socket
RPC program number that DSO uses. This setting is optional.
Page 1339 of 4705
Home
Option
Description
Maps to: The DSO Local RPC Program Number field in the DSO Server
area on the Configuration tab of the AR System Administration: Server
Information form. (See Setting server passwords, RPC options, and plug-in
timeouts.)
DSO-Log-Level
Level of logging for all DSO logs (ardist.log, ardist.log.default, ardist.
poolName.log, and ardist.log. poolName ):

0 Logs only errors. Includes contextual information.
1 Logs errors and warnings. Includes contextual information.
2 Logs errors, warnings, and other information to provide a
step-by-step record of DSO activities.
DSO-Main-Thread-Polling-Interval
Interval at which the DSO server queries the distributed pending queue for
pending distributed items. Enter any integer from 0 (no polling) to 3600
seconds (1 hour).
DSO-Mark-Pending-Retry-Flag
Flag indicating whether to set the status of items in the DSO distributed
pending queue to Retry after an attempt to perform the associated operation
fails. (Failure must be due to a recoverable error. Items that fail because of
nonrecoverable errors are removed from the queue.) Valid values:
T (Default) Does not set the status to Retry. Instead, the status
remains set to New. Depending on the number of pending items that
the DSO server processes, this setting might improve the server's
performance.
F Sets the status to Retry. Use this to differentiate items in the
queue that have never been processed (status = New) from items that
were processed but failed because of recoverable errors (status =
Retry).
Note: Regardless of this option's value, the pending item is retried
based on its retry configuration.
DSO-Max-Pending-Records-Per-Query
Maximum number of records in the Distributed Pending form that DSO reads
in a single database query. Minimum value is 1. Maximum value is unlimited.
If no value is specified, the default is 1000.
DSO-Merge-DupID-Overwrite 2
The way the DSO server behaves when it finds a duplicate request ID on the
target server. Valid values:
T Updates mapped fields and sets unmapped fields to NULL.
F (Default) Updates only the mapped fields on the target request.
DSO-Placeholder-Mode
Mode that disables the DSO server installed on the same host as the AR
System server. Use this when setting up a DSO server outside a firewall to
support an AR System server running behind a firewall.
DSO-Polling-Interval
Interval (in seconds) at which the DSO server checks the distributed pending
queue for pending distributed items. This is used as a backup when no
signals are received from workflow. The value can be any integer between
15 and 7200. By default, the backup polling interval is disabled.
DSO-Source-Server
Page 1340 of 4705
Home
Option
Description
The AR System server for a DSO server to support when that AR System
server is different from the one installed with the DSO server. Use this when
setting up a DSO server outside a firewall to support an AR System server
running behind a firewall.
Note: Use this entry to configure DSO for load balancing.
DSO-Supress-No-Such-Entry-For-Delete
Flag indicating whether to log AR System server error 302 (entry does not
exist in database) in the*arerror.log* file when performing distributed delete
operations. Valid values:
T Do not log ARERR 302 during distributed deletes.
F (Default) Log ARERR 302 during distributed deletes except when
the DSO-Error-Retry-Option is set to 2 (retry after every error).
Note: When this option is set to T, errors caused by valid problems
might also be omitted from the log.
DSO-Target-Connection
Information for the target BMC Remedy AR System server. Use this format:
DSO-Target-Connection: serverName:RPCNumber portNumber
Maps to: The Target connection settings tables field in the DSO Server
area on the Configuration tab of the AR System Administration: Server
Information form. (See Setting server passwords, RPC options, and plug-in
timeouts.)
DSO-Target-Password
Password used to access the target BMC Remedy AR System server

through the DSO server.
Use this format:DSO-Target-Password: serverName:encryptedPassword
DSO-Timeout-Normal
Timeout (in seconds) that the DSO server applies during communication with
the AR System server. Enter an integer between 60 (1 minute) and 21600 (6
hours).
If no value is specified, the system uses the default timeout (120 seconds).
DSO-User-Password
Password for the local DSO server user.
Configuration settings E-M

Configuration options (E-M)
Option
Description
Email-Notify-From 2
Sender name to use for filter-generated email notifications in which no

subject is specified. The value is limited to 29 characters.
Email-Timeout 2
Maximum time that arserverd waits for a return value from sendmail.
This option was valid in AR System versions 4.5.1 through 5.0.1 but
became obsolete when the Email Engine was introduced in version
5.1.0.
Enable-Unlimited-Log-Line-Length
Flag indicating whether log files display complete lines into log files or
not. Values are:
Page 1341 of 4705
Home
Option
Description
T AR System server logs complete lines into log files without
truncation.
F (Default) AR System server logs only 255 characters per
line.
Encrypt-Data-Encryption-Algorithm
Integer indicating the encryption algorithm of the data key. Use the
following values.Standard Security
1 56-bit DES using CBC mode (default)
Performance Security
Premium Security
For more information, see the Encryption Security section.
Encrypt-Public-Key-Algorithm
Integer indicating the encryption algorithm of the public key. Values are
4 512-bit RSA key (default for Standard Security)
5 1024-bit RSA key (default for Performance Security)
6 2048-bit RSA key (default for Premium Security)
Encrypt-Public-Key-Expire
Integer specifying the life span (in seconds) of the public key. At the end
of the specified time, the key expires, and the server generates a new
key. The default is 86400 seconds (24 hours).
Integer indicating whether encryption is on or off. Values are

0 (Default) Optional: Clients with and without encryption
installed can communicate with the server. Network traffic is
encrypted only if the client supports the server encryption
configuration. Otherwise, network traffic is exchanged in plain
text.
1 Required: Only clients with encryption installed can
communicate with the server. The encryption level installed on
the client (standard, performance, or premium) must be
compatible with the encryption algorithms used by the server.
2 Disabled: Whether encryption is installed on a client or not,
communication with the server is not encrypted. Network traffic is
Encrypt-Session-Hash-Entries 2
Size of the hash table that holds the encrypted session information. The
default is 509; there is no maximum.
Encrypt-Symmetric-Data-Key-Expire
Integer specifying the life span (in seconds) of the data key. At the end
of the specified time, the key expires, and a new key exchange occurs.
The default is 2700 seconds (45 minutes).
Escalation-Log-File
Page 1342 of 4705
Home
Option
Description
Full path name of the file to use if escalation logging is on (see
Debug-mode).
Exception-Diagnostic-Option 2
Integer value controlling the diagnostic output when the server crashes.
Values are
0 AR_EXCEPTION_DIAG_ALL ; includes all diagnostic
output when an exception occurs.
1 AR_EXCEPTION_EXCLUDE_STACK ; excludes the stack
trace in the diagnostic output when an exception occurs.
External-Authentication-Group-Mapping 2
Mapping of LDAP groups to BMC Remedy AR System groups for

external authentication. The value of this option consists of one or more
pairs of group names separated by semicolons. For example:"LDAP-1"
"ARS-1";"LDAP-2" "ARS-2";"LDAP-3" "ARS-3" Use mapping as an
alternative to creating an BMC Remedy AR System group
corresponding to each LDAP group. You can map each LDAP group to
an BMC Remedy AR System group (as in the example) or multiple
LDAP groups to a single BMC Remedy AR System group. If you try to
map a single LDAP group to multiple BMC Remedy AR System groups,
only the first mapping expression is valid. This option can be used with
the External-Authentication-Ignore-Excess-Groups option.
External-Authentication-Ignore-Excess-Groups 2
Flag used by AR System during external authentication. Values are

0 (Default) Users are authenticated when a match exists
between every LDAP group to which a user belongs and a
corresponding group in AR System.
1 Users are authenticated when any single LDAP group to
which a user belongs matches a group in BMC Remedy AR
System. Excess LDAP groups are ignored.
This option can be used with the
External-Authentication-Group-Mapping option.
External-Authentication-Return-Data-Capabilities 2
Bit mask that specifies the return data capabilities for the current AREA
plug-in. This option does not control the AREA plug-in; it merely
describes the behavior of the plug-in, enabling server optimization.
Values are
0 (Default) The server tries to retrieve this information from
AREA.
Bit 1 (value = 1 ) No email address is provided.
Bit 2 (value = 2 ) No notify mechanism is provided.
Bit 3 (value = 4 ) No group identifiers are provided.
7--The server potentially can reduce the number of AREA related
calls during notification processing.
Bit 4 (value = 8 ) No license information is provided.
Bit 5 (value = 16 ) No notification user validation should occur.
This enables the server to avoid using AREA for notification user
validation and information retrieval. Use this setting for sites
using a form of AREA that applies user names as email
addresses and where accessing an authentication database
provides no benefit.
External-Authentication-RPC-Socket
Page 1343 of 4705
Home
Option
Description
RPC socket number on which an external authentication server awaits
requests for authentication. The default value is 0 (external
authentication is not used). The RPC program number for the plug-in
server is 390695.
External-Authentication-RPC-Timeout
RPC timeout (in seconds) used when calling the authentication (AREA)
server. The default value is 40 seconds.
External-Authentication-Sync-Timeout
Internal timeout (in seconds) that the BMC Remedy AR System server
uses to invoke the external authentication server's
AREANeedToSyncCallback() function periodically. This function
instructs the BMC Remedy AR System server to renew its internally
stored user information in case the source used to authenticate users is
changed. A value of 0 means that the BMC Remedy AR System server
does not invoke the call to the AREA server. The default value is 300
seconds.
Filter-Api-Timeout
Time limit (in seconds) for the Filter API RPC to respond to the server's
request before an error is returned. The minimum value is 1. The
maximum is 300. The default is 40.
Filter-Log-File
Full path name of the file to use if filter logging is on (see Debug-mode).
Filter-Max-Stack
Maximum number of recursion levels allowed for an operation. The data

modification performed by an AR_FILTER_ACTION_FIELDP filter
action might trigger a second set, or level, of filters, one of which might
trigger a third level of filters and so on. This option limits the number of
times such recursion can happen, preventing the server crash that
would occur if the recursion continued indefinitely. The default value is
25.
Filter-Max-Total
Maximum number of filters that the server executes for a given

operation. The default value is 10000.
Flush-Log-Lines
Flag indicating whether logged lines are buffered or written directly to

disc. Values are:
T (Default) Logged lines are written to disc.
F Logged lines are buffered.
Full-Text-Case-Option
Flag indicating whether full text searching is case sensitive or case

insensitive. This setting affects all fields indexed for full text search and
affects how the indexes are built. Therefore, changes to this setting
trigger an automatic re-index. Values are
0 Full text search is case sensitive
1 (Default) Full text search is case insensitive
Full-Text-Collection-Directory 1
Location in the file system where search engine index files are stored.
Full-Text-Configuration-Directory
Location in the file system where search engine configuration files are
stored.
Note: If you change the directory in this option, update the
pluginsvr_config.xml file with the correct directory path. This file is in
ARSystemInstallDir\pluginsvr\fts.
Full-Text-Disable-Indexing
Page 1344 of 4705
Home
Option
Description
Flag indicating whether the server processes pending indexing tasks.
Values are
T Disable indexing. Pending indexing tasks are recorded for
processing later when indexing is enabled.
F (Default) Do not disable indexing.
Full-Text-Disable-Searching
Flag indicating whether the server uses the full text search engine for
searching. Values are
T Disable the full text search engine. The server uses the
search capability of the underlying database whether or not a
user has a full text license.
F (Default) Use the full text search engine.
Full-Text-Indexer-Log-File
Full path name of the file to use if full text indexer logging is on (see
Debug-mode).
Full-Text-Indexer-Recovery-Interval
Number of minutes that the server waits between periodic attempts to

index entries that failed to index for an unexpected reason in a prior
attempt. The default value is 60 minutes.
Full-Text-Match-Option
The way the server modifies qualifications from the client. Values are
0 Force leading and trailing wildcards.
1 Ignore leading and force trailing wildcards.
2 Ignore leading wildcards.
3 Remove leading and trailing wildcards.
4 (Default) Leave query unchanged.
Full-Text-Search-Threshold
The maximum number of search results returned from the search

engine. The default value is 10,000. To limit the number of search
results (because of constraints on the computer where the search
engine is running), reduce the threshold. If you change this option, you
must restart the BMC Remedy AR System server for the change to take
effect.
Full-Text-Search-Threshold-High
During the processing of search results, the server combines results

from subqueries to arrive at the final result set. If the number of rows
created during processing exceeds this value, the server returns an
error message indicating the search is too complex. The default value is
1,000,000.
Full-Text-Search-Threshold-Low
While processing search results, the server creates a temporary table if

the number of FTS matches reaches this value. If the number of FTS
matches is under this value, the server uses the SQL IN operator for a
query on an existing table. The default value is 200.
GetListEntry-Server-Date-Format 2
Flag indicating where to format the GetListEntry date. This option is

used mainly for backward compatibility purposes. Values are
T Format date on server.
F (Default) Format date on client.
Guest-Restricted-Read
Flag indicating whether guest users receive a restricted read license

when they log in to BMC Remedy AR System. Values are
Page 1345 of 4705
Home
Option
Description
T
F
If this option is not specified, guest users receive a read license.
GUID-Prefix 2
Character string used as a prefix for GUID strings generated by filters.
Homepage-Form
Path to the systemwide default home page. This home page is used
only if
The current server is designated as the server for the home page
in the BMC Remedy AR System User Preference form.
Or
The current server is designated as the home page server on the
General Settings page in Mid Tier Configuration Tool (see
Configuring the General Settings page.)
And
No home page is specified in the BMC Remedy AR System User
Preference form.
Note: If the home page is deleted, this option is cleared, and the
default home page must be re-entered.
Internal-User-Info-Hash-Lists 2
Number of shared, linked lists that hold all user-related information. This
number must be a power of 2. The default setting is 128. The minimum
number is 2. There is no maximum.
Note: BMC Remedy AR System doe not verify that this number is a
power of 2. If the number is not a power of 2, the AR System server
might behave in unexpected ways.
Internal-User-Instance-Timeout 2
Time, in minutes, that the AR System server waits before removing

inactive user instances from its internal memory cache. Use this option
in an LDAP environment to reduce the frequency of checks against an
outside authenticator (if a user's record is in server memory, the server
does not need to check the user's password outside the system). The
default is 2 hours (120 minutes), and the minimum is 30 minutes.
Note: This value must be greater than or equal to the value of the
Floating License Timeout on the AR System Administration: Server
Information form's Timeouts tab (by default, 2 hours). If you specify a
value that is less than the Floating License Timeout, you will not receive
an error. Inactive user instances, however, will not be removed in less
than the time specified by the Floating License Timeout. If you do not
set this option, the persistence of inactive user instances is controlled
by the Floating License Timeout.
IP-Name
Option used to specify that a server has multiple names. This option
can appear in the configuration file more than once. When checking
workflow and connections against itself, the server compares its server
name, host name, IP aliases, and any names specified by this option to
the name passed to it. If the name matches any of those names, the
server concludes that the workflow or connection is for itself. This option
can be used for servers with variable length domains or for servers on
computers with multiple internet addresses. For example, to connect to
Page 1346 of 4705
Home
Option
Description
a computer named tix as tix, tix.company.com, or
tix.eng.company.com, an administrator would create three IP-Name
entries, one for each connection name. To connect to a computer with
multiple internet addresses such as tix.company.com,
tix.biggercompany.com, and tix.evenbigger.com, an administrator
would create an IP-Name entry for each of those addresses.
License-Timeout
Number of hours the BMC Remedy AR System server waits before

disconnecting inactive users. If a user is holding a floating license, the
system also frees the license. The default value is two hours.
Locale-List
The installed language packs. Some sample values are

en English
fr French
it Italian
ja Japanese
ko Korean
pt_br Brazilian Portuguese
zh_cn Simplified Chinese
Localized-Messages-To-Cache
A semicolon-separated list of message numbers used to modify the

server's default caching behavior for localized system messages.
To cache all localized system messages the first time they are retrieved
from the AR System Message Catalog form (the default), do not use
this option in the configuration file.
To not cache any localized system messages, use this option without
any message numbers, for example:
Localized-Messages-To-Cache:
To restrict the caching of localized system messages to a specific
subset of message numbers, use this option with a
semicolon-separated list of message numbers, for example:
Localized-Messages-To-Cache: 66;72;302;314
Localized-Server
Flag indicating whether the server is running in localized support mode.

Values are
T Run in localized support mode, and use localized messages
if available.
F (Default) The server does not search for or use localized
strings.
Locked-Workflow-Log-Mode 2
Mode that causes the server to record locked workflow actions in

workflow logs. These actions are written as encrypted strings.
Log-DSO-Errors-To-Form
Flag indicating whether to log failed pending distributed operations to

the Distributed Pending Errors form. Values are
T Log errors to the form.
F Do not log errors to the form.
Log-File-Append
Page 1347 of 4705
Home
Option
Description
Flag indicating whether to create a separate *.bak file or to append to
the existing log file. Values are
T Append new log information to the existing file.
F (Default) Create a *.bak file.
Log-Form-Selected
Bitmask indicating the type of information to log in the common log form
(AR System Log:ALL). To activate one bit, set this option to its value (
values are listed under the Debug-mode option). To activate two or
more bits, add their values, and set this option to the total. For example,
to activate bits 1 and 3, set this option to 5 because bit 1 has a value of
1 and bit 3 has a value of 4. To deactivate a bit, subtract its value from
the value of this option. This option does not apply to the following bits
because information about their corresponding applications is not
logged to a form:
Log-To-Form
Bitmask indicating the information to log in predefined forms (for

example, AR System Log: API and AR System Log: Filter). To activate
one bit, set this option to its value (values are listed under the
Debug-mode option). To activate two or more bits, add their values, and
set this option to the total. For example, to activate bits 1 and 3, set this
option to 5 because bit 1 has a value of 1 and bit 3 has a value of 4. To
deactivate a bit, subtract its value from the value of this option. This
option does not apply to the following bits because no log form is
created for their corresponding applications:
Map-IP-Address
2
IP address mappings that enable alerts to work through firewalls when

Network Address Translation (NAT) is on. You must set up a mapping
for each client computer that has access through the firewall where the
client IP address is translated from an internal address to a valid
external address. In addition, a mapping is required for the AR System
server IP address if the host where the server resides is also translated.
Here is a multiple line example:
Map-IP-Address: 123.45.67.89 10.5.119.83

Map-IP-Address: 123.45.55.90 10.26.55.65
Maximum number of requests returned by a search. Because users can

also specify the maximum number of requests returned through Search
Preferences in the BMC Remedy AR System User Preference form, the
actual maximum is the lower of these values. The default value is no
server-defined maximum.
Page 1348 of 4705
Home
Option
Description
BMC recommends always setting a value for this parameter as

unqualified searches can yield enormous results resulting in
unpredictable system behavior.
Max-Log-File-Size
Maximum size in bytes for system log files. If the maximum is reached,
the logging cycle restarts at the beginning of the file, overwriting existing
information. The default value is 0 (no limit). This option does not apply
to the Arfork-Log-File.
Max-Log-History
Maximum number of backup (.bak) log files to be allowed when the log
file reaches the Max-Log-File-Size value and a new log file is created.
By default, the number of backup log files allowed is 1 and the
maximum number of backup log files allowed is 999.
Max-Notify-Mail-Line-Len 2
Maximum number of bytes that can be in a line of a mail notification.
Max-Password-Attempts
Maximum number of consecutive bad password retries a user can make

. If this option is set to 3, the user has 3 chances to log in. If all 3
attempts have bad passwords, the user account is marked INVALID.
Values are 0 (which turns this feature off) and all positive integers.
Display-General-Auth-Message. See Configuration settings C-D. See
also the description for error 624.
Max-Recursion-Level
For forms that contain hierarchical data, such as manager and

employee relationships, the maximum number of levels in the hierarchy
that a recursive query retrieves. Values are any integer greater than 0.
The default is 25. See ARGetListEntryWithMultiSchemaFields.
Max-Vendor-Temp-Tables
Maximum number of temporary tables that can exist on an AR System

server for a single vendor form. The
ARGetListEntryWithMultiSchemaFields function stores data from
vendor data sources in these tables. By default, only one temporary
table can exist for each vendor form. This setting applies to all vendor
forms on the server. It is overridden by the value of an individual vendor
form's Maximum Vendor Temp Tables property. Enter any integer
greater than 0. See ARGetListEntryWithMultiSchemaFields.
Maximum-Concurrent-Client-Managed-Transactions
Maximum number of concurrent client-managed transactions. The

default is 10, and the maximum value you can enter is 100.
MFS-Environment-Field-Weight
Indicates the relevancy weight for the Environment field of a form in a

multiple-form search. The value can be any number between 0 and
2000. Values are:
0 - 0.9 Reduces the relevancy weight of the Environment
field.
1 (Default) No change to the relevancy weight.
1.1 - 2000 Increases the relevancy weight of the
Environment field.
For more information, see Configuring forms for multiple-form FTS.
MFS-Keywords-Field-Weight
Indicates the relevancy weight for the Keywords field of a form in a

2000. Values are:
Page 1349 of 4705
Home
Option
Description
0 - 0.9 Reduces the relevancy weight of the Keywords field.
1.1 - 2000 Increases the relevancy weight of the Keywords
field.
MFS-Title-Field-Weight
Indicates the relevancy weight for the Title field of a form in a

2000. Values are:
0 - 0.9 Reduces the relevancy weight of the Title field.
1.1 - 2000 Increases the relevancy weight of the Title field.
Mid-Tier-Service-Password
Password that administrators use to access the mid tier.
Minimum-API-Version
Oldest API version with which the server communicates. The default
value is 0, which means that the server communicates with all API
versions. If the client's API version is less than the specified value, the
server refuses to talk with the client, and the client receives a decode
error. (A AR System client is any program that accesses the AR System
server through API calls, for example, BMC Remedy Developer Studio,
plug-ins loaded by the plug-in server, and so on.)
Minimum-CMDB-API-Version
Oldest CMDB API version with which the server communicates. The
default value is 3. If the version of a CMDB call is less than the
specified value, the server refuses the call. This option is independent
of the Minimum-API-Version option.
Multiple-ARSystem-Servers
Flag indicating whether other AR System servers can run on this

server's host computer. Values are
T (Default) Other servers can run on this server's host
computer.
F Other servers cannot run on this server's host computer.
To run multiple servers on the same host computer, this option must be
set to T in the configuration file of each server.
Note: To add a 7.5.00 or later AR System server to an environment in
which a 7.1.00 or earlier AR System server is already installed, you
must first change the value of this option from F to T. Otherwise, the
7.5.00 or later server installation will fail.
Multiple-Assign-Groups 2
Flag indicating whether multiple assignee groups can be stored in

row-level security field ID 112. This enables users from multiple groups
to access the same request. In the past, only one group could be stored
in Field 112. Values are
T (Default) Allow multiple groups in field ID 112.
F Do not allow multiple groups in field ID 112.
Page 1350 of 4705
Home
Configuration settings N-R

Configuration options (N-R)
Option
Description
Next-ID-Commit 2
Flag indicating whether to perform a new commit transaction when the system generates
the next ID for a record in the database. Values are
T Perform a new commit transaction. To increase efficiency and for debugging,
use this value.
F (Default) Include the transaction to generate the next ID in the create entry
transaction.
Note: Next-ID-Block-Size replaced Next-ID-Commit, but Next-ID-Commit is available for
backward compatibility.
Next-ID-Block-Size
Option that allocates next IDs in blocks instead of one at a time. Allocating in blocks
increases performance during create operations. Values are any positive number up to
1000. The default value is 25. (A value of 1 disables the feature.) You can also disable it by
removing it from the configuration file. You do not need to restart the server for the change
to take effect.
This setting is always disabled on the Distributed Pending form so that DSO can operate
correctly.
Warning: The use of this option might result in unpredictably large Next-ID sequence gaps
. The likelihood of this occurring increases with the use of multiple servers that share a
database. The BMC Remedy AR System server will not malfunction because of this gap,
and it should not be considered a defect.
Maps to: The Next Request ID Block Size field on the Configuration tab of the AR
System Administration: Server Information form. (See Setting administrative options.)
Notification-Web-Path
Base URL that appears in email notifications. If this option is not used, the
Default-Web-Path option is used. (Notification-Web-Path is available because the
Default-Web-Path is specified for other applications such as Flashboards, and it might be
different from the mid tier web path for opening requests in a notification.)
Num-Preload-Schema-Segments
Total number of preload segments loaded by the preload threads when preload threads are
configured. See Setting the Preload Tables Configuration option.
Maps to: The Number of Preload Segments field on the Advanced tab of the AR System
Administration: Server Information form. (See Setting performance and security options.)
Num-Preload-Threads
Number of preload threads to use when preload threads are configured. A value of 0
indicates that preload threads are not used. The maximum value is 30 or twice the number
of preload segments, whichever is lower. See Setting the Preload Tables Configuration
option.
Maps to: The Number of Preload Threads field on the Advanced tab of the AR System
Oracle-Bulk-Fetch-Count 2
Number of data rows simultaneously fetched from the result set when an Oracle database
is queried. The minimum is 1, the maximum is 100, and the default is 50. The higher the
value, the more memory is used during data retrieval.
Oracle-Clob-Storage-In-Row
(Oracle databases only) Flag controlling Oracle CLOB storage. Values are
T CLOBs are created "in row." In-row CLOBs can degrade CPU performance.
Page 1351 of 4705
Home
Option
Description
F (Default) CLOBs are created "out row." Out-row CLOBs can cause the
database to grow rapidly.
Oracle-Cursor-Sharing 2
Database setting that matches the setting in the Oracle initialization file ( initARS.ora if the
BMC Remedy AR System database SID is ARS). Values are
FORCE Use this value if the initARS.ora file includes the following line:
CURSOR_SHARING=FORCE.
SIMILAR If your Oracle database is set for SIMILAR, use this value.
Oracle-Search-On-Clob 2
Flag indicating whether CLOBs can be searched. Values are

T (Default) Allow searches on CLOBs. When a search is performed, the
qualification can include all the diary and character fields stored in the database as
CLOB columns. Including these fields affects performance, and indexes cannot be
used for this type of query.
F Searching on diary and character fields stored in the database as CLOB
columns returns an error.
CLOBs can use the operator LIKE, but not =.
Oracle-SID 1
(Oracle databases only) System ID for the underlying database.
Oracle-Two-Task 1
(Oracle databases only) Two-task environment setting for the underlying database.
Overlay-mode 2
Specifies the default overlay group for the server. Clients that use the default overlay group
(all clients other than Developer Studio) will retrieve and use objects from the default group.
0 Clients will only retrieve and operate on origin objects. Custom objects and
overlays of origin objects will not be visible to clients, and the server will execute
only origin filters and escalations. In this mode, customizations are ignored.
1 Clients will retrieve non-overlaid origin objects, overlays, and custom objects.
All customizations will be visible, and the server will execute non-overlaid
escalations, overlays of escalations, and custom escalations.
See Ignoring overlay and custom objects at runtime.
Per-Thread-Logging
Flag indicating whether to create per-thread log files. Values are

T Create per-thread log files.
F (Default) Do not create per-thread log files.
File name of one or more plug-ins that the plug-in server loads. The file name of the DLL or
shared object is provided. The file name might be an absolute file name or might be relative
to the BMC Remedy AR System installation directory. Add as many entries for this option to
the server configuration file as needed, but specify only one file name in each option.
Plugin-Log-File
Full path name of the file to use if plug-in logging is on (see Debug-mode).
Plugin-Log-Level
Option that specifies the type of information printed to plug-in log files. Values are
Plugin
10000 No information (ARPLUGIN_OFF ).

1000 (Default) Only severe messages ( ARPLUGIN_SEVERE ).
900 Severe and warning messages (ARPLUGIN_WARNING ).
800 Status, severe, and warning messages ( ARPLUGIN_INFO ).
700 Configuration, status, severe, and warning messages ( ARPLUGIN_CONFIG
).
Page 1352 of 4705
Home
Option
Description
600 Internal exceptions (ARPLUGIN_FINE ).
500 Trace logs that log tasks as they are executed ( ARPLUGIN_FINER ).
400 Code-level information (ARPLUGIN_FINEST ).
100 All log information (ARPLUGIN_ALL ).
Plugin-Loopback-RPC-Socket 2
RPC socket number for the private server queue to which loopback plug-in API calls should
be directed. Values are in the following ranges:
390621-390634
390636-390669
390680-390694
Loopback plug-ins (such as the Report Creator plug-in) that call back into BMC Remedy
AR System use this number to determine the queue to request. By default, plug-in API calls
are directed to a queue that corresponds to the call type. To be effective, the server must
be configured to have a designated private queue for this option.
Maps to: The Plugin Loopback RPC Program Number field on the Ports and Queues
tab of the AR System Administration: Server Information form.
Plugin-Password
Plug-in password. If this option is specified, the plug-in server accepts connections only
from BMC Remedy AR System servers whose Server-Plugin-Target-Password option is
set to the same password. If this option is not specified, the plug-in server accepts
connections from BMC Remedy AR System servers that are not configured to use a plug-in
password.
Plugin-Port
The port number on which the plug-in server waits for incoming requests.
Preference-Server-Option
Option that specifies whether users must use centralized preferences. Values are
1 Users can choose to use a preference server if one is available.
2 Users must use the specified preference server.
3 Users must use a preference server, but they cannot use this server as a
preference server. If users choose a server that is not a preference server, a
warning is returned.
Maps to: The Preference Server Option field on the Advanced tab of the AR System
Private-RPC-Socket
RPC program number that determines the type of queue to which requests are routed and
the number of threads running on that queue.
Maps to: The Server Queue field on the Ports and Queues tab of the AR System
Administration: Server Information form. (See Setting ports and RPC numbers.)
Private-RPC-Socket (for debug

queue)
Option that designates debug queues. A debug queue is a type of private queue used by
the BMC Remedy AR System Workflow Debugger. To make any private queue a debug
queue, use this syntax:Private-RPC-Socket: rpcNumberDebug For example:
Private-RPC-Socket: 390666 Debug Alternatively, you can make a private queue a debug
queue by selecting its Debug check box in the list of queues in the Ports and Queues tab of
the Administration Console.
RE-Log-File-Location 2
Location of the Reconciliation Engine log file.
Record-Object-Relationships
Flag indicating whether the BMC Remedy AR System server records the relationships
between workflow objects.
Page 1353 of 4705
Home
Option
Description
Note: If using a server group, all servers within the same server group must have the same
setting for this option. If they do not, the servers in the group inconsistently populate and
un-populate the object relationship database should they be the highest ranked server for
the Administration operation when they are restarted. Only the highest ranked server for
the Administration operation in the server group will perform the required object relationship
actions when restarted.
Values are
T The server creates entries in a database table to track the relationships
between many types of workflow objects.
When you set this option to T and restart the server, it records the relationships of all server
objects before it accepts connections from clients. Therefore, the first time you restart the
server after selecting this option, you cannot connect to the server with any clent for a
period of time, depending on how many objects are defined on the server. With a large
number of objects, such as with an ITSM application installed, this could take as long as an
hour depending on the performance of the database. (Subsequent server startups are not
affected by this setting.) When you can connect, the recording of object relationship data is
complete.
F (Default) The server does not record relationships.
When you set this option to F or remove it and restart the server, all the recorded
relationships are removed from the database. You must restart the BMC Remedy AR
System server before a change to this option takes effect.
Note: BMC recommends that you set this option by using the Record Object Relationships
option on the Configuration tab of the BMC Remedy AR System Administration: Server
Information form instead of setting it manually in the configuration file. See Viewing and
sorting related objects.
Maps to: The Record Object Relationships field on the Configuration tab of the AR
System Administration: Server Information form. (See Setting administrative options.)
Record-Server-Events
Server events to log in the Server Events form, which makes server-related changes
available to workflow and API programs. Enter the following values, separated by
semicolons, for the events to record.
1 Form
2 Field
3 Menu
4 Filter
5 Import
6 Active link
7 Escalation
8 View
9 Container
10 User
11 Group
12 Server setting
14 Archive
15 Server group actions
For example:Record-Server-Events: 4;8;9;12;14; For information about the Server
Events form, viewing recorded server events, and using server events in workflow, see
Understanding the Server Events form.
Page 1354 of 4705
Home
Option
Description
Register-With-Portmapper
Flag that prevents the BMC Remedy AR System server from registering with a portmapper.
Use this feature in conjunction with setting specific ports to enable you to run servers on
computers that do not have a portmapper. Values are
T (Default) Register with portmapper.
F Do not register with portmapper.
No more than one server should try to register with AR System Portmapper in an
environment with multiple servers on one computer.
Maps to: The Register with Portmapper field on the Configuration tab of the AR System
Administration: Server Information form. (See Setting ports and RPC numbers.)
Registry-Admin-Password
Password of the BMC Atrium Web Services Registry admin user. Used by workflow for the
BMC Remedy AR System Web Services Registry form.
Registry-Admin-User
User name of the BMC Atrium Web Services Registry admin user. Used by workflow for the
BMC Remedy AR System Web Services Registry form.
Registry-Location
URL of the BMC Atrium Web Services Registry. Used by workflow for the BMC Remedy
AR System Web Services Registry form.
Remedy-App-Service-Password
Encrypted password that AR System application services such as Approval Server use to
access the BMC Remedy AR System server.
Maps to: The Application Service Password field on the Connection Settings tab of the
AR System Administration: Server Information form. (See Setting server passwords, RPC
options, and plug-in timeouts.)
Required-Field-Identifier
Character to add to the label of a field whose entry mode is Required. The default is an
asterisk.
Maps to: The Required Field Identifier field on the Configuration tab of the AR System
Required-Field-Identifier-Location
Position to add the character that identifies a Required field. Values are
0 Add the character to the beginning of the field label.
1 (Default) Add the character to the end of the field label.
Maps to: The Required Field Identifier field on the Configuration tab of the AR System
RPC-Non-Blocking-IO 2
Flag that enables BMC Remedy AR System on compliant systems to receive remote
procedure calls in a nonblocking mode. The mode prevents
Remote attackers from disabling RPC services.
Invalid or corrupt packets from temporarily disabling the arserverd process. Values
are
T Run in RPC nonblocking mode. The system can process multiple headers at
the same time.
F (Default) The server must receive an entire RPC header before processing a
different one.
To make value changes take effect, restart your AR System server. Windows and Linux
operating systems do not support this feature. Important: To enable your system to use this
feature, you must install the following patches. If these patches are not installed, you see
an error message or most of your RPC calls are blocked.
HP
Page 1355 of 4705
Home
Option
Description
PHNE_29210 - HPUX 11.0
PHNE_29211 - HPUX 11i
Solaris
108993-38 - Solaris 8
113319-19 - Solaris 9
IBM Does not specify a patch number. Multiple file sets might be required. (If you do not
obtain an IBM patch, your server might crash.)
Fix for Authorized Problem Analysis Report (APAR) IY61602 - AIX 5.3
Fix for APAR IY61409 - AIX 5.2
Configuration settings S-Z

Configuration options (S-Z)
Option
Description
Save-Login
Flag indicating whether users must log in to client tools. This

option enables users to save a previous login of their choice.
Values are
0 (Default) Login is controlled by user.
1 Do not force a login controlled by the
administrator.
2 Force a login controlled by the administrator.
This option does not apply to the mid tier.
SCC-Comment-Checkin
Flag indicating whether a source code control integration

requires you to enter a comment at checkin. Values are
SCC-Comment-Checkout
Flag indicating whether a source code control integration

requires you to enter a comment at checkout. Values are
SCC-Enabled
Flag indicating whether a source code control system is being

used with BMC Remedy AR System. Values are
0 (Default) Source code control system is disabled.
1 Source code control system is in use.
Page 1356 of 4705
Home
SCC-Integration-Mode
Flag indicating the level of source code control integration.

Values are
0 (Default) Advisory level.
1 Enforced level.
SCC-Provider-Name
Name of the source code control provider. For example:

Visual Source Safe.
SCC-Target-Dir
Character string for the source code control system target

directory. If none is present, this value is NULL. This string is
limited to 255 characters.
Select-Query-Hint 2
Text to use in a query hint in the WITH clause of a SELECT

statement when queries are supplied to Microsoft SQL Server
databases. This option works only for queries triggered by
GLE, GLEWF, and GME API calls. If this option is an empty
string or is not present, no WITH clause is generated. To
determine the appropriateness of using this feature in your
environment, consult your SQL Server documentation. This
option is commonly used with a NOLOCK setting for allowing
queries to execute without being blocked by simultaneous
updates, thereby improving performance. For example, to
allow SQL Server to read data being updated and avoid
blocking, use this syntax:Select-Query-Hint: NOLOCK
Server-Connect-Name
2
New name for a server in a server group. By default, a server

in a server group uses a fully qualified server name with
domain to identify itself. Others servers in the group use this
name to communicate. To change the server name, add this
option to the configuration file:
Server-Connect-Name: <myServerName>
If a common server alias is specified, this option is required.

This name must be resolvable by DNS and is used exactly as
specified. See Configuring server groups.
Server-directory 1
Full path name of the AR System data directory. This

directory contains support and log files for the AR System
server.
Server-Group-Email-Admin-Port 2
Port number (RMIPort ) for email administration in Email

Engine. If RMIPort is different from the default (1100 ), set
this option to the new, port number to enable the server to
communicate email administration information to Email
Engine during server group processing. For example, in a
single Email Engine configuration, use this syntax:
Server-Group-Email-Admin-Port: 2020
Page 1357 of 4705
Home
Option
Description
If multiple Email Engines are configured for the server, each

engine must have a unique RMIPort. For a multiple Email
Engine configuration, use semicolons to separate the
RMIPort numbers. For example:
Server-Group-Email-Admin-Port: 2020;2030;2040
Server-Group-Flashboards-Admin-Port 2
Port number (RMIRegistryPort ) for Flashboards

administration in the Flashboards server. If the default
Flashboards port number is changed, set this option to the
new port number to enable the server to communicate
Flashboards administration information to the Flashboards
server during server group processing. For example:
Server-Group-Flashboards-Admin-Port: 2021
Server-Group-Log-File
Name and location of the server group trace log file. The
default name is arsrvgrp.log. For example:
Server-Group-Log-File: c:\temp\servgroup.log
Server-Group-Member
Flag indicating whether the server is a member of a server

group. Values are T and F (default).
Maps to: The Server Group Member field on the
Configuration tab of the AR System Administration: Server
Information form. (See Setting administrative options.)
Server-Name
An alias that is always interpreted as the current server. This

option is used in multiple server installations to differentiate
servers. If you specify a value for this option, enter the value
after the -h option when you use the arreload command-line
utility. Otherwise, arreload uses the default server name
rather than the name specified by this option. Do not specify
a fully qualified name for this option. For example, use alpha
instead of alpha.remedy.com.
Note: If this server belongs to a server group and you use a
common server alias, you must also specify the
Server-Connect-Name option. See Server-Connect-Name.
Server-Plugin-Alias
2
Alias of a plug-in server. When the BMC Remedy AR System

server calls a plug-in server, it must determine whether the
plug-in server name is an alias. Aliases can direct the BMC
Remedy AR System server to access a plug-in server
running on a different host or listening at a specified port
number. The syntax is
Server-Plugin-Alias: <aliasName> <realName> <

hostName>[:<portNumber>]
Workflow (that is, references to AR Filter API and ARDBC

plug-ins) references a plug-in name. This name can be an
alias. This enables you to run a plug-in on a remote host or to
Page 1358 of 4705
Home
Option
Description
run more than one instance of a plug-in on a host. For
example, to run the RMDY.ARDBC.XML plug-in on the
remote host foo at port number 12345, add the following
entry to the AR System server configuration file:
Server-Plugin-Alias: RMDY.ARDBC.XML
RMDY.ARDBC.XML foo:12345 The alias and real plug-in
names can be identical if you run the plug-in on a remote
host. To run more than one instance of the plug-in on the
same or different hosts, create different aliases that reference
the same plug-in on its respective hosts.
Number of seconds in which the plug-in server must respond

to a call before an error is returned. The minimum value is 0.
The maximum is 600. The default is 60.
Server-Plugin-Target-Password
Encrypted password used to call a plug-in server. The BMC

Remedy AR System server uses this password whenever it
communicates with a plug-in server running on the specified
host and port. The syntax is {{Server-Plugin-Target-Password
: <hostName>:<portNumber>: <encryptedPassword>
For server-side table fields, the number of requests (or size of

the chunk) that the server retrieves at one time from the
database and stores in memory to process during filter or
filter guide actions. The server then retrieves, stores, and
processes the next chunk until all requests are processed.
The value 0 causes the server to retrieve an unlimited
number of requests. The default is 1000 requests. Specifying
a lower value causes the server to process smaller chunks,
which reduces server memory use but results in slower
processing because the server must access the database
many times, especially for large tables. Specifying a higher
value causes the server to retrieve and process large chunks
of data and access the database fewer times. This results in
improved performance at the cost of increased memory use.
Maps to: The Server Table Field Chunk Size field on the
Configuration tab of the AR System Administration: Server
Information form. (See Setting administrative options.)
Server-Stats-Rec-Interval
Interval (in seconds) at which the server records server

statistics. The default is 60 seconds.
Server-Stats-Rec-Mode
Server statistics recording mode. This option determines

what information is recorded in the server statistics form.
Values are
0 (Default) Recording is off.
1 The server records only cumulative queue
statistics (the sum of all the individual queue statistics).
2 The server records both cumulative and individual
queue statistics. One entry is written for the cumulative
statistics and a separate entry is written for each
queue.
To see the statistics, open the Server Statistics form. See
Server statistics for baseline data.
Page 1359 of 4705
Home
Option
Description
Set-Process-Timeout
Number of seconds the BMC Remedy AR System server

waits before ending a Set Fields process that did not finish.
Values are 1 through 60. The default value is 5.
SQL-Log-File
Full path name of the file to use if SQL logging is on (see

Debug-mode).
SQL-Secure-Connection
(Microsoft SQL Server only) Flag indicating the type of

authentication to use to connect BMC Remedy AR System to
a Microsoft SQL Server database. Values are
T Windows Authentication
F SQL Authentication
SQL-Server-Set-ANSI-Defaults 2
Option that causes the server to issue a SET ANSI_NULLS

ON command.
Submitter-Mode
Flag indicating whether the Submitter field can be changed

and whether the submitter of a request must have a write
license to modify it. Values are
1 Locked mode. The Submitter field cannot be
changed after a request is submitted. If the Submitter
group has change permission, the request can be
modified by submitters with a read or write license but
not by users with a restricted read license.
2 (Default) Changeable mode. The Submitter field
can be changed after a request is submitted. If the
Submitter group has change permission, the submitter
must have a write license to modify the request.
Suppress-warnings 2
A series of zero or more message numbers (separated by

spaces) that identify informational or warning messages that
the system should suppress. Only server warnings and notes
can be suppressed.
System-Logging-Options 2
Bitmask that sets logging options for the operating system.

Values are
0 (Default) Use normal operating system logging.
Bit 1 (value = 1 ) Suppress logging to the operating
system log file.
System-Messages-Displayed
Flag to specify whether system messages appear in the

prompt bar or a pop-up box. Values are
0 (Default) Notes and warnings appear in the
prompt bar, but errors will appear in a pop-up box.
1 All system messages willl appear in the prompt
bar.
2 No messages will appear in a prompt bar. All
messages will appear in a pop-up box.
Alternatively, you can specify how system messages appear
by changing the value in the Use Prompt Bar For field on
the Configuration tab of the Server Information form.
Page 1360 of 4705
Home
Option
Description
TCD-Specific-Port
TCP port for the arserver process. If this option is not set,
the dispatcher is randomly assigned to an available port. (
TCD stands for transaction control daemon.)
Maps to: The Server TCP/IP Port field on the Ports and
Queues tab of the AR System Administration: Server
Information form. (See Setting ports and RPC numbers.)
Thread-Log-File
Full path name of the file to use if thread logging is on (see

Debug-mode).
Track-Admin-Op-Progress 2
Flag indicating whether the BMC Remedy AR System server

populates progress information (if any) during long-running
administrative operations, such as definition imports.
T Track progress.
F (Default) Do not track progress.
To retrieve the progress information, clients can use the
GetServerInfo function with the
AR_SERVER_INFO_ADMIN_OP_PROGRESS request tag.
Two-Digit-Year-Cutoff 2
Integer that specifies the cutoff year for interpreting a

two-digit year as a four-digit year. For example, if the
two-digit cutoff year is 2040:
Two-digit years fall between 1941 and 2040.
If a two-digit year cutoff is not specified, a rolling two-digit
year is used: Two-digit years are the years between the
current year plus 29 years and the current year minus 70
years. For example, if the current year is 2002, two-digit
years are the years between 1922 and 2031.
Use-FTS-In-Workflow
Controls whether the server will use full text searches when
executing queries during workflow that have full text indexed
fields in the qualification. If this option is not used, the server
will use the search capability of the database. The options
are T (use FTS in workflow) and F (do not use FTS in
workflow).
Maps to: The Use FTS in Workflow field on the FTS tab of
the AR System Administration: Server Information form. (See
FTS tab configuration options.)
Use-Password-File
Validation mechanism for unregistered AR System users. To

set this value, use the Authenticate Unregistered Users check
box in the EA tab of the AR System Administration: Server
Information form. Windows Indicates whether the Windows
domain service is used to validate users not registered with
BMC Remedy AR System. Values are
T Use domain service. Users in the Windows
domain are considered valid users of BMC Remedy
AR System and are assigned to the Public group.
F (Default) Do not use domain service.
Page 1361 of 4705
Home
Option
Description
UNIX and Linux Indicates whether the /etc/passwd file is
used to validate users not registered with BMC Remedy AR
System. Values are
T (Default) Use password file. Users in /etc/
passwd are considered valid users of BMC Remedy
AR System and are assigned to a group identified by
the UNIX group ID.
F Do not use password file.
Use-Server-Connect-Name-In-Stats 2
Flag indicating whether the server name specified by the

Server-Connect-Name option is used as the value for the
Server Name field when Server Statistics form entries are
created. Values are
T Use the Server-Connect-Name. This provides
server-specific statistics when the server runs in a
server group because the server enters a unique
server name into the Server Statistics form.
If the Server-Connect-Name is not configured, the default
behavior occurs.
F (Default) Use the host name (or server alias if
configured) with the domain name appended.
When a common server alias is specified for all servers in a
server group, the same server name is used for the servers,
effectively combining the statistics for all servers in the group.
User-Log-File
Full path name of the file to use if user logging is on (see

Debug-mode).
VersionControl-Object-Modification-Log-Mode
Option indicating whether the object modification log is

enabled or disabled. When the log is enabled, it records
every change to AR System objects in your system (see
Version control in BMC Remedy AR System). Values are
10 Enabled
You can also set this option by using the Object Modification
Log field on the Version Control tab in the AR System
Administration: Server Information form. See Setting version
control options.
Option indicating whether the AR System server writes a

definition file each time an object is created or changed (see
Version control in BMC Remedy AR System). This option is
effective only when the object modification log is enabled.
Values are
0 (Default) No, a definition file is not created.
10 Yes, a definition file is created.
Page 1362 of 4705
Home
Option
Description
You can also set this option by using the Save Definition Files
field on the Version Control tab in the AR System
control options.
VersionControl-Object-Reservation-Mode
Option indicating whether object reservation is enforced or

disabled. When object reservation is enforced, users can
reserve server objects, and BMC Remedy AR System
prevents other users from modifying the reserved objects (
see Version control in BMC Remedy AR System). Values are
10 Enforced
You can also set this option by using the Object Reservation
field on the Version Control tab in the AR System
control options.
Notifications about changes to centralized configuration

settings
When the AR System server detects any changes to the centralized configuration settings, it sends
a notification, after a 5 second delay, to the components regarding the change. Each affected
component then updates the setting across all instances.
For example, when you change the value of the arsystem.session_timeout setting, the AR
System server notifies BMC Remedy Mid Tier regarding the change. The mid tier, in turn, updates
the setting across all mid tiers in that cluster within 30 seconds.
Updating configuration settings by using the AR System

Configuration Generic UI form
Use the AR System Configuration Generic UI form from the BMC Remedy AR System
Administration Console to add or modify configuration settings for centralized components.
This topic provides the following procedures:
To add a new configuration setting
To modify an existing configuration setting
To disable an existing configuration setting
To delete an existing configuration setting
Note
Page 1363 of 4705
Home
You can continue to change the configuration settings for the following components
by using the listed form or tool:
BMC Remedy AR System server AR System Administration:Server
Information form
BMC Remedy Approval Server AP-Admin-ServerSettings form
BMC Remedy Mid Tier Mid Tier Configuration Tool
You can use the AR System Administration:Plugin Server Information form form to
change the configuration settings for Java plug-in server.
You can use the AR System Configuration Generic UI form form for BMC Remedy
Email Engine configuration settings and any other configuration settings that are
not available in the preceding forms.
To add a new configuration setting

> General > Centralized Configuration.
2. In the AR System Configuration Generic UI form, from the Component Name list, select the
component to which you want to add a setting.
3. Click Add.
4. Enter the name of the setting that you want to add and its value.
For a complete list of configuration settings, see Configuration settings.
5. Click Apply.
6. Click Close.
To modify an existing configuration setting

appropriate component.
3. From the settings table, select the setting that you want to modify.
4. Make the required change, and click Apply.
5. Click Close.
To disable an existing configuration setting

3. From the settings table, select the setting that you want to disable.
4.
Page 1364 of 4705
Home
4. Prefix the setting value with a hash symbol (#) to comment it out, and click Apply.
5. Click Close.
To delete an existing configuration setting

3. From the settings table, select the setting that you want to delete, and click Delete.
4. Click Apply and Close.
Service failover
A companion service is a process that the operating system starts (typically, when the system
starts up) or that armonitor starts. These processes communicate with the AR System server by
using the BMC Remedy AR System API to get their work and to create or change entries. In the
BMC Remedy AR System environment, companion services provide services such as the Email
Engine sending outgoing emails and handling incoming emails. You can deploy these services in a
server group, which provides resiliency if something fails. The servers in the group cooperate to
manage service failover. The server group manages when the companion services become active
to perform tasks and when they are suspended. Also, the companion services are tracked and can
fail over independently of any AR System server.
In this topic:
Monitor service failover
Companion services periodically assert their current state in the form of a heartbeat. This heartbeat
informs the AR System server of the companion service's state. When the AR System server does
not detect a companion service's heartbeat, it instructs another companion service to take over.
Note
Companion services do not have to run on the same computer as the AR System server.
Furthermore, multiple companion services can run on the same computer.
The following figure shows an example of a server group with companion services. Two companion
services (Email Engine instances) access the AR System server group through a load balancer.
Example configuration of a server group with companion services
Page 1365 of 4705
Home
The load balancer provides a single connection point, attempts to direct the load across all nodes in
the server group, and routes clients to active nodes in the server group when a node is inactive due
to a failure. Clients access the server group through the load balancer.
One companion service can perform multiple services. In this example, one Email Engine instance
can provide a service for sending outgoing emails and another service for handling incoming emails
. In such a configuration, each companion service can own, or have exclusive rights to perform
work on, any number of services. This configuration enables both companion services to process
work. (However, only one companion service can own a given service at a time.)
The companion service, in this case, would house two service providers (Email Engine instances).
The service providers' states are stored in a AR System form, and the server group manages those
states.
If the AR System detects that a companion service's heartbeat has stopped, it can instruct another
companion service to take over. Each service provider can fail over independently of the other
servers and independently of a given AR System server.
Monitor service failover

The following forms enable you to monitor or manage failover:
AR System Service Failover Ranking The form that you use to manage the ranking of
each service provider. You can view and change entries in this form. To change the ranking
of a service provider, see Changing the ranking of a service provider .
Page 1366 of 4705
Home
AR System Service Failover Whiteboard A form that stores the current status of all
service providers. You can use this forms entries to see which clients are:
Providing a service
Waiting to provide a service
Unavailable
Warning
Do not modify the existing workflows on these forms.
The following topics provide information about service failover:

Service provider states
Service failover ranking entries
Changing the ranking of a service provider
Naming conventions for service names
Email engine service failover in a server group

A single companion service can provide multiple services. Each service has a state that is stored in
the AR System Service Failover Whiteboard form.
State transitions

State
Description
Active
The service provider is processing requests.
Page 1367 of 4705
Home
State
Description
Suspending
The service provider has been told to complete or abort any in-progress request and relinquish ownership of the
service.
Waiting
The service provider is available to process requests.
Unavailable
The heartbeat from the service provider is no longer being detected. (As part of a graceful shutdown, the service
provider can assert that it is no longer available.)
Within a server group, one node has an active service failover controller, which drives state
transition for the group. If the AR System server with that node goes down, another node in the
server group receives ownership of the controller. For more information about the controller, see
Service Failover Ranking Entries.
Service provider state transitions
Original
New state
state
Changes driven by the AR
Changes driven by the service provider
System server
Active
Unavailable
The AR System server did not

detect a heartbeat, which
indicates that the service provider
is not working or is unavailable to
take ownership of a service.
The service provider has shut down and is no longer available.
Waiting
Unavailable

is no longer available to take
ownership of a service.
The service provider has shut down and is no longer available.
Suspending
Unavailable

is still gracefully suspending work
in progress.
The service provider gracefully completes all the in-progress

requests and then is no longer available.
Active
Suspending
The AR System server intends to

fail over the service from one
service provider to another. The
AR System server gives the active
service provider the ability to
gracefully finish any work that is
currently under way.
Not applicable. The service provider cannot assert a suspending

state.
Active
Waiting
Not applicable. Only the service

provider can assert a waiting state
.
The service provider has completed its requests and intends to

give the AR System platform the opportunity to recalculate the
highest ranked service provider for the service. The AR System
server would detect that there is no active service provider for
the service, examine the ranking criteria and available service
providers, and give ownership to (that is, make active) the
appropriate service provider.
Waiting
Active
The AR System server intends to

fail over the service from one
service provider to another. The
AR System server indicates to a
Not applicable. Only the AR System server can determine and

assign ownership of the service.
Page 1368 of 4705
Home
Original
state
New state
Changes driven by the AR

System server
Changes driven by the service provider
waiting service provider that it

should take ownership of the
service and begin processing.
Related topic
Verifying the state of the service provider

The controller creates an entry in the AR System Service Failover Ranking form under the following
circumstances:
When an entry is created in the AR System Service Whiteboard form
When a waiting or active provider is examined as a possible highest rank
If no other rankings exist for the service, the entry receives a ranking of 1. If other rankings exist,
the entry receives a null ranking (that is, an unset ranking), which is treated as the lowest ranking (
MAXINT (232 - 1)). This ranking assumes that existing providers are already working, and a failover
is not triggered when you introduce a new provider.
Rank is in ascending numerical order. Service providers with the numerically lower rank are chosen
before ranks of greater value (negative-valued rank takes a higher precedence over positive-valued
rank). If two providers of the same service have the same rank, then the service failover controller
chooses one.
Changing the ranking of a service provider

Administrators can use the AR System Service Failover Ranking form to view and manage
rankings.
To change the ranking of a service provider

1. In a browser, open the AR System Service Failover Ranking form in search mode:
http://midTierServer:portNumber/arsys/forms/ARSystemServer/AR+System+Service
Failover+Ranking/
2. Perform a search to see the entries in the form, and select the required entry.
3. Change the value in the Rank field.
The valid value for this field is any integer.
Note
A negative-valued rank takes precedence over a positive-valued rank.
Page 1369 of 4705
Home
4. Save the form.
Related topic
Naming conventions for service names

Service names are unique and use the following syntax to ensure uniqueness:
nameSpace://service-name
nameSpace uniquely identifies the type of service: com.bmc.arsys.emaildaemon.

service-name is specific to the implementation of the service.
Note
For Email Engine, the service-name is made up of two parts: mailboxFunction/
mailboxName.
mailboxFunction refers to the incoming or outgoing service.
mailboxName refers to the name of the mailbox from the AR System Email Mailbox
Configuration form.
For example:
com.bmc.arsys.emaildaemon://outgoing/IN-REMDEV
com.bmc.arsys.emaildaemon is the nameSpace.
outgoing/IN-REMDEV is the service-name.
Related topic
Email engine service failover in a server group

In this topic:
Service failover scenario 1
Related topic
Page 1370 of 4705
Home

Consider a scenario where you configure BMC Remedy Email Engine in a server group
environment, behind a load balancer, and one of the AR System servers goes down. Since
everything is routed via the load balancer, the associated email engine service continues to run.
To configure Email engine behind a load balancer, perform the following steps:
1. Open the EmailDaemon.properties file located in the ARSystemInstallDir\BMCARSystem
\AREmailfolder and modify the following properties to point to the AR System server alias:
com.bmc.arsys.emaildaemon.serverName.TCP
com.bmc.arsys.emaildaemon.serverName.Password
com.bmc.arsys.emaildaemon.serverName.Language
com.bmc.arsys.emaildaemon.serverName.Interval
com.bmc.arsys.emaildaemon.Servers
com.bmc.arsys.emaildaemon.serverName.RPC
com.bmc.arsys.emaildaemon.serverName.Authentication
2. Open the C:\WINDOWS\system32\drivers\etc\hosts file and add the following alias entry,
and save the file:
IPAddress serverName
Where,
IPAddress is the IP address of the load balancer
serverName is the server name alias of the load balancer

Consider another scenario, where you configure Email Engine in a server group environment,
behind a load balancer, and one of the Email engine services (inbound email) goes down. The
second email engine service now handles both the inbound and outbound services.
Page 1371 of 4705
Home
Note
When you configure two Email engines (Email Engine1 and Email Engine2) in a server
group environment, by default, Email Engine1 will be the primary server for both inbound
and outbound services.
To configure Email Engine1 as the primary server for inbound, and Email Engine2 as the primary
for outbound, you must perform the following steps:
1. Open the AR System Service Failover Ranking form.
2. For the following entries, change the values in the Rank field to 2.
Entry for Email Engine1 outbound service.
Entry for Email Engine2 inbound service.
3. Restart the Email engine services for the changes to take effect.
Related topic
This section describes how to administer BMC Remedy AR System security. Topics include:
Creating users, groups, and roles
Access control
Setting up an authentication alias
Restrictions when logging in to a BMC Remedy AR System server
Understanding database security issues
Using audit records
Page 1372 of 4705
Home
Creating users, groups, and roles

These sections provide an overview of BMC Remedy AR System users, groups, and roles:
Creating and managing users
Adding and modifying user information
Creating and managing groups
Creating and mapping roles
Creating and managing users

A user is any person to whom you give permission to access BMC Remedy AR System. Users can
be members of multiple groups or no group at all. Users in BMC Remedy AR System range from an
administrator (who maintains the entire system) to employees (who submit requests or view data).
BMC Remedy AR System includes one predefined user ( Demo). You can use the User form in a
browser to rename this user and create additional users. For information about defining users for
BMC Remedy AR System, see Adding and modifying user information.
Use the following procedures to create, modify, or delete BMC Remedy AR System users and to
enable users to change their information. You can apply the three Fixed licenses included with
BMC Remedy AR System to new users.
To create users
To modify user information
To delete users
To enable users to change user record information
To create users
1. Log in to a browser.
If you are the first administrator to log in, you must log in as Demo and leave the Password
field empty. (BMC Remedy AR System user names are case-sensitive, which means that
you must type Demo, not demo or DEMO.)
During initial installation, the Demo user is installed without a required password. To keep
BMC Remedy AR System secure, add a password for this user as soon as possible.
2. From the AR System Administration Console, click System > Application > Users / Groups
/ Roles > User.
The User form opens in Search mode.
3.
Page 1373 of 4705
Home
3. Choose Actions > New to switch to New mode.

4. Enter information in the appropriate fields, as described in the User form fields table.
To modify user information

/ Roles > User.
2. Click Search to retrieve a list of defined users.
3. Select the appropriate user from the list.
4. Modify information in the appropriate fields.
Warning
If you modify the Demo user's Fixed license or Administrator group membership
before you create another Administrator user, you lose administrator privileges.
To delete users
/ Roles > User.
4. Choose Actions > Delete.
A confirmation box appears to verify that you want to delete the selected users.
5. Click OK.
Warning
If you delete the Demo user before you create another Administrator user, you
lose administrator privileges.
To enable users to change user record information

1. Open the User form in BMC Remedy Developer Studio.
2. Make the User form's Assigned Tofield visible. (By default, the field is hidden.)
a. Double-click the Assigned To field to open the field Properties dialog box.
b. In the Display tab, clear the Hidden check box.
3.
Page 1374 of 4705
Home
3. Give the Assignee group Change permission for the Password, Default Notify
Mechanisms, or Email Address fields.
4. Give public "visible" permissions.
See Field permissions.
5. Save your changes, and close BMC Remedy Developer Studio.
6. In a web client, open the AR System Administration Console, and click System >
Application > Users / Groups / Roles > User .
The User form opens in Search mode. The Assigned To field is visible in the User form.
7. Retrieve a list of defined users.
9. Copy the Login name to the Assigned To field to make the user the Assignee.
By using the Assignee group, you enable the user to modify the user's password, default
notification mechanism, or email address.
You can also make the user the Submitter by entering the same name in the Login name
field and in the Creator field.
Adding and modifying user information
Important
If you use BMC Remedy AR System-based applications, set up users in each
application's People form, not in the User form. For more information, see the application
documentation.
In BMC Remedy AR System, you can have registered users and guest users. Each type of user
has different privileges within the system, as discussed in the following sections.
You enter data in the User form to define the components that work together to determine each
user's access to BMC Remedy AR System: login name, password, group membership, and license
type. You also define notification information for each user in this form. For information about the
restrictions for creating or modifying user information, see Restrictions.
To grant a user permission for BMC Remedy AR System objects, add the user to the groups to
which access will be given. To make a user part of a group, choose the appropriate group from the
Group List menu in the User form. (Multiple group names in the Group List field are separated by
spaces.) You can select from the reserved BMC Remedy AR System groups.
Notes
Page 1375 of 4705
Home
If the group information is returned through external authentication, you cannot be

a part of any administrator group. You can be a part of the administrator group only
from the User form. For information about setting up for external authentication,
see Configuring the AR System server for external authentication and Specifying
internal and external authentication.
You can get group information from external authentication only if the Group List is
NULL.
For more information, see Groups in BMC Remedy AR System .

User form in new mode
The following table lists the key fields in the User form.
Key fields in the Roles form
Area name
Field
Description
User
Information
Login Name
Identifying name that the user enters into the User Name field when logging in to BMC Remedy
AR System. The name can be the same or different than the user name by which this user is
known to the underlying operating system. The dynamic group with an ID of 60988 has read
access to this field, enabling the user to view this field if a password policy is established. See
User
Information
Full Name
Full name of the user.
User
Information
Password
Identifying password that the user enters when logging in to BMC Remedy AR System. This field's
length is 30 bytes, so you can enable users to enter as many as 30 bytes.
Note: Users cannot enter a 28-character password, or an error will occur during authentication.
The Password field is encrypted into the database by using a one-way hash (SHA-1), so
unauthorized users cannot retrieve passwords in clear text, for example, to log in to applications.
To enhance system security, select a password that is different from one used for another purpose
. If unsecure passwords are needed for applications, store the password in a character field rather
than the Password field (field 102). If the Password field is left blank, the BMC Remedy AR
System server does not validate the password with the user's Windows or UNIX password, unless
Page 1376 of 4705
Home
Area name
Field
Description
you configure the server to cross-reference a blank password. See Cross-referencing blank
passwords. The dynamic group with an ID of 60988 has read access to this field, enabling the
user to view this field if a password policy is established. See Enforcing a password policy
introduction.
User
Group List
Information
The access control groups to which the user belongs. If you leave this field empty, the user has
only basic Submitter, Assignee, Assignee Group, or Public permissions. Specify groups by name
or ID, as defined in the Group form. User permissions are determined in the Group List field of
the User form. If you later change the Group ID for a group, the users originally assigned to the
group are still attached to the old ID. If no group has the old ID, these users lose access to any
BMC Remedy AR System object for which they do not have permission through another group. If
you choose to This field is limited to 4000 bytes, including expanded strings. See Groups in BMC
Remedy AR System.
Note: If you create multiple groups with the same ID, the User form displays the first available
group name for the selected group id.
User
Information
Computed
Group List
The names of the computed groups to which the User is a member. The members of a computed
group are calculated by the server based on the groups that the User belongs to. This is a
display-only field, and the field ID is 121. To search in this field in a query-by-example, enter the
ID number of a computed group. To enter more than one computed group ID, include semicolons
after each ID. You must enter the computed group IDs in the same order in which the names
appear in the Computed Group List field when the user's record is displayed. In the following
examples:
The ID for Computed Group 1 is 5678.
The ID for Computed Group 2 is 6789.
You can also use the Advanced Search bar with the LIKE operator. Include the semicolon
with the complete ID.
To search for users who are members of Computed Group 1, enter:
'Computed Group List' LIKE "%5678;%"
You can also enter a partial ID for the computed group.
To search for users who are members of both Computed Group 1 and Computed Group 2,
enter:
'Computed Group List' LIKE "%56%" AND 'Computed Group List' LIKE "%89%"
User
Full Name
Full name of a user. By default, this name appears in the Results pane of the User form when
users perform a search operation.
User
Information
License
Type of license that the user is assigned: Read , Restricted Read , Fixed, or Floating. The default
is Read. See License types overview for further descriptions of these types.
User
Information
Application
License
Information
Type
List of application licenses granted to the user. For example, BMC Change Mgmt User Fixed,
where BMC Change Mgmt is the name of the application and User Fixed is the type of license.
BMC Remedy AR System automatically populates this field according to information entered in the
application's People form.
Note: To use BMC Remedy AR System-based applications from BMC Software, users need an
BMC Remedy AR System user license (to access the BMC Remedy AR System server) and an
application user license (to access the application).
Page 1377 of 4705
Home
Area name
Field
Description
User
Information
Default
Notify
Mechanism
Method by which the user is notified for Notify filter and escalation actions when User Default is
specified. The default setting on the User form is Alert.
User
Information
Email
Email address used to notify the user if email is the notify method.
User
Information
Status
Address
Defines the status of the user account. This field is for information only. It does not change the
status of a user's account. This field is set through workflow if you set a password policy. See
Enforcing a password policy introduction. The options are:
Current---The account is in use.
Disabled---The account is no longer in use.
User
Information
Allowed
Client Types
Allows the user to make API calls using only the client types mentioned in the Allowed Client
Types field.
To enter more than one client type ID, include semicolons after each ID. In the following example,
the user can make an API call only to BMC Remedy Mid Tier, BMC Remedy Developer Studio
and BMC ProactiveNet Performance Management.
If the user makes an API call to the Client Type not assigned in the Allowed Client Types field,
the API call fails with the following error:
ARRER 8937: You do not have permission to the client operation.
If the Allowed Client Type field is left blank, the user can make API calls using any client type.
For more information on the list of Client types, see List of Client Type ID.
Password
Management
Disable
Password
Management
For This
User
Disables password management for the user. If this check box is selected, when the User
Password Management Configuration form is updated, the user is not affected. For more
information about password management, see Enforcing a password policy introduction.
Password
Management
Dynamic
Group
Access
The dynamic group to which the user belongs.
Password
Management
Last
The last time the password was changed. BMC Remedy AR System automatically updated this
field when a user's password is changed.
Password
Management
Account
Disabled
Date
The date the account was disabled, if applicable.
Password
Management
Force
Indicates that the user must change the password. The next time the user logs in, the user is
prompted to change the password. After the password is changed, the check box in the User form
is automatically cleared through workflow.
Password
Change for
Policy
Password
Change on
Login
Password
Management
Number of
Days Before
Expiration
The numbers of days before a user's password expires if it is not changed.
Page 1378 of 4705
Home
Area name
Field
Description
Password
Management
Number of
Warning
Days
Indicates when a user receives a warning message before the password is set to expire unless
changed.
Password
Management
Days After
The number of days after which a user's account is disabled if the password is not changed.
Expiration
Until
Disablement

You cannot create other users with more administrative rights than yourself, and you cannot modify
your own rights.
The new restrictions are applied to prevent:
Creation of an administrative user by a non-administrative user.
Creation of an administrative user with access to more overlay groups than the
administrative user who created them.
The following restrictions are applied before and after you create or modify any user in the User
and Group form.
1. Only an administrator can create, modify, or delete other users belonging to the
Administrator, Sub-Administrator, Struct Admin, or Struct Sub-Admin groups.
A user must have Group ID 1 (AR Administrator) in the group list to create/modify/
delete another user with any of the four administrative class groups in their group list.
2. No Admin user can create or modify a user (themselves included) with lesser administrative
restrictions than the user making the modification.
For example, an administrator user with Overlay Group 1 cannot create or modify users with
no overlay groups. Consider a situation where you have created an ABCGroup with an
Overlay Group set to 1. User ABCAdmin is part of Administrator group and ABCGroup.
However, ABCAdmin is restricted only to the ABCGroup. ABCAdmin can change (create/
modify/delete) any user belonging only to the ABCGroup. For more information about
creating a group as an overlay group, see Creating groups.
A user cannot create another admin user with the ability to modify base objects if they
themselves cannot do it.
BMC recommends that you should restrict your users to make modifications only to
custom objects and overlays.
3. Only an unrestricted administrator can create, modify, or delete groups that restrict a users
administrative capabilities.
Only an administrator with no overlay specific groups can create, modify, or remove
overlay specific groups.
Page 1379 of 4705
Home
Creating and managing groups

Access control groups are collections of BMC Remedy 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.
BMC Remedy 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.
BMC Remedy AR System provides two types of groups:
Explicit groups Groups 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 Creating and mapping roles and Adding and modifying user
information
Implicit groups Groups 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.
Creating groups
This section provides the steps to create BMC Remedy 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 Adding and modifying user information, to assign individual users to the appropriate groups.
Use the Group form (shown in the following figure) in a browser to create and manage the access
control groups to which you grant or deny access to AR System objects. BMC recommends that
you should restrict your users to make modifications only to custom objects and overlays.
Note
Page 1380 of 4705
Home
You must log on as an Administrator to work with the Group form.
Group Information form New mode

The following table lists the fields you can set the Group form.
Fields in the Group Information form
Field
Description
Group
Name of the access control group. Use this name in the Group list field in the User form and in the Permission and
Name
No Permission lists when you are defining BMC Remedy 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:
0 1000 For AR System groups and current AR System applications
1000 1049, 1061 13004, 13021 13999, 14102 14450, and 14452 14998 For non-BMC regular
and computed groups
1050 1060, 13005 13020, 14000 14101, and 14451 Reserved for current AR System applications
14999 59999 For current and future AR System applications
60000 and 60002 60099 For non-BMC dynamic groups
60001 and 60100 60999 For AR System application dynamic groups
61000 99999 For AR System applications
100000 999999999 For non-BMC regular and computed groups
1000000000+ For BMC company permissions
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 Remedy
Administrator to build a unique inde on the Group ID field in the Group form. (See Defining indexes.) The Group ID
defines the priority of a group when a user obtains a floating license. See About floating licenses in a license pool.
Note: If you create multiple groups with the same ID, the User form displays the first available group name for the
selected group id.
Page 1381 of 4705
Home
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. See Field permissions.
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 the mid tier when listing groups.
Group
Category
The group category, such as Regular, Dynamic, or Computed, which is described in Regular, computed, and
dynamic groups. 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 .
Information about setting permissions inheritance for an object, see Assigning permissions for individual or
multiple objects.
Information about row-level access control and hierarchical groups, see Controlling access to requests for
hierarchical groups.
Overlay
Use the setting to define the group as an Overlay Group. The Overlay Group option on the Group Information Form,
Group
provides the following access options:

Overlay Group field set to 1: When a group assigned to the user has the Overlay Group field 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 set to 0, 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.
Overlay Group field set to 999999999: When a group assigned to the user has the Overlay Group field set to
999999999, the user can work only in read-only mode on all base, overlay, and custom objects.
For more information, see Groups in BMC Remedy AR System and Operations on objects restricted by development
mode.
Note: Do not assign an overlay to a computed group. If you assign an overlay to a computed group, the ARERR
8821 warning occurs and the computed group is saved with Overlay Group as NULL in the AR System server.
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 NOT. Optionally, use the AND, OR, NOT, Append Group, Append User, and parentheses buttons
to build the qualification string.
Examples
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.
Page 1382 of 4705
Home
"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 About floating licenses in a license pool. If this field is
missing from the Group form, you can add it using Remedy Administrator. Use field ID 115. See Creating data fields.
Application
Floating
License
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'.
Example
For a 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;
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 Remedy Administrator to add the field. Use field ID 115. See Creating
data fields.
To use BMC Remedy AR System-based applications from BMC Software, you need an BMC Remedy AR System
user (floating) license (to access the BMC Remedy 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.
Datatag
Tags the data record as needed. This field is optional. For example, it can store the name of the application which
uses this group.
Note
Page 1383 of 4705
Home
If attributes that you want to specify in the group definition are not represented in the
Group form, you can use Remedy Administrator to add the appropriate fields. However,
be careful that you do not modify or delete any of the original fields or field IDs.
To create groups
1. In 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.
For a regular group, assign users to it by using the User form in a browser.
After you save a group, the server automatically reaches, and the new group appears in the
Group menu in the User form after a short delay. For more information about adding users,
see Adding and modifying user information.
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.
Note
If you create and save a group in the Group form using a browser, and then flush the mid
tier cache, the new group still does not appear when a user opens the field menu of a
group list in a form. The user must click the browser Refresh button to see the new group.
Managing groups
You can modify, delete, or search for groups in the Group form.
To search for groups

1. In 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 Operators for more
information.) 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 BMC Remedy 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.
Page 1384 of 4705
Home
To modify groups
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.
To delete groups
2. Perform a search to retrieve a list of currently defined groups.
3. Select the appropriate group from the list.
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 user's 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.
Struct Admin group permissions

When assigning Struct Admin permissions, you will need to create a group to provide access to the
objects from the schema and assign it to Struct Admin. The following table lists all objects the
Struct Admin permissions group must provide.
For more information about structural administrators options, see:
Special groups in BMC Remedy AR System
Creating groups
Access level options for administrators
The Access Type field in the following table lists the access that BMC Remedy Developer Studio
needs to the fields of the listed form.
If the Access Type is Read, grant the Struct Admin Permissions group View permission to
the form's fields.
If the Access Type is Read/Write, grant the Struct Admin Permissions group Change
permission to the form's fields (except field 1, which should always have View permission).
StuctAdmin group permissions matrix
Page 1385 of 4705
Home
Form Name
Access
Type
Details
Data Visualization Definition
Read/
Write
This form is used for all Flashboard, Flashboard Variable and Flashboard
Alarm. BMC Remedy Developer Studio needs read-write access for this form.
Data Visualization Module
Read
This form is used in Form Editor to populate the Module Type property of Data
Visualization Field.
AR System Metadata: actlink
Read
All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata:
actlink_auto
Read
AR System Metadata:
actlink_call
Read
AR System Metadata:
actlink_dde
Read
AR System Metadata:
actlink_goto
Read
AR System Metadata:
actlink_group_ids
Read
AR System Metadata:
actlink_macro
Read
AR System Metadata:
actlink_macro_parm
Read
AR System Metadata:
actlink_mapping
Read
AR System Metadata:
actlink_message
Read
AR System Metadata:
actlink_open
Read
AR System Metadata:
actlink_process
Read
AR System Metadata:
actlink_push
Read
AR System Metadata:
actlink_serviceaction
Read
AR System Metadata:
actlink_set
Read
AR System Metadata:
actlink_set_char
Read
AR System Metadata:
actlink_sql
Read
Read
Page 1386 of 4705
Home
Form Name
Access
Type
Details
AR System Metadata:
arcontainer
Read
AR System Metadata:
arctr_group_ids
Read
AR System Metadata:
Read
Read
AR System Metadata:
arschema
Read
AR System Metadata:
char_menu
Read
AR System Metadata:
char_menu_dd
Read
AR System Metadata:
char_menu_file
Read
AR System Metadata:
char_menu_list
Read
AR System Metadata:
char_menu_query
Read
AR System Metadata:
char_menu_sql
Read
AR System Metadata:
cntnr_ownr_obj
Read
AR System Metadata:
escal_mapping
Read
AR System Metadata:
escalation
Read
AR System Metadata: field
Read
AR System Metadata:
field_char
Read
AR System Metadata:
field_column
Read
AR System Metadata:
field_curr
Read
AR System Metadata:
field_dispprop
Read
Read
AR System Metadata:
actlink_wait
arctr_subadmin
AR System Metadata:
arreference
Page 1387 of 4705
Home
Form Name
Access
Type
Details
AR System Metadata:
field_enum_values
Read
AR System Metadata:
field_permissions
Read
AR System Metadata:
field_table
Read
AR System Metadata: filter
Read
AR System Metadata:
filter_call
Read
AR System Metadata:
Read
AR System Metadata:
filter_log
Read
AR System Metadata:
filter_mapping
Read
AR System Metadata:
Read
AR System Metadata:
filter_notify
Read
AR System Metadata:
filter_process
Read
AR System Metadata:
filter_push
Read
AR System Metadata:
Read
AR System Metadata:
filter_set
Read
AR System Metadata:
filter_sql
Read
AR System Metadata: image
Read
AR System Metadata:
schema_archive
Read
AR System Metadata:
schema_audit
Read
AR System Metadata:
schema_group_ids
Read
AR System Metadata:
schema_index
Read
AR System Metadata:
field_enum
filter_goto
filter_message
filter_serviceaction
Page 1388 of 4705
Home
Form Name
Access
Type
Details
AR System Metadata:
Read
AR System Metadata:
schema_list_fields
Read
AR System Metadata:
subadmin_group
Read
AR System Metadata:
Read
Read
AR System Metadata: vui
Read
AR System Administration:
Read
This form is used by the Analyzer to read configuration data.
AR System Ignored Analyzer

Results
Read/
Write
This form is used by the Analyzer to store results marked as Ignored.
User
Read
This form is by the Analyzer to read user permissions.
AR System Object
Relationships
Read
This form is used to calculate related objects. It is used extensively in Search,

Analyzer, Object List, Relationships and Workflow Viewer.
Groups
Read
This form is used in Group Object List, Search and Analyser.
Roles
Read
This form is used to read user roles.
AR System Administrator
Preference
Read/
Write
These forms are used to read and write administrator and user preferences.
Read/
Write
These forms are used to read and write administrator and user preferences.
AR System Version Control:

Object Reservation
Read/
Write
These forms are used for Object Reservation feature.

Object Modification Log
Read
These forms are used for Label Management.

Label
Read/
Write
Read/
Labeled Object
Write
AR System Currency Codes
Read
This form is used to get currency types that are shown in the Currency Types
property of a currency field.
AR System Orchestrator
Configuration
Read
This form is used in Set Fields action when Data Source is set to Webservice.
ReportType
Read
This form is used by Open Window action when Window Type is set to Report.
Distributed Mapping
Read/
Write
These forms are used in Distributed Mapping and Distributed Pool editors
schema_join
vendor_mapping
AR System Metadata:
view_mapping
Server Information
Page 1389 of 4705
Home
Form Name
Access
Type
Details
Distributed Pool
Read/
These forms are used in Distributed Mapping and Distributed Pool editors.
Write
DSO Distributed Logical
Name
Read
Used by DSO Editors and DSO action to read logical names.
BMC Remedy Localization

Toolkit: Items
Read/
Write
This form is used by L10n Toolkit.

Toolkit: Location Package
Join
Read
These forms are used by L10n Toolkit.

Toolkit: Location Package
Read

Toolkit: Locations
Read/
Write

Toolkit: Translations
Read/
Write
Read/
Toolkit: Translations Audit
Write
AR System Resource
Definitions
Read/
Write
This form is used for localizing templates.
AR System Message Catalog
Read/
Write
This form is used for localizing messages.
AR System Currency Label

Catalog
Read
This form is used to read localized current code.
Link
Creating and mapping roles

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 application's 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.
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.
Page 1390 of 4705
Home
Use the Roles form 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 Defining and managing an application. 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.
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. To enable
a particular mapping, change the application's state. For more information, see Working with
deployable application states.
Use the following procedures to create, modify, or delete BMC Remedy AR System roles:
To create and map roles
To modify roles and role mappings
To delete roles
The following table lists the key fields in the Roles form.
Key fields in the Roles form
Field
Description
Application
Name
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.
Role Name
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.
Role ID
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.
Test
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 application's State property to Test. For more information, see
Working with deployable application states.
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 application's State property to Production. For more
information, see Working with deployable application states.
Page 1391 of 4705
Home
To create and map roles

1. In 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.
Note
- BMC Remedy AR System does not maintain the list of Application names. The
BMC Remedy AR System Administrator should keep a note of all the Application
names.
- 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 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.
To delete roles
1. In 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 role.
A confirmation box appears to verify that you want to delete the role entry.
5. Click OK.
Page 1392 of 4705
Home
Administrator security role

BMC Remedy AR System provides administrators with interfaces to manage security policy and its
implementation in the AR System Administration Console, BMC Remedy Developer Studio, and the
BMC Remedy Mid Tier Configuration Tool. These clients allow the administrator to manage server
objects and system configuration settings, and to control access to AR System by human users,
BMC Remedy-based applications, and other external clients.
All user access definition and management is performed through forms that are accessible to
administrators. Policy management and implementation are controlled through the use of access
control groups and security role definitions and privileges. Access control groups are the basis by
which all user access is granted. Access control in AR System is additive. Each user starts out with
no access to AR System controlled objects, and administrators or subadministrators add
permissions as needed. Administrators can set default permissions and specific permissions on
objects in AR System, and subadministrators can set specific permissions to objects where
assigned.
Roles, including security roles, are specified in the AR System by membership in groups. The AR
System reserves eight group IDs for special group definitions with associated access privileges,
including the groups administrator and subadministrator. Members of the administrator group have
the security role administrator. Members of the subadministrator group have the security role
subadministrator.
Configuration of application servers, including application server passwords, is controlled by
administrators using the AR System Administration: Server Information form and other forms
accessible to the administrator through a browser. Many settings managed in the AR System
Administration: Server Information form are stored in the server configuration file ( ar.cfg on
Windows or ar.conf on UNIX). The administrator must protect this and other configuration files from
tampering by setting the appropriate directory permissions and file settings. In addition to the file
protections assumed to be provided by the operational environment, application service passwords
stored in configuration files are obfuscated using a proprietary implementation of DES.
Access level options for administrators

In your application development and production environments, you can provide different levels of
access for administrators. 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 set to 1, the user is
restricted to working on overlay and custom mode objects. In BMC Remedy Developer
Studio, the user can work only in Best Practice Customization mode.
Page 1393 of 4705
Home

When a group assigned to the user has the Overlay Group field set to 0, the user is
restricted to working on base mode objects. In BMC Remedy Developer Studio, the user can
work only in Base Developer mode.
When a group assigned to the user has the Overlay Group field set to 999999999, the user
is restricted from creating, modifying, deleting, and importing objects. The user can only read
and export objects from all layers.
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. For more information about Overlay Groups, see Creating
groups.
When you assign a user to a group with Overlay Groups set to 1, you must also assign the
user to the Struct Admin or Struct Subadmin group. For more information, see Groups in
BMC Remedy AR System and Operations on objects restricted by development mode.
To create a new group with the Overlay Group option set to 1

1. From the BMC Remedy AR System Administration Console, navigate to: Application >
Users/Groups/Roles > Groups
2. Create the Group as desired and select 1 in the Overlay Group drop-down menu, to make it
an Overlay Group.
To create Struct Admin Permissions

1. From the BMC Remedy AR System Administration Console, navigate to Application >
Users/Groups/Roles > Groups
2. Create a group named Struct Admin Permissions, to provide access to the objects.
3. Set the Group Category field to Regular.
4. Set the Group Type field to Change.
To assign group assignments to a user

1. From the BMC Remedy AR System Administration Console, navigate to Application >
Users/Groups/Roles > Users
2. Make sure the user is assigned the following groups:
Struct Admin
Struct Admin Permissions
Page 1394 of 4705
Home
For details see Struct Admin group permissions.
Subadministrator security role

Administrators, members of the Administrators group, can use BMC Remedy Developer Studio to
view every AR System server object and can modify any object that is not reserved by another user
. You can use Subadministrator Permissions to grant administrator access to a subset of existing
forms, local applications, and workflow to subadministrators, members 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.
The following figure is an example of using Subadministrator Permission to enable users to
maintain some objects on an AR System server.
Users administering forms
Rights for subadministrators

Subadministrators can perform the following functions:
Log on to BMC Remedy Developer Studio
When you log on as a Subadministrator, the server icon in Encryption Security 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
Page 1395 of 4705
Home
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.
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 BMC Remedy Encryption Security.
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.
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 Subadministrator security roleshows, 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 Version control in
Page 1396 of 4705
Home
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 application's 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 Subadministrator security role.
To grant subadministrator capabilities to a user

1. In 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.
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, select the Definitions tab. In the Permissions panel, expand the
Subadministrator Permissions sub-panel.
For a local application or a packing list, in the Properties tab, click the Permissions
> 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 permissions as
are assigned for the individual forms in the application.
The members of the group or role have the same privileges and permissions that an administrator
has for that object.
Page 1397 of 4705
Home
Access control
This section provides an overview of the BMC Remedy AR System access control. Topics include:
Additive access control
User and group access
Access to BMC Remedy AR System objects
Access to requests
Assigning permissions
Struct Admin group permissions
Note
For information about role-based access, see Role-based access overview.
Access control is the BMC Remedy AR System mechanism that controls which users can open an
application, form, or guide in a browser, can perform an action, and can create, view, modify, and
delete a request. You can configure AR System to run with limited access privileges and access to
limited set of resources on the host machine. This prevents malicious scripts or programs from
being installed on the machine.
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 BMC Remedy 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. BMC Remedy AR System has various levels of security:
Server Controls access to the BMC Remedy 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 workflow Controls access to BMC Remedy 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.
Page 1398 of 4705
Home
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 field-level permission.
The following figure presents an overview of access control, and lists the questions that you can
use to determine the access that users have to BMC Remedy AR System.
Access control overview
Page 1399 of 4705
Home
User and group access

See User and group access overview for a description of user and group access and Types of
access control groups for a description of explicit and implicit groups.
Users in BMC Remedy AR System
Groups in BMC Remedy AR System
Regular, computed, and dynamic groups
Using a parent group for permissions inheritance
Users in BMC Remedy AR System

Groups in BMC Remedy AR System

Access control groups are collections of BMC Remedy 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.
BMC Remedy 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.

BMC Remedy AR System reserves the following group IDs for special group definitions. The
following table describes the access privileges for each of these groups.

Group
ID
Type
Description
Public
Implicit
Provides general access. Access granted to this group is granted to all users. Every user who logs
in to BMC Remedy AR System is automatically a member of the Public group. This includes
registered users (that is, listed in the User form) and guest users.
Page 1400 of 4705
Home
Group
ID
Type
Description
Administrator
Explicit
Defines users who have full and unlimited access to BMC Remedy AR System. Administrators,
members of this group, can view any object or field in a browser and can create a request in any
form. Administrators can view, create, modify, and delete any server object in Remedy Administrator
. 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 the mid tier. Use this group with
caution.
Submitter
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. See Enabling
submitters to modify requests, 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.
Sub
Administrator
Explicit
Provides administrative access to selected server objects. Subadministrators, members of this

group, can 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 Subadministrator security role. 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
user's name. For more information, see Assignee Group access and Form, active link guide, and
application permissions.
Note
Do not confuse this group with the Assignee group, which gives permission to the
individual user named in the Assignee field.
Struct Admin
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.
Note
For more information about Struct Admin permissions, see Struct Admin group
permissions.
The assigned user must have a fixed license or this group assignment is ignored.
Struct
Subadmin
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 might present a conflict with custom type assignments.
Page 1401 of 4705
Home
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.
Regular, computed, and dynamic groups

You can create the following groups in the Group form.
Regular groups Explicit groups that you create and to which you assign a specific list of
users. For information about assigning users to groups, see Adding and modifying user
information.
Computed groups Explicit 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
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.
Dynamic groups Implicit 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.
BMC Remedy AR System provides two types of groups:
Explicit groups Groups 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 Role-based
access.
For information about assigning users to groups, see Adding and modifying user information.
Implicit groups Groups 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.
Here are access control group types:
Access control group types
Page 1402 of 4705
Home
Type
of
access
control
group
Description
Explicit
A group to which you must assign users.
Predefined groups
1
Administrator
Sub
Administrator
Customize
Custom groups 2
Any regular and computed groups that you create.

Regular groups are groups to which you assign a
specific list of users. Computedgroups are groups to
which users are assigned based on their
memberships in 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 users who are
members of both groups A and B, or members of
Implicit
A group to which a user automatically (or

implicitly) belongs by virtue of the contents
of certain fields in a request. You cannot
assign users to implicit groups. All users
are members of Public. You use the other
types of implicit groups to control access
to requests (row-level database access).
Public
Submitter
Assignee
Assignee
Group
Any dynamic groups that you create.Dynamic

groups use the contents of special fields to
determine group membership.
Membership in multiple groups

Users often belong to multiple groups in an organization. They inherit permissions from each of the
groups to which they belong.
If a group has permission to access a form, field, request, active link, or active link guide and a user
belongs to that group, the user has access, even if the user belongs to other groups that do not
have access.
How permissions work
Page 1403 of 4705
Home
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 the following figure, 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.
Hierarchical group relationships
Page 1404 of 4705
Home
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.
Note
Hierarchical group relationships are used for permissions management only, and are not
recognized when sending notifications by group.
Object properties that control hierarchical group access

Two object properties determine whether AR System grants access according to a parent group
relationship:
Page 1405 of 4705
Home
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 BMC Remedy AR System objects .
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.
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.
Access to BMC Remedy 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
Field permissions
Active link permissions

Permissions determine which access control groups can access forms, active link guides, or
applications in the user client (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:
Visible Members of the group or role can select and view the object in the user client.
Hidden Members 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.
None Members 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
Page 1406 of 4705
Home
permissions for the application also apply to any ancestors of the mapped group.
The following figure lists the questions that you can ask to determine the access that users have to
forms in BMC Remedy 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.
Accessing forms, guides, and applications
Page 1407 of 4705
Home
Field permissions
Field permissions determine the types of access that groups or roles have for individual fields in a
form:
View Users can read the contents of the field.
Change Users 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 and in the Field permissions example.
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
Page 1408 of 4705
Home
permission for a field.

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 form's 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 Set Fields action.
Field permissions lists the questions that you can ask to determine the access that users have to
fields in BMC Remedy AR System. Some of the questions are covered in Configuring after
installation.
Accessing fields
Page 1409 of 4705
Home
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 Field types for more information about
the following advanced fields.
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:
Page 1410 of 4705
Home
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 hierarchy--that 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.
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 and Assigning
permissions for individual or multiple objects.
Page 1411 of 4705
Home
Field permissions example

The following figure 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 Defining
default permissions.
Specifying field access control
At the field level, each group is granted specific access to the Short Description data field:
CS Staff group Change
Sales Staff group View
Browser group View Because the Browser group has a maximum access of View,
Change access at the field level is not possible.
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.
Page 1412 of 4705
Home
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.

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.
active links in BMC Remedy AR System.
Accessing active links
Page 1413 of 4705
Home
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 BMC Remedy 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 groups--Row-level security .
requests in BMC Remedy AR System.
Page 1414 of 4705
Home
Accessing requests

Controlling access by using implicit groups--Row-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 groups--Examples
Controlling access to requests for hierarchical groups
Controlling access by using implicit groups--Row-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 BMC Remedy AR System fields.
The following table shows the differences and similarities among these implicit groups and their
associated fields.
Implicit group
Group ID
Associated default field name
Field ID
Core field?
Associated field contents
Submitter
Submitter
Yes
User name
Assignee
Assigned To
Yes
User name
Assignee
Group
None
112
No
User, group, or role names
Dynamic
60000-60999
None
60000-60999
No
User, group, or role names
groups
You can also grant parent groups row-level access. For information, see Controlling access to
requests for hierarchical groups.
Page 1415 of 4705
Home
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
user's login name. Field ID 2 is usually set on submission by using the $USER$ keyword to
define this field's contents.
To have access as a member of the Assignee group, the contents of field ID 4 must equal
the user's login name. Field ID 4 is often set manually or by workflow to a user's name when
the status of the request changes.
Assignee Group access

The Assignee Group group allows access to requests or fields on a per-user or per-group 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 groups--Examples .
Page 1416 of 4705
Home
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 groups--Examples .
Using the Request ID field with implicit groups

Using implicit groups to control access to requests is a powerful method of access control within
BMC Remedy 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 user's 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.
If you are using a user's login name to assign access, remember these tips:
In the Submitter or Assigned To fields, enter the user's login name without quotation marks.
In the Assignee Group or dynamic group fields , enter the user's login name in single
quotation marks. Double any single quotation marks that are part of the login name (for
example, 'Dan O''Connor' ).
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 BMC Remedy AR System
Administration: Server Information form. To enter users Dan O'Connor and Mary Manager, group
ID 12000, role ID -9000, and role Managers, use the following syntax:
'Dan O''Connor';'Mary Manager';12000;-9000;Managers
Page 1417 of 4705
Home
Note
If a group and role have the same name, the role name is assumed. For example, if a
dynamic field contains Managers;Sales, BMC Remedy AR System assumes the
Managers and Sales roles, if they exist; otherwise, BMC Remedy AR System assumes
the Manager and Sales groups.
For more information about all settings in the BMC Remedy AR System Administration: Server
Information form, see Configuring AR System servers.
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 the following figure.
Controlling access to requests by using row-level security
Using the Assignee Group and dynamic groups--Examples

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.
Page 1418 of 4705
Home
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 BMC Remedy 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 the following figure.
Field permissions for the Request ID field
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 Computer's 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.
Page 1419 of 4705
Home
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 BMC Remedy 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 .
For more information about all settings in the BMC Remedy AR System Administration:
Server Information form, see Configuring AR System servers.
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 Remedy
Administrator 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 the following figure) executes when users
submit requests.
Using Assignee Group access in workflow
Page 1420 of 4705
Home
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 Introducing workflow.
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).
To use a dynamic group to control access to requests

1. Create the groups (or roles) and users to which you want to assign access.
2. Create a dynamic group in the Group form.
For example, create a group called Dynamic Access with a group ID of 60001.
3. Create a form, and give the appropriate groups Visible permission for it.
4. Add a character field to the form with field ID 60001, the same ID number as the dynamic
group ID.
5. Restrict access to requests in the form by granting the group Dynamic Access permission to
the Request ID field.
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 BMC Remedy 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.
For more information about all settings in the BMC Remedy AR System Administration:
Server Information form, see Configuring AR System servers.
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
Page 1421 of 4705
Home
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.
To control access to requests for hierarchical groups

1. Follow the appropriate procedure in Using the Assignee Group and dynamic groups-Examples 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.
6. Expand the Permissions panel and then the Group Permissions panel.
7. 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.
8. Save the form.
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 permissions The 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.
Page 1422 of 4705
Home
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.
Permissions for individual objects You 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 and
To assign permissions for other objects.
Permissions for fields You 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 .
Batch permissions You can specify permissions for multiple objects of the same type at
the same time. For more information, see Modifying object properties.
Group and role permissions You 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 .
Defining default permissions
Assigning permissions for individual or multiple objects
Checking object visibility for the Public group
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 user's 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.
Page 1423 of 4705
Home
Note
The objects created after setting the default permissions will not derive the default
permissions assigned before creating the objects.
Default permissions defined for forms on a server are shown here. The groups listed will be granted
visible permissions or hidden permissions to any new forms.
Server default permissions
(Click the image to expand.)
The Default Permissions dialog box for an application is shown here. In this case, the administrator
is assigning permission for new active link guides created in the application.
Application default permissions
(Click the image to expand.)
Page 1424 of 4705
Home
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:
Field permissions
Assigning permissions for individual or multiple BMC Remedy AR System objects
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:
c. Choose Window > Preferences.
d. In the Preferences dialog box, expand Developer Studio and select Default
Permissions.
e. 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
.
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.
Object Types
Access
level
Access for users in the group or groups mapped to the

role
Active link guide, application, form, web

service
Visible
View and access the object in the user client.
Active link guide, application, form, web
Hidden
Access to the object only through workflow.
Field
View
View the field.
Field
Change
View and change the field.
Active link, packing list
(none)
View and access the object in the user client.
service
6. For fields only, select or clear the Allow Any User to Submitcheck box. Use this mode to
determine security for the field when a request is submitted. If the check box is:
Page 1425 of 4705
6.
Home
Selected Any user can assign a value to the field, regardless of whether the
submitter belongs to an explicit group with Change permission to the field.
Cleared (the default) Only users who belong to one or more explicit groups with
Change permission to the field (or users who belong to explicit groups mapped to
roles with Change permission to the field) can enter data into the field. Row-level
security permissions cannot grant access during entry creation.
To remove default permissions

1. Select the group or role in the Permissions list and click Remove or click Remove All.
2. 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 objects

To override the default permissions or otherwise set specific permissions for individual objects or
multiple objects, use the procedures in this topic:
#To assign permissions for forms
#To assign permissions for other objects
#To assign permissions for one or more fields
#To assign permissions for a group to multiple objects
To assign permissions for forms

1. In Developer Studio, open the form for modification.
3. Expand the Permissions panel, and then open the Group Permissions subpanel.
4. In the Group Permissions subpanel, 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 Permissions panel and Group Permissions
subpanel on the Definitions tab 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 Permissions panel on the Definitions tab.
Page 1426 of 4705
Home
To assign permissions for other objects

1. In Developer Studio, open the object (such as an application, active link, or web service).
2. Open the Permissions panel.
3. For applications and web services, open the Group Permissions subpanel.
4. To add more groups to the Permissions list, select Additive from the Overlay Type
drop-down list.
To overwrite the origin object's permissions, select Overwrite.
For more information about overlays, see Customizing applications using overlays and
custom objects.
5. 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 the object, add the Public group to the Permission list.
6. 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.
7. To set the object permissions to their defaults, click Apply Defaults.
For more information, see Defining default permissions.
8. Click OK to close the Permissions dialog box.
9. To configure hierarchical group access to the object, set the object permissions property
Static Permissions Inheritance to True.
To assign permissions for one or more fields

1. In Developer Studio, open the form for modification.
2. Select the fields.
3. To add more groups to the Permissions list, in the Properties tab, select Additive from the
Overlay Type drop-down list.
To overwrite the origin object's permissions, select Overwrite.
For more information about overlays, see Customizing applications using overlays and
custom objects.
4. Click Set Permissions.
5. 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 groups-Row-level security.
To allow all users to view or change a field, add the Public group to the Permission list.
6.
Page 1427 of 4705
Home
6. If you selected Overwrite as the Overlay Type, click the drop-down menu in the
Permissions column if you want to set a different access level (View or Change) for each
group or role.
7. To set the object permissions to their defaults, click Apply Defaults. For more information,
see Defining default permissions.
8. Click OK to close the Permissions dialog box.
9. Choose File > Save to save the permission changes.
To assign permissions for a group to multiple objects

1. In 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 Modifying object
properties.
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.
Page 1428 of 4705
Home
For non-administrators, this setting has no effect; objects are displayed in the list according to the
user's group permissions.
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.
Enabling submitters to modify requests

BMC Remedy AR System contains a setting that enables users to modify requests that they initially
submitted even if they do not have a write license. To enable this feature, set the Submitter Mode
option to Locked in the Licenses tab of the AR System Administration: Server Information form.
Setting Submitter Mode on the Licenses tab
The Submitter Mode options are:

Locked Enables users who have their name in the Submitter field to modify their own
requests without a write license. This does not apply to users with a Restricted Read license
who cannot modify requests under any circumstances. In the locked submitter mode, after
the entry is submitted, the value in the Submitter field cannot be changed.
Page 1429 of 4705
Home
Changeable Requires users to have a write (fixed or floating) license to change any
record, including requests for which they are the submitter.
Access control, passwords and server security

This section contains information about access control, passwords and BMC Remedy AR System
server security:
Validating password information
Enforcing a password policy introduction
Setting up the mid tier for the password policy
Forcing users to change their passwords
Refer to Multitiered access control model for more access control information.
Validating password information

The BMC Remedy AR System server can validate the password entered by a user against the
user's Windows or UNIX login password instead of maintaining an Encryption Security-specific
password. To enable this:
Make sure the BMC Remedy Encryption Performance Security or BMC Remedy Encryption
Premium Security user name and the operating system user name are identical.
If you use Authentication aliases, the Login name alias should be identical to the operating
system user name.
Leave the Password field in the User form blank. See "Field" in Adding and modifying user
information
Select the Cross Ref Blank Password check box on the EA (external authentication) tab of
the AR System Administration: Server Information form. For more information about
password configuration, see Setting external authentication options.
Warning
Make sure that you specify a password for Administrator accounts (such as Demo) before
enabling Cross Ref Blank Password. Otherwise, an administrator can be locked out of the
system.
Where supported, the operating system password validation feature enables the operating system
to set the following password policies:
Aging Determines how quickly a password expires.
Lockout Limits the number of incorrect logins a user can enter before the system locks
the user out.
Password Restrictions Sets the password length and the allowed password characters.
Page 1430 of 4705
Home
Aging and Password Restrictions can be configured in BMC Remedy AR System where the user
password is stored in the User form (see Enforcing a password policy introduction and Enforcing
restrictions on passwords). The operating system password management system must be used to
configure Aging and Password Restrictions where the user password is stored external to the User
form.
Note
The operating system password management system can also be configured to lock out
users after too many failed password attempts. Use this method when the user password
is stored external to the User form. See Max Number of Password Attempts in Setting
administrative options. The operating system password management system can also be
configured to lock out users after too many failed password attempts. This method is
effective where the user password is stored external to the User form.
Enforcing a password policy introduction

BMC Remedy AR System ensures that passwords are always encrypted. An MD5 hash of
passwords is stored in the database, ensuring that the system (and so the reader of the database)
cannot retrieve passwords. In addition, you can enforce a password policy with the User Password
Management Configuration form.
User Password Management Configuration form
Note
Page 1431 of 4705
Home
If you are upgrading from a version prior to 7.1.00, note the changes to the User form, as
described in User form access.
The password management feature is preconfigured when you install BMC Remedy Encryption
Security, but it is not enabled. This section describes how to enable and use the feature.
With a password policy, you can:
Force all users or individual users to change their passwords when they use a browser
Enforce restrictions on passwords [Health Insurance Portability and Accountability Act (
HIPAA) standards are shipped as the default restrictions.]
Set up password expiration with scheduled warnings
Disable an account after the expiration period
Enable users to change their passwords at will
Important
If your system uses external authentication (through the Cross Ref Blank Password
option), be careful if you enforce password policy with the User Password Management
Configuration form. The policy should be enforced only for users whose passwords are
stored in the Encryption Security User form. If you enable the policy and have users who
are externally authenticated, disable the policy for the externally authenticated users as
described in Disabling password management for individual users. For information about
the Cross-Reference Blank Password feature used with external authentication, see
Cross-referencing blank passwords.
Setting up the mid tier for the password policy

If you are running on a BMC Remedy Mid Tier, use the BMC Remedy Mid Tier Configuration Tool
to set an authentication server for the BMC Remedy Mid Tier, and set up the policy on that server.
To set the authentication server, open the BMC Remedy Mid Tier Configuration Tool, and click the
General Settings link. Then, enter the server in the Authentication Server field.
Forcing users to change their passwords

With the Enforce Policy and Restrictions check box in the User Password Management
Configuration form, you can force all users to change their passwords according to the policy you
set up.
Forcing all users to change their passwords
Forcing new users to change their passwords
Page 1432 of 4705
Home
Forcing individual users to change their passwords

Enforcing restrictions on passwords
Setting security options using Server information form settings
Disabling password management for individual users
Reverting an individual user to global password management settings
Forcing all users to change their passwords

To force all users to change their passwords:
1. From the BMC Remedy AR System Administration Console, click System > General >
Password Management Configuration.
2. In the User Password Management Configuration form, select the Enforce Policy and
Restrictions check box if it is not already selected.
3. Complete the fields in the Enforcement Policy and Restrictions sections. For more
information about these fields, see:
Setting up password expiration with scheduled warnings
Disabling an account after the expiration period
4. Click Save.
All users are forced to change their passwords at their scheduled expiration date. When
users change their passwords, they must enter the old password once and the new
password twice.
Forcing new users to change their passwords

To force new users to change their passwords:
Password Management Configuration.
2. In the User Password Management Configuration form, select the New User Must Change
Password check box.
3. Click Save. Now, when you create a user, the user is prompted to change the password the
first time she logs in.
Forcing individual users to change their passwords

To force individual users to change their passwords:
1. From the BMC Remedy AR System Administration Console, click System > Application >
Users / Groups / Roles > User . The User form opens in Search mode.
4. Modify the Password Management fields, as needed. For more information about the User
form, see Adding and modifying user information.
5. Select the Force Password Change on Login check box.
6. Click Save.
Page 1433 of 4705
Home
6.
Note
Changes in the User form take precedence over the configuration settings in the
User Password Management Configuration form. If you change the User form and
you want the user to use the global password management policy (as configured in
the User Password Management Configuration form), see Reverting an individual
user to global password management settings . If you change the policy User
Password Management Configuration form, changes in the User form are
overwritten.

By default, the password management policy uses workflow to enforce Health Insurance Portability
and Accountability Act (HIPAA) rules for new passwords. You can use the default restrictions, add
restrictions, or disable the default restrictions and use your own.
The HIPAA rules include the following restrictions:
Blank passwords are not allowed.
The password cannot match the login name.
The user cannot use the old password when changing the password.
The password cannot be a dictionary word, which is achieved by the following rules:
Must be a minimum of eight alphanumeric characters
Must include at least one uppercase alphabetic character
Must include at least one lowercase alphabetic character
Must include at least one non-alphanumeric (special) character
Other restrictions include the following:
The administrator must be able to change the password at any time.
Users (except for the administrator and the password's user) cannot change the password.
This is accomplished through the Dynamic Group Access field (ID 60988) on the User
form.
The account is disabled if the user does not change the password after the number of days
specified in the Days after force change until disablement field in the User Password
Management Configuration form.
Restricting the use of certain characters in passwords
Page 1434 of 4705
Home
Restriction qualifications scenarios

Enabling users to change their passwords at will
Restricting the use of certain characters in passwords

On UNIX, users must enter two backslashes (\ ) in front of any dollar signs ($) in their passwords.
For example, if a user's password is testBMC$12, the user must enter it as follows: testBMC \ \ $12
.
To avoid login problems, restrict the use of $ in passwords.
Setting up password restrictions
Password Management Configuration. The User Password Management Configuration
form appears.
2. To disable the default HIPAA character restrictions, select the Disable Default Character
Restrictions check box.
This check box disables the default HIPAA character restrictions regarding
non-alphanumeric characters and case-sensitivity. If the check box is selected, users
can enter any characters in the Password field, except for characters that are
restricted according to what you enter in the Restrictions Qualifier field.
Length restrictions are still enforced, but you change them in the Minimum Length
field as described in the following step.
3. Complete the following fields in the Restrictions section.
Minimum Length Sets the minimum length the user must enter when changing a
password. You can enter a length of 1 through 30; the default is 8.
Restrictions Qualifier Specifies restrictions in addition to the default HIPAA
restrictions. For example, to force users to include a numeric character in their
password, enter:
'New Password' LIKE "%[0-9]%"
If the default HIPAA restrictions are enabled, you can add more restrictive qualifications, but your
restrictions cannot contradict the default restrictions. If you want less restrictive rules, disable the
default HIPAA restrictions. In summary, you can enforce restrictions in any of the following ways:
Use the default restrictions Do not enter a qualification in the Restrictions Qualifier field.
Use the default restrictions, but refine them further Simply enter a qualification in the
Restrictions Qualifier field.
Replace the default restrictions with your own custom restrictions Select the Disable
Default Character Restrictions check box and enter a qualification in the Restrictions
Qualifier field.
Page 1435 of 4705
Home
Remove the default restrictions, and allow users to enter any combination of characters
Select the Disable Default Character Restrictions check box and do not enter a
qualification in the Restrictions Qualifier field. See Restriction qualifications scenarios.
Failure Message Specifies the message if a password is entered that does not qualify
against the restrictions set.
4. Click Save.
Restriction qualifications scenarios

If the Disable Default Character Restrictions check box is not selected, the qualifier entered in
the Restrictions Qualifier field is appended to the current default restriction. However, you cannot
change the qualifier already defined in the default qualifier, which enforces that the password must
include at least one lowercase, one uppercase letter, and a special character.
Scenario 1
To add a restriction requiring users to include a numeric character in their password, enter the
following qualification in the Restriction Qualifier field:
This qualifier is appended to the default qualifier. With this restriction, aA1#, aa1#, and AA1# are
acceptable passwords if the minimum length for password is 4.
Scenario 2
To add the restriction of requiring a lowercase letter, enter the following qualification:
('New Password' LIKE "%[0-9]%") AND ('New Password' LIKE "%[â-z]%")
With this restriction, a password like aa1# is valid.

Scenario 3
The following qualification would not work because you cannot invalidate the default qualifier, which
requires a letter in the password.
('New Password' LIKE "%[Â-Z]%") AND ('New Password' LIKE "%[â-z]%"
If the Disable Default Character Restrictions check box is selected, the default qualifier is
ignored. The qualifier entered in the Restrictions Qualifier field is the only qualifier used.
Scenario 4
To force users to include numeric characters in their password, enter the following qualification in
the Restrictions Qualifier field:
Page 1436 of 4705
Home
With this restriction, 1111 is an acceptable password if the minimum length is 4. A password
without any numbers, like aaaa, would cause an error.

You can control when a password expires and how many days before the expiration users are
warned.
Note
Notifications that the User Password Management application sends are in English only.
To set up password expiration with scheduled warnings
form appears.
2. Complete the following fields in the Enforcement Policy section.
Number of Days Before Expiration Indicates the numbers of days before a user's
password expires if it is not changed.
Number of Warning Days Indicates when a user receives a warning message
before the password is set to expire unless changed.
3. Click Save.
Note
You can perform this function in the User form for individual users. See Adding and
modifying user information.

If a user does not change his or her password before a specified time, you can disable that user's
account.
To disable an account through the password policy:
form appears.
2. In the Days After Expiration Until Disablement field, enter the number of days after which
a user's account is disabled if the password is not changed.
3. Click Save. You can also perform this function in the User form for individual users. See
Adding and modifying user information.
Enabling users to change their passwords at will
Page 1437 of 4705
Home
A Change Password link is automatically placed on the Home Page form so users can change their
passwords voluntarily. When they click the link, the User Password Change form is opened.
User Password Change form
Important
If you enable users to change their passwords directly in the User form instead of the User
Password Change form, beware that the password restriction policy (default or
customized by you) is bypassed because the restrictions are enforced through the User
Password Change form, not through the User form.
Setting security options using Server information form settings

Every BMC Remedy AR System server has a variety of configuration settings that control how the
server works and how it interacts with users. Configuration settings are specific for each server.
Use the Advanced tab in the AR System Administration: Server Information form from the BMC
Remedy AR System Administration Console to create settings for security. This tab also contains
performance-related settings. You must be an administrator to make changes.
Note
Page 1438 of 4705
Home
BMC recommends using the AR System Administration: Server Information form to

change server settings, but you can also change settings manually in the server
configuration file (ar.cfg or ar.conf).
To set advanced options

Server Information. The AR System Administration: Server Information form appears.
AR System Administration: Server Information form Advanced tab
3. Edit the options listed in the following table as needed, and click Apply.
Area name
Field name
Description
Default Web
Path
Specifies the base URL for the mid tier and is used by clients such as Flashboards.
The URL appears as:
http://hostName/contextPath
hostName is the name of the server (for example, eng.remedy.com).

contextPath is the URL context path of the AR System application registered with the
servlet engine. This is set up during installation. The default value is arsys. If your
company has multiple domains, use a fully qualified path name.|
Maximum
Depth for
Hierarchical
Query
Maximum
Vendor
Temp Tables
For forms that contain hierarchical data, such as manager and employee relationships,
specifies the maximum number of levels in the hierarchy that a recursive query
retrieves. By default, the maximum is 25. Enter any integer greater than 0. See
Specifies the maximum number of temporary tables that can exist on an AR System
server for a single vendor form. The ARGetListEntryWithMultiSchemaFields function
stores data from vendor data sources in these tables. By default, only one temporary
table can exist for each vendor form. This setting applies to all vendor forms on the
server. It is overridden by the value of an individual vendor form's Maximum Vendor
Temp Tables property
Page 1439 of 4705
Home
Area name
Field name
Description
Email
Suppress
Server
Domain in
URL
Suppresses the server domain in the URL. The option is clear by default.
Maximum
Line Length
Specifies the maximum line length that can be in an email. The default is 1024. If a
single line of the message is over this length, a return is automatically inserted. Limits
the line length of email messages passed through the mail server to protect users from
excessively long lines.
in Email
Security
Email
Notification
Web Path
Specifies the base URL that appears in email notifications. If this field is left blank, the
Active Link
Specifies the only directory that the Run Process active link action can run from, for
Run Process
Directory
example, C:\arsys. If no directory is specified, active link processes can run from any
directory.
Active Link
Run Process
Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no
path is specified, administrators can specify any shell.
Default Web Path is used. (The Email Notifications Web Path field is available
because the Default Web Path is specified for other applications like Flashboards, and
it might be different from the mid tier web path for opening requests in a notification.) If
your company has multiple domains, use a fully qualified path name.
Shell(UNIX
servers only
)
Allow
arcache and
arreload
Client
Managed
Transaction (
CMT)
Configuration
Enables the administrator to use the arcache and arreload utilities. See arcache.exe or
arcache and arreload.exe or arreload. The option is selected by default.
Maximum
Concurrent
Transactions
Specifies the maximum number of concurrent client-managed transactions. The default

is 10, and the maximum value you can enter is 100.
Transaction
Timeout
Specifies the maximum time (in seconds) allowed to hold a transaction before a timeout
occurs. The default is 60 seconds, and there is no maximum. If a timeout occurs, the
server automatically rolls the transaction back, and the client receives an error on the
next operation that uses the transaction handle.
Localized
Error
Messages
Localize
Server
Enables the administrator to enable or disable localization of the server. Selected

indicates that the server is localized and enabled for such tasks as searching entries in
localized forms, or using AR System Message Catalog to load the message. Clients are
enabled to display localized messages, but clients still have local catalogs, such as the
user.dll. You must select the Localize Server check box to see localized error
messages. Cleared is the default and indicates that the server is not localized. Such
tasks as searching localized forms and the localization of messages are disabled. The
server does not use the AR System Message Catalog form, and messages are shown
from the error catalog. The default message is displayed.
Note
If users in a different locale open a form with localized views before you select
this option, you must flush the mid tier cache after setting this option to make
the localized view available on the web. See Configuring the Cache Settings
page.
Page 1440 of 4705
Home
Area name
Field name
Description
By default, when the BMC Remedy AR System server reads a system message (type 0
) from the AR System Message Catalog form, it caches the message text in memory to
avoid reading the message from the database each time the message is needed. To
modify this default behavior, see the "Localized-Messages-To-Cache" in ar.cfg or
ar.conf options E-M.
Catalog
Form Name
Displays the name of the form the server uses to resolve error messages when "
Localize Server" is selected. For more information about the AR System Message
Catalog form, see Localizing messages manually.
Filters
Maximum
Filters for an
Operation
Specifies the number of filters that can be performed in an operation. The default and
Maximum
Stack of
Specifies the maximum number of nested filters and filter guides that execute to
prevent recursive actions on the server. The default and recommended number is 25.
Increase this number at your own risk only if you reach a limit in your system and you
have verified that your workflow is valid.
Filters
Server
Statistics
Server
Recording
Mode
Specifies how the server records server statistics. Select one of the following options:
Off, the default, do not record server statistics; Cumulative Queue, record a cumulative
statistic that is a combination of all the queue statistics; and Cumulative and Individual
Queue, record a cumulative statistic that is a combination of all the queue statistics as
well as statistics of each queue individually. Information is recorded in the Server
Statistics form, which is installed when you install AR System. See Server statistics for
baseline data.
Recording
Interval (
Specifies how often the server records server statistics. The default is 60 seconds.
Remember that one (Cumulative Queue) or more (Cumulative and Individual Queue)
entries are recorded in the Server Statistics form during each interval. If you have a
short interval, many records are created. This can affect the performance of the system
and the size of the database if you configure with too short an interval.
seconds)
Server Group
recommended number is 10000. Increase this number at your own risk only if you
reach a limit in your system and you have verified that your workflow is valid.
Server
Group
Names
If the server belongs to a server group, specifies the name of the group. All servers in
the server group share this setting.
Check
Interval
Specifies how often the server communicates with other servers in the group. Each
server can register its own status, determine whether any server is delinquent,
establish the parameters needed for sending signals, and determine operational
responsibilities. The default value is 60 seconds, the minimum is 30 seconds, and there
is no maximum. All servers in the server group share this setting, and when it is
changed, all the AR System servers in the group must be restarted.
Preference
Server
Preference
Server
Option
Specifies where user preferences are read from. The options are User Defined, where
users can choose whether to use a preference server, and this server might or might
not be used depending on whether the Centralized Preference forms are defined; Use
This Server, where users must use a preference server, and this server is an available
preference server; Use Other Server, where users must use a preference server, and
this server is not available as a preference server. See Establishing a mandatory
preference server.
Preload
Preload
Tables At
Init Only
If the number of preload threads is not zero, specifies whether the threads are used
only at server startup or for all cache reloads from the database. See Setting the
Tables
Configuration
Preload Tables Configuration option. The values are Yes, if preload threads are
Page 1441 of 4705
Home
Area name
Field name
Description
configured (use them only at server startup) and No. If preload threads are configured,
always use them when loading the cache from the database. For information about the
corresponding configuration file setting, see "Preload-At-Init-Only" in ar.cfg or ar.conf
options N-R.
Number of
Preload
Threads
Specifies the number of preload threads used when information is loaded from the
database into the server cache. The maximum value is 30 or twice the number of
preload segments, whichever is lower. The server might reduce the number of threads
at runtime if it determines that threads would be started with no work to do. If this field
is set to 0, the Preload Tables Configuration option is off. For information about the
corresponding configuration file setting, see "Num-Preload-Threads" in ar.cfg or ar.conf
options N-R.
Number of
Preload
Segments
Specifies the total number of preload segments handled by the preload threads. Vary
this setting to balance the load between preload threads and to optimize cache load
time. A good initial setting for this option is 1/3 the number of schemas (forms) in the
AR System server. See Setting the Preload Tables Configuration option. For
information about the corresponding configuration file setting, see "
Num-Preload-Schema-Segments" in ar.cfg or ar.conf options N-R.
Disabling password management for individual users

To disable password management for individual users:
4. Select the Disable Password Management For This User check box.
5. Click Save.
Reverting an individual user to global password management settings

To revert an individual user to global password management settings:
4. Clear all the Pssword Management fields on the form.
5. Click Save.
Enabling skins administration for users

You can enable any user to configure and modify skins on the form views using the Skin Designer
role in BMC Remedy AR System. In a multi-tenant environment, you may enable tenants to
configure skins for their environment. By default, these tenants do not have the permissions to
configure skins. You can enable this feature by mapping Skin Designer role to specific tenant
groups.
Page 1442 of 4705
Home
Note
When the tenant applies skins, the skins will be applied to that server's forms and is
limited to that tenant environment. In a mid tier multi-tenant environment, it affects only the
tenant using that server.
To enable skins configuration for users

1. Create a AR System access control group using the BMC Remedy Mid Tier. Use the Group
form to create the group to which you want to grant access for configuring AR System skins.
For example, you might want to create a group with a name such as AR System Skin
Administrator. For more information about creating a group, see Creating groups.
Note
You can also use an existing group for mapping the Skin Designer role.
2. Open the Roles form in New mode and create a new role for the following applications:
a. AR System Administration
b. AR System Skins
3. For each application, enter the following details:
Field
Value
Application Name
AR System Administration
AR System Skins
Role Name
Skin Designer
Skin Designer
ID
-2
-2
Mapped Group
Test: AR System Skin Administrator

Production: AR System Skin Administrator
Test: AR System Skin Administrator

Production: AR System Skin Administrator
For more information about creating and mapping roles, see Creating and mapping roles.
Note
If the Skin Designer role is already defined for the above applications, modify the role to
add group information by searching the Roles form in Search mode.
When you map the role to the AR System Administrator group, all the users of the group can
access the AR System Skin Administration console. In a browser, the user can access the skin
administration console by clicking AR System Administration > AR System Skin Administration
. For more information about defining skins, see Defining skins and Applying skins to form views.
Page 1443 of 4705
Home

This section describes how to set up an authentication alias. An authentication alias enables you to
use an alternate user name (User Name Alias) or an authentication string (Authentication String
Alias) when the operating system or an AR System External Authentication (AREA) plug-in is
performing the authentication. The User Name Alias and the Authentication String Alias operate
independently of one another, so you can use both or either one alone. Topics include:
User Name Alias introduction
Authentication String Alias introduction
User Name Alias introduction

A User Name Alias is a secondary account name associated with a user and is used only for
authentication purposes. The user's primary account name (the login name entered into the User
Name field of the Login dialog box of BMC Remedy AR System clients) is used for all other
purposes. If a User Name Alias is defined, the BMC Remedy AR System server uses it to
authenticate the user and password.
The User Name Alias is applicable in the following situations:
When you want the user's full name to be used as the BMC Remedy AR System login
instead of the user's computer account name. The system uses the alias when
authenticating the user.
When a user's name changes, the user can use the new name to log in to BMC Remedy AR
System but continue to use the same computer account name for authentication purposes.
When a user's computer account or domain name is subject to changes. Leveraging an alias
enables the user to continue using the same user name to log in throughout the changes
Configuring the User Name Alias

To configure a User Name Alias, add a character field to the User form in BMC Remedy Developer
Studio and name it Authentication Login Name. Set the field's properties as follows:
Field property
Field
Name
Authentication Login Name
Field ID
117
Data Type
Character
Database Length
30
You can set any permissions, including whether the values are optional or required. You can also
create workflow to populate and validate the values in this field.
Page 1444 of 4705
Home
Important
Be cautious when setting permissions. Typically, the values in this field should be set only
by an administrator or by workflow.
The information in the Authentication Login Name field is accessed when the user logs in to a
BMC Remedy AR System client and the following conditions apply:
Cross-Reference Blank Password is configured on the BMC Remedy AR System server (see
Cross-referencing blank passwords).
The Password field on the User form is empty.
One of the following external authentication methods is used:
An AREA plug-in
A Windows Domain server (when the BMC Remedy AR System server is running on
a Windows platform)
A UNIX password resolution (when the BMC Remedy AR System server is running on
a UNIX platform)
The Authentication Login Name field on the User form interacts with the User Namefield in
the Login dialog box according to the following rules:
If the Authentication Login Name field is present on the User form, the value
contained in this field is used for authentication instead of the name entered in the
User Name field in the Login dialog box.
For backwards compatibility, if the Authentication Login Name field is not present
on the User form or the value in this field is NULL, the user is authenticated with the
information entered in the User Name field in the Login dialog box.
These rules apply to all BMC Remedy AR System clients, including those accessing a BMC
Remedy AR System server by using C or Java APIs.
Authentication String Alias introduction

When an Authentication String Alias is defined, it overrides any entry in the Login dialog box of the
AR System client. The Authentication String Alias can be used to identify the correct authentication
domain for the user.
Use the Authentication String Alias in the following situations:
When users belong to specific authentication domains and you do not want to require users
to enter an authentication string when they log in.
When a user's computer account or domain name is subject to changes. Leveraging an
Authentication String Alias enables the user to continue using the same user name to log in
throughout the changes.
Page 1445 of 4705
Home
Configuring the Authentication String Alias

To configure an Authentication String Alias, add a character field to the User form in BMC Remedy
Developer Studio and name it Authentication String. Set the field's properties as follows:
Field property
Field
Name
Authentication String
Field ID
118
Data Type
Character
Database Length
255
You can set any permissions, including whether the values are optional or required. You can also
create workflow to populate and validate the values in these fields.
Important
Be cautious when setting permissions. Typically, the values in this field should be set only
by an administrator or by workflow.
The information in the Authentication String field is accessed when the user logs in to an AR
System client and the following conditions apply:
Cross-Reference Blank Password is configured on the BMC Remedy AR System server. (
See Cross-referencing blank passwords for more information.)

The Password field on the User form is empty.
One of the following external authentication methods is used:
An AREA plug-in
A Windows Domain server (when the BMC Remedy AR System server is running on
a Windows platform)
A UNIX password resolution (when the BMC Remedy AR System server is running on
a UNIX platform)
Login dialog box
Page 1446 of 4705
Home
The Authentication String Alias field on the User form interacts with the Authentication field in
the Login dialog box according to the following rules:
The value in the Authentication String field on the User form is used instead of the entry in
the Authentication field in the Login dialog box.
For backwards compatibility, if the Authentication String Alias field is not present on the
User form or the value in this field is NULL, the information entered in the Login dialog box is
used for authentication.
These rules apply to all BMC Remedy AR System clients, including those accessing a BMC
Remedy AR System server by using C or Java APIs.
Restrictions when logging in to a BMC Remedy AR System

server
The following restrictions apply to users logging in to a BMC Remedy AR System (AR System)
server:
Multiple IP addresses With the exception of users who have Restricted Read licenses,
nonadministrative users can access a AR System server from only one computer at a time.
This restriction applies to the server, not to an application. For example, if you run the BMC
Remedy IT Service Management (ITSM) Suite on an AR System server, a user accessing
any form in any ITSM application on that server can do so from only one IP address.
AR System administrators (users who have the Administrator group in their Group List on the
User form) can access a server from multiple computers simultaneously.
Note
Page 1447 of 4705
Home
AR System uses a globally unique identifier (GUID) to identify the computer, so

users do not need to log in again if their IP address changes during a session.
Wait time After a user logs out of one computer, the user might need to wait a short time
to make sure the status is cleared before using the same login name to access another
computer.
Session takeovers A user who is blocked from access can perform a session takeover
through a message dialog box. This can be helpful if someone forgets to log out of a client at
a different location. Only one session takeover is allowed every fifteen minutes for each user
.
Matching user names In BMC Remedy AR System 6.3, multiple users with the same user
name but different passwords could log in at the same time. In BMC Remedy AR System
7.0.00 and later, multiple users with the same user name cannot log in concurrently if you
use the User form for authentication. If you use external authentication, however, multiple
users with the same user name can log in if they belong to the same groups. (In the cache,
only one session is created, and this session is used for all users who have the same user
name.)
If you try upgrading to BMC Remedy AR System 7.0.00 or later from a 6.3 system in which
you allowed multiple users to have the same user name but different passwords, the BMC
Remedy AR System upgrade scripts fail and generate a message suggesting that you
correct the multiple user name problem.

This section provides instructions for managing information about your BMC Remedy AR System
users. Topics include:
User licenses
User form access
See the following sections for related information:
Viewing user license information
Enabling submitters to modify requests
User licenses
When creating users, you must assign a license type to each user. The type of license a user has
determines the user's ability to access BMC Remedy AR System objects and to perform tasks. This
section contains the following information to assist you with licensing:
License types for users to access BMC Remedy AR System server
About floating licenses in a license pool
Page 1448 of 4705
Home
Releasing floating licenses to a license pool

For more licensing information, see License overview and Working with BMC Remedy AR System
licenses.
License types for users to access BMC Remedy AR System server

The following license types are used to access the BMC Remedy AR System server:
License
type
Description
Read
Enables users to search for and display requests within their assigned permissions. Administrators can configure the
BMC Remedy AR System server to enable users with Read licenses to submit requests and to modify requests that
they submit. See Enabling submitters to modify requests.
Restricted
Read
Enables users to create, search for, and display requests within their assigned permissions. Users with Restricted
Read licenses cannot modify any requests, including their own.
Restricted Read licenses enable the same login account to access BMC Remedy AR System from multiple IP
addresses simultaneously.
You can give guest users a Restricted Read license. See Setting administrative options.
Fixed
Includes all the capabilities of a Read license, and also enables users (based on the permissions of the groups to
which they belong) to modify and save requests that they did not submit. BMC Remedy AR System administrators
and subadministrators must have a Fixed license. Other BMC Remedy AR System users who consistently need to
modify requests must also have Fixed licenses.
A Fixed license is associated with a user name and is always "reserved" for that user. Users who have a Fixed
license can access the BMC Remedy AR System server at any time.
A user cannot be assigned the same Fixed license more than three times in one week. If this limitation is exceeded,
the user must wait one week from the first assignment of the Fixed license before it can be assigned again.
Floating
Includes all the capabilities of a Read license, and also enables users to modify and save data for requests that they
did not submit based on the groups to which they belong. Multiple users can use the same Floating licenses, one
user at a time: they are available on a first-come, first-served basis. This type of license is designed for users who
occasionally need to modify and save requests.
When a user who is assigned a Floating license logs in to BMC Remedy AR System, the user is given a Read license
. When the user attempts to perform a search, modify, or submit operation, BMC Remedy AR System checks for an
available Floating license, and the following occurs:
If a Floating license is available, the user is granted write access to requests. The user retains write access
until the Floating license is released.
If no Floating licenses are available, the user is notified and continues to use the Read license until a Floating
license becomes available.Generally, Floating licenses are shared by all BMC Remedy AR System users. You
can, however, define license pools to reserve a set of Floating licenses for a group of users. This enables you
to prioritize the availability of Floating licenses. For example, you can allocate a number of licenses to
department managers to make sure that they can immediately approve essential requests. Users who do not
belong to this group cannot acquire any of the reserved licenses.
Page 1449 of 4705
Home
An AR System server license key activates three fixed write licenses (which you might have to
purchase, depending on your sales contract) and unlimited read and restricted read licenses. You
can purchase additional fixed write licenses and floating write licenses from BMC or from an
authorized reseller.
For more information about licensing, see License overview and Working with BMC Remedy AR
System licenses.
The operating system password management system can also be configured to lock out users after
too many failed password attempts. Use this method when the user password is stored external to
the User form. For more information, see the Max Number of Password Attempts row in the table in
Setting administrative options. The operating system password management system can also be
configured to lock out users after too many failed password attempts. This method is effective
where the user password is stored external to the User form.
About floating licenses in a license pool

A license pool consists of a number of floating licenses reserved for a group, subject to the number
of floating licenses available in the database. When a member of a group logs in, a license from the
license pool for that group is granted. When the user finishes using the license, it is released back
into the pool.
If no licenses are available in the pool, a check is made to see if the user is a member of any other
group that has a license pool. If no licenses are available in any pool the user is a member of, a
check is made for floating licenses not associated with any pool. A user is never granted a floating
license from a pool of which the user is not a member.
License pools enable you to give priority to a group that needs licenses more urgently. The group
with the smallest group ID has the highest priority. When a non-reserved floating license becomes
available, it is granted to the next user who needs it, regardless of the priority of that user's access
to the system.
For more information about user groups, see Adding and modifying user information and Groups in
Releasing floating licenses to a license pool

A floating license is automatically released back to the pool of available licenses in the following
situations:
A user logs out of a mid tier session.
Page 1450 of 4705
Home
A user closes the browser window.

If a user closes the browser window, which is displaying BMC Remedy Mid Tier, then the
system performs an automatic logout after a short delay. For more information about session
timeouts, see the License Release Timeout 30 -300 Seconds row in the General Settings
parameters table in the Configuring the General Settings page section.
Note
If the user is accessing BMC Remedy Mid Tier on multiple browser windows, the
token is released only after the user closes the last browser window associated
with the current HTTP session or navigates away from BMC Remedy Mid Tier.
A user does not perform a BMC Remedy AR System operation for the period of time in the
floating license time-out interval. See the Floating License Timeout (hours) row in the
Timeout tab fields table on the Setting timeout options section.
If a timeout occurs in a BMC Remedy Mid Tier session, it does not have any effect
on the licences held by the user.
In addition, administrators can manually release user's licence one time in a 24-hour period by
using the following procedure.
To release a floating license

> Application > Users/Groups/Roles > License Review .
2. From the Category list in the Manage User Licenses form, select Current Licenses.
3. From the License Type list, select Floating. A list of users with the selected license type
appears.
4. From the list of active users, select the appropriate user.
5. Click Release User. The license held by that user is released. Another user can take the
license and start working. If the original user returns, the user cannot get back into the
system if no licenses are available.
Note
If you release a Fixed or Read license, this procedure removes the user from the
list of current users; it does not affect the user's ability to connect to the server. The
next time the user accesses the server, the user obtains the licences again and the
user's license information reappears.
Page 1451 of 4705
Home
6. Click Close.

The Manage User Licenses form displays information about the registered and current users on the
selected server. The registered user information is the information submitted for each user in the
User form. See Adding and modifying user information.
To display user license information

> Application > Users/Groups/Roles > License Review . The Manage User Licenses form
appears.
License information
2. From the Users Category list, select one of these options:

Server - Current Users Displays the following information for each user connected
to AR System through a BMC Remedy AR System license:
Name of the user
Type of AR System license assigned
Connect time during the current session
Time that the user last accessed the server during this session
Floating license pool
Server - Registered Users Displays the following information for all users known
to BMC Remedy AR System with an AR System license:
Name of the user
Default notification mechanism
Email address
Note
Page 1452 of 4705
Home
If your User form contains more than 30,000 users, the Server Registered Users option does not work well. Instead, search the
User form for a list of registered users.
Server - Invalid Users Displays the number of users who are locked out of the
browser because of too many bad password attempts. To reset an invalid account,
reset the user's password. To set a maximum number of bad passwords, enter the
number in the Max Number of Password Attempts field in the BMC Remedy AR
System Administration: Server Information form (Configuration tab). To turn the
feature off (unlimited number of bad passwords allowed), set the number to 0 (the
default). You can also check for invalid users by using the driver program with the glu
command. See Using the driver program.
Application - Current Users Displays the following information for each user
connected to AR System through an Integration System Vendor (ISV) license:
Name of the user
Connect time during the current session
Time that the user last accessed the server during this session
Floating license pool
Application - Registered Users Displays the following information for all users
known to AR System with an Integration System Vendor (ISV) license:
Name of the user
Name of the licensed application
3. From the License Type list, select the license type for the category of users that you want to
view. The Write License Pool column shows the name of the current group (pool) from which
the user's Floating license was acquired. At another time, if a license is acquired from a
different pool to which the user belongs, that pool name is displayed.
4. Click Close.
User form access

Prior to version 7.1.00 of BMC Remedy AR System, only the Administrator group had access to the
form. In version 7.1.00 and later, the following changes were made:
The Public group has Hidden permission to the User form.
The Dynamic Group Access field on the User form gives users read permission to the
following fields: Login Name, Password, and Request ID. These permissions are
automatically given to all new users that the administrator creates.
Page 1453 of 4705
Home
If you are upgrading to 7.1.00 or later, be aware of these permission changes. If you customized
the User form, these changes might affect your customizations.
These changes enable you to enforce a password policy. See Enforcing a password policy
introduction.
Understanding database security issues

In general, BMC Remedy AR System hides the underlying database from the user. The BMC
Remedy AR System (AR System) server interacts with the database and provides information to
the user independent of the underlying database. All access through the API supplied with the
product goes through this server and is independent of the database. This section contains topics
related to database security:
Using IBM DB2 Universal Database user names and passwords
Assigning permissions when using SQL queries
For information about configuration options and parameters associated with specific databases, see
Configuring after installation.
Using IBM DB2 Universal Database user names and passwords

IBM DB2 Universal Database user name and password behavior that you need to consider include:
When the DB2 database resides on the same computer as the BMC Remedy AR System (
AR System) server, ARAdmin user is not used. You can run the AR System server installer
as root or any other user as long as that user has administrator privileges for the specific
DB2 instance on which you install the BMC Remedy AR System database.
When the DB2 database resides on a different computer from the AR System server, the
database user name, aradmin, must be created in lowercase before installing AR System
server. The database user name is associated with the operating system. For overwrite and
new installations (but not for upgrade installations), this operating system account must exist
before installing AR System server. The password must be AR#Admin#. After the AR
System server is installed, you can change the password.
Because the database user name is associated with the operating system, you must make
password changes in the operating system and set the new password in the AR System
Administration: Server Information form. For more information about this form, see
See Using IBM DB2 Universal Database with BMC Remedy AR System for DB2-specific
information.
Page 1454 of 4705
Home
Changing the BMC Remedy AR System database user name and password
The BMC Remedy AR System database user ( ARAdmin by default) and password (AR#Admin#
by default) are set during the AR System server installation. You can, however, change them to suit
your needs.
To change the BMC Remedy AR System database user name

1. Stop the AR System server.
2. Update the database user name in the database. For more information, see your database
documentation.
3. Update the Db-user option in the ar.conf (ar.cfg) file.
a. Open the ar.conf (ar.cfg) file with a text editor.
b. Change the Db-user entry to match the value you specified in step 2.
c. Save the ar.conf (ar.cfg) file.
To change the BMC Remedy AR System database password

Use the Database tab in the AR System Administration: Server Information form. See
OR
Use the ARSetServerInfo API call. See ARSetServerInfo.
Warning
Do not change this password directly in the database.
Note
To change the database password in a server group, change the password in each AR
System server's AR System Administration: Server Information form. Each server
attempts to alter the password in the database, but only the first one changes the
password. Each server updates its configuration file. On database platforms that require
an existing (old) password to perform the change, the server initially logs a failure to the
SQL log as servers (after the first one) have their passwords changed. This occurs
because the subsequent servers do not know that the first server already changed the
password, so they do not supply the correct existing password. The servers recover from
this condition and successfully update the configuration file.
See Using IBM DB2 Universal Database with BMC Remedy AR System for special considerations
for database user name and password with DB2.
Page 1455 of 4705
Home
Assigning permissions when using SQL queries

To use SQL queries, familiarize yourself with your underlying database. All SQL queries are issued
by the following users:
Database
User
DB2
The user who installs BMC Remedy AR System
ARAdmin
Oracle
ARAdmin
Sybase
ARAdmin
If you run BMC Remedy AR System as one of these users without permission to access the
database, you cannot issue the SQL query.
To access non-BMC Remedy AR 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
Using audit records

This section describes the various types of log files, also called audit records, available in BMC
Remedy AR System (AR System). It also shows how you can trace the activity of most AR System
server functions using audit records.
Viewing BMC Remedy AR System Server audit records
Viewing BMC Remedy Mid Tier audit records
Viewing BMC Remedy Distributed Server Option audit records
Viewing database audit records
See Troubleshooting for more information about log files.
Viewing BMC Remedy AR System server audit records

The arerror.log file is always active, and logs all BMC Remedy AR System server error messages.
Any message that represents a serious or fatal server error is reported in this file, including
messages that cannot be returned to a user, or that are not appropriate for return.
The logged messages include information about termination of or failed server processes. A
termination entry about a server process also appears for normal shutdown. For example, any time
an AR System server shuts down, a message is written to this file.
On Windows, this file is stored in the ARSystemInstallDir\arserver\Db directory.
Page 1456 of 4705
Home
On UNIX systems, this file is stored in the ARSystemInstallDir/db directory. Check this file
regularly to see if your servers are reporting errors.
See Log entry format for detailed information about audit records.
Viewing BMC Remedy Mid Tier audit records

You can view the log files that record the activity of the BMC Remedy Mid Tier (mid tier). If you
have no log files generated, it might be because the Log Viewer setting is set to Console. Change
this setting to Files to generate mid tier log files.
Setting
Description
Display Last
The number of lines that you want to view from the most recent entries in the log. The default is 25.
View Log File
Click to view the log file.
See BMC Remedy Mid Tier logging for more information about mid tier logging.
Viewing BMC Remedy Distributed Server Option audit records

BMC Remedy Distributed Server Option (DSO) logs track the steps and events of distributed
operations handled by the DSO server. You can activate DSO logging only on BMC Remedy AR
System servers that have a license for DSO.
The following table lists the DSO log files for Java.
BMC Remedy
Distributed
Server Option
log file
Description
ardist.log
Contains information about the DSO server.
ardist.default.log
Contains information about the default distributed pool.
ardist. poolName
Contains information about a custom distributed pool. Windows log file names In a Windows environment, if
the name of a distributed pool contains special characters, BMC Remedy AR System replaces those
characters with a dot (.) in the pool's log file name. Special characters are characters not allowed in Windows
file names, such as a colon (:), forward slash (/), and question mark (?). For example, the log file for a pool
.log
named test:dso would be ardist.test.dso.log. If you then created a pool named test/dso, its log file would
be ardist.test.dso.log. To avoid the confusion that these virtually identical log file names might cause, do not
use special characters to differentiate pool names. UNIX log file names In a UNIX environment, the special
characters are allowed in file names. Therefore, if the name of a distributed pool contains special characters,
the characters are included in the pool's log file name. For example, the log file for a pool named test:dso
would be ardist.log.test:dso.
By default, the DSO log files are stored in these directories :

(UNIX) ARSystemServerInstallDir/db/
(Windows) ARSystemServerInstallDir\Arserver\Db
You can change the path or file names of the DSO log files in the AR System Administration:
Server Information form. (See Configuring BMC Remedy Distributed Server Option logging .)
Page 1457 of 4705
Home
Viewing database audit records

The database SQL log is similar to the filter log, but the SQL log file consists of a series of SQL
commands (one per line), each of which contains the information listed in Log entry format. In this
case, the log type is (<SQL>), which identifies the entry as an SQL logging line. By default, the log
file is named arsql.log.
Note
This mode of debugging can generate a large amount of information quickly. It is not
unusual to have several hundred megabytes of information logged in one day.
If the server is licensed for full text search, the SQL debug mode also logs full text search (FTS)
searches in this file.
SQL log file: sample section
<SQL > <TID: 0000000620> <RPC ID: 0000000000> <Queue: Admin >
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:28.8280 */SQL Trace Log -- ON
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:29.1560 */CONNECT ARSystem,
USER ARAdmin
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:30.5780 */SET
CONCAT_NULL_YIELDS_NULL OFF
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:30.5780 */OK
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:30.5780 */SELECT @@version
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:31.0000 */SELECT dbVersion FROM
control
<Client-RPC: 000000 > <USER: > /* Wed Oct 04 2006 13:18:31.3900 */SELECT MAX(serverId)
FROM server_cache
The SQL log file includes an "OK" line that displays the end time for each transaction that is logged.
If an SQL error or warning is encountered as a result of the command, the command is followed by
another line with the same header, but the SQL command is replaced with *** ERROR *** or **
Page 1458 of 4705
Home
** WARNING ****. The text of the error or warning from the database follows. This information
associates an operation with the user who performed the operation, and is useful for identifying
database issues.

This section contains information about options for setting centralized user and administrator
preferences on the server.
Users can set individual preferences for the behavior and display characteristics of the clients they
use. These preferences are stored centrally (on a designated preference server).
Centralized preferences help users who want to have the same settings and customizations
available when they use multiple computers. Users who log in to web clients must use centralized
preferences.
Accessing preference forms for centralized preferences
Restricting preferences from users
Configuring clients to use a preference server
Establishing a mandatory preference server
Behaviors associated with preference server configuration
Setting the AR System User Preference form
Setting user preferences in the BMC Remedy Mid Tier
Accessing preference forms for centralized preferences

Centralized preferences are saved on a preference server. Preference servers contain the following
preference forms, which are installed when you install the BMC Remedy AR System server.
Preference forms
Form
Purpose and Content
AR System
Stores preferences for web clients. Administrators can set the value of the fields in the AR System User
User
Preference form by using the PERFORM-ACTION-SET-PREFERENCE Run Process command.
Preference
form
AR System
(Mid tier only) Stores searches that users create and save for a form in a browser. See:
Searches
Preference
form
Types of browser searches for your end users

AR System
Administrator
Preference
form
Page 1459 of 4705
Home
Form
Purpose and Content

Stores preferences for BMC Remedy Developer Studio and BMC Remedy Data Import. By default, this form has
administrator permissions only. You might want to define subadministrator permissions. Display preferences and
the list of login servers are stored in the AR System User Preference form. Developer Studio and Data Import
users can also access these preference settings in the Options dialog box (choose File > Preferences). The
changes made here are saved to the AR System Administrator Preference form.
To access these forms through the AR System Administration Console, click User Preferences or
Admin Preferences.
If the preference forms are not present on the server or if the user does not choose a preference
server, the local ar.ini file is used to determine their preferences.
If the preference forms are not installed, you can import the definition files. For more information,
see Exporting and importing definitions.
Restricting preferences from users

To restrict preferences, remove Public permissions from individual fields in the AR System User
Preference form.
Configuring clients to use a preference server

To use centralized preferences in web clients, specify preference servers during the mid tier
installation, or specify these servers later by using Mid Tier Configuration Tool. See Configuring the
Establishing a mandatory preference server

As a BMC Remedy AR System administrator, you can designate a mandatory preference server
that stores the system preference information. This configurable server setting provides a
mechanism to enforce the use of centralized preferences across an organization.
To enable a mandatory preference server

Server Information.
Server Information Advanced tab
Page 1460 of 4705
Home
3. Select the appropriate Preference Server Option:

User Defined Enables the user to determine whether to use a preference server.
Use This Server Designates the current server as the preference server. (The
preference forms must be available.)
Use Other Server Designates the current server as a non-preference server and
indicates another server on the system is set with Use This Server.
Important
If Use This Server or Use Other Server is selected, the local preferences are
disabled. The system tries to connect to the designated preference server. If
no preference server is found, the default preference values are used
instead of the local ar.ini file.
For more information about the effects of these choices, see Behaviors associated
with preference server configuration.
4. Click OK.
Behaviors associated with preference server configuration

Different behaviors occur depending on the server settings you configure for the Preference Server
Option on the Advanced tab of the AR System Administration: Server Information form.
"User Defined" behaviors
User action
Behavior
Leaves the Preference
The local preferences are used (ar.ini file).
Server field blank

Specifies a valid preference
The system connects to the preference server, and the Accounts list is updated to reflect the list of
server
servers specified on the Server List setting.
Specifies an invalid
preference server
The local preferences are used (ar.ini file).
"Use This Server" or "Use Other Server" behavior

Page 1461 of 4705
Home
User action
Behavior
Leaves the
Preference
Server field
blank
The system searches the Accounts list for a server designated as a preference server. If one is found, the server
name is written to the Preference Server field of the Login dialog box. In addition, the accounts list is updated to
reflect the list of servers specified on the Server List setting for that preference server.
Note
The user receives this warning: 50176 - A preference server has been selected based on the
Administrator settings.
If no preference server is available, the default preference values are used and no session specific changes to the
preferences are stored. (Local preferences are disabled.)
Specifies a
valid
preference
server
The system connects to the preference server, and the Accounts list is updated to reflect the list of servers
Specifies an
invalid
preference
server
The system searches the accounts list for a server designated as a preference server. If one is found, the server
specified on the Server List setting for that preference server.
name is written to the Preference Server field of the Login dialog box. In addition, the accounts list is updated to
reflect the list of servers specified on the preference server.
Note
The user receives this warning: 50174 - The preference server specified is invalid. Another
preference server has been selected.
If no preference server is available, the default preference values are used and no session specific changes to the
preferences are stored. (Local preferences are disabled.) The user receives this warning: 50175 - The preference
server specified is invalid. User preferences will not be used.
Setting the AR System User Preference form

The following sections describe the fields on each of the tabs in the AR System User Preference
form.
Setting common fields
Setting the Accessibility tab
Setting the Advanced tab
Setting the Alert tab
Setting the Confirmation tab
Setting the Edit tab
Setting the General tab
Setting the Home Page tab
Setting the Locale tab
Setting the Logging tab
Setting the Misc tab
Setting the Recent tab
Page 1462 of 4705
Home
Setting the Report tab

Setting the Web tab
Setting the Window tab
Date and time formats
Setting common fields

Common fields reside in the upper portion of the AR System User Preference form. These fields
affect the mid tier.
AR System User Preference form--common fields
Common fields on the AR System User Preference form

Field Name
Description
Login
Name
The user's login name. Lets the administrator create, search for, and modify preferences for a specific user by
entering that user's login name in this field. Users can search for and modify their own preference records. The
default setting is $USER$.
Short
Description
Lets the administrator create, search for, and modify preferences based on a value in this field. The default setting
Status
Not used.
Create
Date
The date the record was created. This field is display-only.
Modified
Date
The date the record was last modified. This field is display-only.
Last
Modified
The login name of the user who last modified the record. This field is display-only.
is Preference entry for $USER$.
By
Setting the Accessibility tab

The Accessibility tab form contains the following web accessibility preferences. If no user
preferences are set, no Section 508 enhancements are made to the form. For each user, Section
508 enhancements are added dynamically when the HTML for the form is read.
AR System User Preference form Accessibility tab
Page 1463 of 4705
Home
Accessibility tab fields

Area name
Field
Description
Client
Generates the HTML page so it is optimized as follows:
Web
Name
Accessibility
Accessible
Mode
Default No optimization.
Screen Magnifier/Low Vision Accessed with a screen magnification device.
Screen Reader/No Vision Accessed using screen reader software.
Accessible Mode is enabled when it is set to Screen Reader/No Vision.
Note
When adding image buttons to a form, you must add a label for the button image
so that screen readers can read the ALT tag for the image. When the No Vision
option is set in user preferences, the screen reader uses the label text to read
the ALT tag.
Accessible
Message
Designates the type of nonvisual feedback that applies to workflow for this view. The
options are
Legacy
*
No Action No messages are shown for accessibility. Active link message

actions of the type Accessible are ignored.
Message Action Displays accessibility messages defined by the active link
message action of type Accessible.
All Actions Displays accessibility messages to reflect visual changes on the
page as well as accessible messages defined by an active link message action of
the type Accessible.
Accessibility messages are displayed for visual changes caused by Change Field and Set
Field active link actions, and other user actions such as table refresh. These messages
reflect the visual changes that the user would have experienced otherwise. If a field is
hidden, changes caused by these actions are ignored.
Note
These options are not used in the BMC Remedy Mid Tier 6.3 and later.
* Legacy = The field is available for legacy environments that use BMC Remedy User, which is no
longer shipped with BMC Remedy AR System.
Page 1464 of 4705
Home
Tip
No Vision users might need more time to traverse forms, so increase the Session
Timeout in Minutes value on the Web tab. See Setting the Web tab.
Setting the Advanced tab

AR System User Preference form Advanced tab
Advanced tab fields

Area
name
Field Name
Description
Client
Form
Default
Form View
Specifies the view to be used as the default for all forms.
Legacy
*
Note
If the user enters a view name that does not exist, BMC Remedy AR System
determines which view best fits. This might not be the default view.
Open
Window
View
Extension
Specifies the extension to be used as the default for all forms opened from other forms.
Legacy
*
Note
If the user enters an extension that does not exist, BMC Remedy AR System
determines which view best fits. This might not be the default view.
Display
Hidden
Forms (
Admin)
Specifies which forms are available. Options are
Legacy
*
No Only forms designated as visible are available.

Yes All forms are available, whether designated as hidden or visible.
Note
This option is available only if the user is logged in as an administrator or
subadministrator to an active server.
Page 1465 of 4705
Home
Table
Refresh
Fields
Content on
Display
Specifies whether the data in a table field is refreshed automatically every time a form is
displayed.
Web
Note
The user can refresh the table manually by clicking on it.
Report
Report
Server
Specifies the name of the server where the following reporting forms reside:
Web
ReportType
ReportCreator
Report
ReportSelection
The server name also serves as the home for report definition files created. This entry is
necessary when the server that stores the reporting forms is different from the server that
stores the data to be reported on. This field is blank by default.
Result
View
AR
System
Reserved
ODBC Use
Underscores
Specifies whether to replace special characters with underscores when running reports.
Using underscores is important if the user is running Crystal Reports and field or form
names contain special characters.
Legacy
*
Alert Sort
Displays the last column on which the user sorted a result or alert list. The user can specify
Legacy
a value in this field.
Sort Criteria
Displays the value set when the user chooses Actions > Sort Options and specify values.
The user can set sort options on a per-form basis.
Legacy
*
AR System
Reserved
Reserved for future use.
N/A
Setting the Alert tab

AR System User Preference form--Alert tab
Alert tab fields

Area name
Field Name
Description
Client
Listen Port
Port Number
Designates the port on which to listen for alerts.
N/A*
Page 1466 of 4705
Home
Logging
Enabled
Logging
Designates whether logging should occur for Alert.
N/A*
If Yes, Logging
Path
Designates the path and name of the log file. By default, alert log files are stored
N/A*
with a .log file extension.

Designates which application should be used to open the Alert List. The options
are
Open Alert List

using
Web
AR System User
Web
On Startup
Server
Designates the server to be used to open the Alert list.
N/A*
Display Alert
Message
Designates whether to display alert information when received.
N/A*
Flash Icon
Designates whether to flash the Alert icon when an alert is received.
N/A*
Beep
Designates whether to beep when an alert is received.
N/A*
Play Wav File
Designates whether to play a .wav file when an alert is received.
N/A*
Wav File
Designates the .wav file to play if the Play Wav File option is set to Yes.
N/A*
Run Process
Designates whether to run a process when an alert is received.
N/A*
Run Process
File
Designates the process to run if the previous option is set to Yes.
N/A*
* N/A = The setting does not apply to a particular client. The setting applies to activities such as
logging or other clients.
Setting the Confirmation tab

AR System User Preference form Confirmation tab
Confirmation tab fields

Area
name
Field Name
Description
Client
Confirm
After Creating a New

Request
Defines whether a confirmation appears after a request is created. The options are
Web
No (Default) The entry is submitted without verification.
Page 1467 of 4705
Home
Yes A dialog box appears after the form is submitted to verify the
submitted entry and the entry ID.
When Deleting a
Report
Defines whether a confirmation appears when the user tries to delete a report. The
Legacy
options are
No (Default) The report is deleted without verification.

Yes A dialog box appears when the user tries to delete a report.
When Deleting a
Saved Search
Defines whether a confirmation appears when the user tries to delete a saved
Legacy
search. The options are
No (Default) The saved search is deleted without verification.

Yes A dialog box appears when the user tries to delete a saved search.
When Deleting a
Macro
Defines whether a confirmation appears when the user tries to delete a macro.
The options are
Legacy
*
No (Default) The macro is deleted without verification.

Yes A dialog box appears when the user tries to delete a macro.
Setting the Edit tab

AR System User Preference form Edit tab
Edit tab fields

Area
name
Field Name
Description
Client
Table
Field
Table Field
Column
Width
Information about a table field that BMC Remedy AR System saves when the user changes
the size of columns in the table field, including the server name, form name, table field ID,
column ID, and the size of the column.
Legacy
*
Table Field
Column
Order
Column order preference.
Legacy
*
Table Field
Column Sort
Not used.
N/A**
Page 1468 of 4705
Home
Schema
Table Field
Refresh
Interval
Interval at which tables automatically refreshes (in minutes). Valid values are 0-99.
Web
Column
Width
Information about a results list that BMC Remedy AR System saves when the user changes
the column size in a results list.
Legacy
*
Column
Order
Information about a results list that BMC Remedy AR System saves when the user reorders
the columns in a results list.
Legacy
*
Grid Height
Parameter set in Customize View mode by choosing Layout > Grid Size and specifying a
value.
Legacy
Parameter set in Customize View mode by choosing Layout > Grid Size and specifying a
value.
Legacy
*
Flag that specifies whether to display extra field name and ID information in the field Help
text. Values are:
Legacy
*
Grid Width
App
Development
Mode
1 Display the extra field information.

0 (Default) Do not display the extra field information.
Menu
Position
Menu window position. Options are:
Legacy
*
Default See Center.

Left Left of where menu icon clicked.
Center (Default) Center of the browser window.
Right Right of where menu icon clicked.
Screen Center Center of screen.
Max Size
Base Menu
Upper limit for the number of items a menu can have. Used for currency and edit field menus
.
Legacy
*
Items Per
Column
Obsolete.
N/A**
List Position
List-menu window position. Options are:
Legacy
*
Default See Center.

Left Left of where menu icon clicked.
Center (Default) Center of the browser window.
Right Right of where menu icon clicked.
Screen Center Center of screen.
List Menu
Width
Width of the list menu window.
Legacy
*
List Menu
Height
Height of the list menu window.
Legacy
List Indent
Space in pixels on left before list items in list menu.
Legacy
*
Items
Threshold
When smart menus is selected, the number of items where menus change from pop-up to list
menus.
Web
Level
Threshold
When smart menus is selected, the number of levels where menus change from pop-up to
list menus.
Web
Diary Width
Diary editor window width.
Page 1469 of 4705
Home
Legacy
*
Edit
Diary
Field
Edit
Text
Field
Diary Height
Diary editor window height.
Legacy
*
Text Width
Text editor window width.
Legacy
*
Text Height
Text editor window height.
Legacy
*
** N/A = The setting does not apply to the web client. The setting applies to activities such as
Setting the General tab

AR System User Preference form General tab
AR System User Preference form General tab

Area
name
Field Name
Description
Client
Search
Search Path
Designates the directories where the user can access custom reports and macros. The path is
Legacy
*
typically userHomeDirectory/arHome/arcmds. To change the search path, the user must

enter the entire directory name for the directory to which the user wants access. To specify
more than one directory, the user must separate each directory name with a semicolon.
Note
If the user deletes all directories from the search path, the user cannot access any
custom reports or macros.
Num Items
in Recently
Used List
The number of recently used items. The user can specify from 4 to 9 items. The default is 5.
This setting applies to these menu lists in the browser:
Legacy
*
File > Recent New Forms

File > Recent Search Forms
File > Recent Requests
Page 1470 of 4705
Home
File > Recent Entry Points

Actions > Recent Searches
Tooltip
Hover
Wait
Time
Hover Wait
Time in
Milliseconds
Specifies the amount of time (in milliseconds) that the system waits to display a tool tip after
the user hovers over an object.
Web
On
New
On New
Defines how fields are set in a form opened in New mode. The options are:
Web
Set Fields to Default Values (Default) Fields are filled with default values when a
new form is opened or when a form is reset after a request is submitted.
Keep Previous Field Values Fields are filled with the previously used values when
that form is reset after a request is submitted.
Clear All Fields All fields are cleared when a new form is opened or when a form is
reset after a request is submitted.
When no option is selected, the default ( Set Fields to Default Values) is used.
On
Search
On Search
Defines the action a form opened in Search mode takes after the user performs a search,
displays the records in modify or display mode, and then returns to the search form without
closing the form. The options are:
Web
Set Fields to Default Values Fields are filled with default values.
Keep Previous Field Values Fields are filled with previously used values.
Clear All Fields (Default) All fields on search forms are cleared.
When no option is selected, the default ( Clear All Fields) is used.
Show
Result List
Defines whether the user views only the results list after every search. If the user selects No,
the results list and a detail pane are displayed after every search.
Web
Defines whether the number of search results returned is limited. The options are:
Web
Only
Limit
Number of
Items
No (Default) All results are returned.
Returned
Yes The number specified here is returned. When the user selects Yes, the next field
is enabled, and the user can specify the number of search results returned. The default
value is 1000.
The Max Entries Returned by the GetList server setting in the Configuration tab of the AR
System Administration: Server Information form can override this preference. BMC Remedy
AR System uses the lesser value.
On
Open
Defines whether to show the advanced search bar when a new window is opened.
Web
Maximize
Window
Defines whether a form is maximized when it is opened. If the user selects No, the form fills
only a portion of the browser.
Web
Show Most
Recent First
Defines the order in which entries appear in the diary field of a form. The options are:
Web
Show
Advanced
Search Bar
Diary
Field
Yes Diary entries are listed in descending order by date, starting with the most recent
entry.
No (Default) Diary entries are listed in ascending order by date, starting with the
earliest entry.
Default See No.
Display As
Specifies how menus attached to a character field are displayed. The options are:
Web
Page 1471 of 4705
Home
Field
Menu
Default See Popup menus.

Popup menus (Default) Displays menus in standard pop-up style. Hierarchical
menus are displayed with arrows indicating that users must move the cursor to the right
to view lower-level menu items. Large menus can cause display problems.
List boxes Displays menus in tree view style. Use this option to display large menus.
Smart menus Displays menus in standard pop-up format except when the menu
exceeds four levels or the total number of menu items exceeds 200. In those cases, the
menu is displayed as a list box.
To change these thresholds, use the Item Threshold and Level Threshold options on the
Edit tab. See Setting the Edit tab. If no option is selected, the default is used.
Expand at
Startup
Determines whether field menus are expanded when the menu is opened. The options are:
Legacy
*
Yes All levels of the menu are displayed when the menu is opened. (This is not
supported in browsers.)
No Only the first level is displayed when the menu is opened.
Flat Look
On Forms
Designates whether forms have a flat or 3-D look. The options are:
Legacy
*
No Use shadows to give the form a 3-D feel.

Yes Do not use shadows. This gives the form a "flat" appearance.
Setting the Home Page tab

AR System User Preference form Home Page tab
Home Page tab fields

Area
name
Field
Name
Description
Client
Home
Page
AR
Server
Designates the name of the server that contains your home page. For more information, See
Configuring home page preferences.
Web
Form
Designates the name of the form to be used as the default home page when the user logs in. For
more information, see Configuring home page preferences.
Web
Defines to what degree the Object List is enabled.
Legacy
*
Name
Object
List
Enable, Show All The Object List lists all the applications, guides, and forms on the
servers that the user is logged in to.
Page 1472 of 4705
Home
Enable, Show Only Entry Points The Object List lists only those entry points for which
the user has permissions.
Disable Access to the Object List is not possible. The File > Open > Object List menu
item and toolbar button are disabled.
Setting the Locale tab

AR System User Preference form Locale tab
Locale tab fields

Area
name
Field
Name
Description
Client
Locale
User
Locale
Designates the language displayed on the user's system, in the format language _country, where
Web
language is the language code (such as fr for French or en for English), and country is the
two-letter country code (such as FR for France or US for United States). Some sample entries are:
en_US English (United States)
fr_BE French (Belgium)
fr_CA French (Canada)
zh_HK Chinese (Hong Kong)
zh_CN Simplified Chinese
ja_JP Japanese (Japan)
This field is clear by default.
Time
Zone
Display
Date/
Time
Style
Defines the time zone displayed on the user's system. Select a time zone from the menu, for
example, Asia/Tokyo, America/New York, or Europe/Paris. Any ICU (International Component for
Unicode) format is accepted. This field is clear by default.
Web
Defines the format in which the date and time appear. According to Windows format, the options
are:
Legacy
*
Short
Long
Custom
This setting is platform-independent and is not automatically the same as any preferences set in
the Windows Control Panel. Use a predefined Windows format. The default is Short.
Page 1473 of 4705
Home
Custom
Date/
Time
Format
Defines the custom Date/Time length format. This field is active only when Custom is selected
from the Display Date/Time Style menu list. To customize separators and other options, the user
Legacy
*
must use a predefined Windows format or a customized Windows format. The EEE and EEEE day
formats do not work in this field. For example, if the user enters EEEE, MMMM dd, yyyy, the day
of the week displays in the browser as EEEE, not the actual day (for example, Tuesday). This field
is clear by default.
Currency
The type of currency to be applied for this locale (for example, USD for United States dollars). If
Web
currency is specified here, it overrides the developer-defined Initial Currency Type field property.
If this field has a default value, it overrides the User Preference and the Initial Currency Type.
Setting the Logging tab

AR System User Preference form Logging tab
Logging tab fields

Area
name
Field Name
Description
Client
Client
Macro
Designates whether the use of macros on the client is logged.
Legacy
*
Active Links
Designates whether the use of active links on the client is logged.
Web
Timings (Web)
Designates whether the time of a request and responses between browser, mid tier server,
and BMC Remedy AR System server are logged.
Web
API
Designates whether use of APIs on the server is logged.
Web
Filter
Designates whether use of filters on the server is logged.
Web
Database
Designates whether activity on the database is logged.
Web
Global
Logging
Enabled
For future use.
Log File Path
Defines the path to the log file.
Server
Global
Web
Page 1474 of 4705
Home
For more information about logging, see Analyzing logs and Tracking client caches.
Setting the Misc tab

AR System User Preference form Misc tab
Misc tab fields

Area name
Field Name
Description
Client
Open Dialog
Shortcut Dir
Indicates the directory to use when creating a shortcut. This value is used when the user
Legacy
*
selects an item from the Open Object List and right-clicks to create a shortcut or when
the user right-clicks a results list and chooses Send To > Desktop.
Find
Performance
Not currently used.
Legacy
*
Preferences that relate to how the browser caches forms. Definitions (for forms and
Legacy
*
related workflow) are loaded into memory from the . arf and .arv cache files and retained
as long as these files are current. This enables subsequent loads of the same form to
load more rapidly since the definitions do not have to be re-read from the disk each time
. To reduce the amount of memory used, several checks are made periodically to see if
definitions can be removed from the memory cache. During these checks, the following
calculation is performed:
Duration Since Last Used = Current Time - Time Definition Last Used
Max Age In
Minutes
If the Duration Since Last Used value is greater than the preference set for Max Age
In Minutes, the form definition can be removed from the memory cache.
Legacy
*
Min Age In
Minutes
If the Duration Since Last Used value is greater than the preference set for Min Age In
Legacy
Minutes, the form definition can be removed from the memory cache. If the system is
approaching the memory limit (Percent of Memory), the Duration Since Last Used
value is taken in conjunction with the Min Age In Minutes value to determine whether
the definition can be removed from the memory cache.
Usage
Threshold
Each time a form is opened, the system increments a usage count. As the memory limit
Percent Of
Memory
Represents a memory threshold. It is compared to the percent of memory used for the
memory cache to determine if the memory limit is reached. This check is used in
is approached, the Usage Threshold value is compared to the usage count to

determine if the definition can be removed from the memory cache.
Legacy
*
Legacy
*
conjunction with the Usage Threshold and the Min Age In Minutes values.
App
Response
Timeout
DDE Application Response Timeout in the browser.
Legacy
*
Page 1475 of 4705
Home
Transaction
Timeout
DDE Transaction Timeout in the browser.
Legacy
*
RPC
Timeout
RPC Timeout for submits in the browser.
Legacy
*
RPC
Timeout
Long
RPC Timeout Long queries in the browser.
Legacy
*
RPC
Timeout
RPC Timeout for extra long operation in the browser.
Legacy
*
Designates whether the macro bar is displayed when the browser starts.
Legacy
*
Show Status
Bar
Designates whether the status bar is displayed when the browser starts.
Legacy
*
Show
Toolbar
Designates whether the toolbar is displayed when the browser starts.
Legacy
*
Disable Web
Help
Designates whether items under BMC Remedy on the Web under the main Help menu
in the browser are disabled.
Legacy
*
Save
Window On
Close
Designates whether to save information about open New and Search windows in the
browser when you close the tool.
Legacy
*
Query On
Return
Designates whether you can initiate a query by pressing the Enter key in the Request
Legacy
*
Close After
Submit
Designates whether to close a New window after a request is submitted in the browser.
Legacy
*
Show Lang
DLL Not
Obsolete.
Legacy
*
Step Size
Obsolete.
Legacy
*
Result Open
On
Double-Click
Designates which panes open when you double-click a record in a results view. The
options are:
Legacy
*
Normal
Extra Long
View
Show Macro
Bar
ID field.
found
Value greater than zero Open the form with a results pane and a detail pane.
0 (Zero) Open the form with a detail pane only.
Setting the Recent tab

AR System User Preference form Recent tab
Page 1476 of 4705
Home
Recent tab fields

Field Name
Description
Client
Recent Forms
A list of recent forms opened in the browser.
Legacy*
Recent Tickets
A list of recent requests opened in the browser.
Legacy*
Recent Applications, Guides, etc.
A list of recent applications or guides opened in the browser.
Legacy*
Recent Entry Points
A list of recent entry points opened in the browser.
Legacy*
Setting the Report tab

AR System User Preference form Report tab
Report tab fields

Area name
Field Name
Description
Client
Default
Margins
Left Margin
Right Margin
Defines the number of blank characters from the left or right edge of the page. The
Web
Top Margin
Bottom Margin
Defines the number of blank lines from the top or bottom edge of the page. The default
value for the top and bottom margin is 1 line.
Web
Column Titles
ColumnRequest
Defines the default characters to separate column titles, columns, or requests,

respectively. By default, column titles are separated by hyphens (-), and columns and
requests are separated by a blank space. You can use any of these special characters:
Web
Default
Separators
default for the left and right margin is 0 characters.
\b (backspace)
\n (return)
\t (tab)
Page 1477 of 4705
Home
*
* (backslash)
** nnn (ASCII character)
Default
Page Size
Misc.
Default
Orientation
Defines whether the default page is in Portrait or Landscape mode.
Web
Use printer
default page
size
Designates whether the default page size should correspond to the default printer page
size.
Web
Lines Per Page
Designates how many lines of text are printed on each page. The default value is 66.
Web
Chars Per Line
Designates how many characters are printed on each line. The default value is 80.
Web
Column Title
Per
Designates a default value for how often column titles appear in a report. The options
are:
Web
6 Column titles appear for each request in the report.

7 Column titles appear for each page in the report.
8 No default.
Page Break Per
Designates a default value for how often page breaks occur in a report. The options are
:
Web
6 Page breaks occur after each request in the report.

7 Page breaks occur after each page in the report.
8 No default.
ODBCReportDot
Indicates whether the ODBC driver should replace the dot in Crystal Report field
names. The options are:
N/A*
No (Default) Do not replace the dot.

Yes Replace the dot.
* N/A = The setting does not apply to the web client. The setting applies to activities such as
Setting the Web tab

AR System User Preference form Web tab
Web tab fields
Page 1478 of 4705
Home
Area
name
Field
Name
Description
Client
Report
Crystal
Report
Designates an application for viewing Crystal Reports. Options are
Web
Viewer
Java (using browser Oracle VM)

Java (using Java Plug-in)
ActiveX
Netscape Plug-in
HTML with frames
HTML without frames (the default)
When no option is selected, the value that the administrator sets is used.
Note
Crystal Reports Server 11 and Business Objects 11 support only the DHTML viewer,
so do not select the Java, ActiveX, or Netscape Plug-in options. Crystal Enterprise 10
supports all viewers.
Alert
Specifies the interval, in minutes, that passes between queries to the Alert Events form. The
default value is 0. The alert list displays the user's alerts by querying the Alert Events form that
contains the user's alerts.
Web
Alert
Servers
Specifies which servers contribute alerts to a web-based alert list. The administrator can enter
the server names to retrieve alerts from this field. The server names must be separated by the
comma ( , ) delimiter. This field is clear by default.
Web
Display
Date/
Specifies the format in which the date and time appear. Options are
Web
Refresh
Interval
Date/Time
Text
Time
Style (
Short
Long
Web)
Custom
The formats adhere to the ICU (International Component for Unicode) format. The format is
platform-independent and is not automatically the same as preferences set in the browser, or
as any preferences set in the Windows Control Panel. The user must use a predefined ICU
format or customize an ICU format to set web view Date/Time appearances. The default is
Short.
Session
Custom
Date
Format
Specifies the format of date strings to be displayed in the browser if the user selects Custom
Custom
Time
Format
Specifies the format of time strings to be displayed in the browser if the user selects Custom
from the Display Date/Time Style (Web) menu. The user can add a semicolon (:), dash (-), or a
period (.) as separators. This field is clear by default. For more information about time formats,
see AR System server components and external utilities.
Web
Session
Specifies the number of minutes after which a session times out. The default is 90 minutes. The
user can set the session timeout for longer than 90 minutes, and this setting overrides the
session timeout in the General Settings page of Mid Tier Configuration Tool.
Web
Specifies whether animated field effects (which show conditions such as state transition) are
enabled.
Web
Timeout
in
Web
from the Display Date/Time Style (Web) menu. The user can add a forward slash (/), dash (-) or
a period (.) as separators. This field is clear by default. For more information about date formats
, see AR System server components and external utilities.
Minutes
Animation
Animated
Effects
Page 1479 of 4705
Home
Setting the Window tab

AR System User Preference form --- Window tab
Window tab fields

Area name
Field Name
Description
Client
Window Size
Pick/Selection List
Selection List window position.
Legacy*
Toolbars
Summary
Coded information about toolbars.
Legacy*
Bar0
Legacy*
Bar1
Legacy*
Bar2
Legacy*
Bar3
Legacy*
Date and time formats

This section describes BMC Remedy AR System date and time formats.
Short date formats
Long date formats
Day formats
Time formats
Additional date or time display characters
Short date formats

The following table lists all the available Short Date Formats in the AR System User Preference
form.
Short date formats
Short Date
Format
Description
Examples
MM/dd/yyyy
Page 1480 of 4705
Home
Short Date
Format
MM/dd/yy
MM/d/yyyy
Description
Examples
Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days,
01/01/2009
four-digit year)
01/15/2009
Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days,
01/01/09
two-digit year)
01/15/09
Month, Day, Year (leading zero for single-digit months, four-digit year)
01/1/2009
01/15/2009
MM/d/yy
Month, Day, Year (leading zero for single-digit months, two-digit year)
01/1/09
01/15/09
M/dd/yyyy
Month, Day, Year (leading zero for single-digit days, four-digit year)
1/01/2009
1/15/2009
M/dd/yy
Month, Day, Year (leading zero for single-digit days, two-digit year)
1/01/09
1/15/09
M/d/yyyy
Month, Day, Year (four-digit year)
1/1/2009
1/15/2009
M/d/yy
Month, Day, Year (two-digit year)
1/1/09
1/15/09
dd/MM/yyyy
dd/MM/yy
dd/M/yyyy
Day, Month, Year (leading zero for single-digit days, leading zero for single-digit months,
four-digit year)
01/01/2009
Day, Month, Year (leading zero for single-digit days, leading zero for single-digit months,
two-digit year)
01/01/09
Day, Month, Year (leading zero for single-digit days, four-digit year)
01/1/2009
15/01/2009
15/01/09
15/1/2009
dd/M/yy
Day, Month, Year (leading zero for single-digit days, two-digit year)
01/1/09
15/1/09
d/MM/yyyy
Day, Month, Year (leading zero for single-digit months, four-digit year)
1/01/2009
15/01/2009
d/MM/yy
Day, Month, Year (leading zero for single-digit months, two-digit year)
1/01/09
15/01/09
d/M/yyyy
Day, Month, Year (four-digit year)
1/1/2009
15/1/200 9
d/M/yy
Day, Month, Year (two-digit year)
1/1/09
15/1/09
yyyy/MM/dd
yyyy/MM/d
Year, Month, Day (four-digit year, leading zero for single-digit months, leading zero for
single-digit days)
2009/01/01
Year, Month, Day (four-digit year, leading zero for single-digit months)
2009/01/1
2009/01/15
2009/01/15
yyyy/M/dd
Year, Month, Day (four-digit year, leading zero for single-digit days)
2009/1/01
2009/1/15
yyyy/M/d
Year, Month, Day (four-digit year)
2009/1/1
2009/1/15
Page 1481 of 4705
Home
Short Date
Format
Description
Examples
yy/MM/dd
Year, Month, Day (two-digit year, leading zero for single-digit months, leading zero for
09/01/01
single-digit days)
09/01/15
Year, Month, Day (two-digit year, leading zero for single-digit months)
09/01/1
yy/MM/d
09/01/15
yy/M/dd
Year, Month, Day (two-digit year, leading zero for single-digit days)
09/1/01
09/1/15
yy/M/d
Year, Month, Day (two-digit year)
09/1/1
09/1/15
Long date formats

The following table contains a complete list of the available Long Date Formats that can be
selected in the AR System User Preference form.
Long date formats
Format
Example
dd MMMM, yyyy
01 January, 2009
dd MMMM, yy
01 January, 09
dd MMM, yyyy
01 Jan, 2009
dd MMM, yy
01 Jan, 09
d MMMM, yyyy
1 January, 2009
d MMMM, yy
1 January, 09
d MMM, yyyy
1 Jan, 2009
d MMM, yy
1 Jan, 09
MMMM dd, yyyy
January 01, 2009
MMMM dd, yy
January 01, 09
MMMM d, yyyy
January 1, 2009
MMMM d, yy
January 1, 09
MMM dd, yyyy
Jan 01, 2009
MMM dd, yy
Jan 01, 09
MMM d, yyyy
Jan 1, 2009
MMM d, yy
Jan 1, 09
Day formats
The following table lists the available day formats in AR System User Preference form.
Day formats
Page 1482 of 4705
Home
Day Format
Description
Examples
EEEE
Long day format. The day is displayed in full.
Friday, Thursday
EEE
Short Day format, three characters only.
Fri, Thu
Note
(Japanese environment only) On the Web tab of the AR System User Preferences form,
do not use the following format in the Display Date/Time Style (Web) field with the Custom
setting in a Japanese environment: EEEE, MMMM dd, yyyy Otherwise, the BMC Remedy
Mid Tier returns ARERR 9376 when a browser user tries to modify an entry in any form.
Time formats
The following table lists the available time formats available in the AR System User Preference
form.
Time formats
Time Format
Description
Examples
h:mm:ss a
Time in 12-hour format (no leading zero for single digit hours)
1:23:45 AM, 10:23:45 PM
hh:mm:ss a
Time in 12-hour format (leading zero for single digit hours)
01:23:45 AM, 10:23:45 PM
H:mm:ss
Time in 24-hour format (no leading zero for single digit hours)
1:23:45, 22:23:45
HH:mm:ss
Time in 24-hour format (leading zero for single digit hours)
01:23:45, 22:23:45
Additional date or time display characters

To include additional characters in your custom date or time display, enclose them in single
quotation marks.
Additional characters for a custom display
Format
Example
'Date' MM/dd/yy
Date 01/01/05
'Time' hh:mm:ss a
Time 01:23:45 AM
Page 1483 of 4705
Home
Setting user preferences in the BMC Remedy Mid Tier

Centralized preferences help users who want to have the same settings and customizations
available when they use multiple computers. Users logging in to web clients must use centralized
preferences to store preferences, and any changes that are made take effect immediately.
The administrator or browser users can set preferences by updating the AR System User
Preference form, which is available at the following case-sensitive URL:
http:// <midTierServer>/arsys/forms/<ARSystemServer>/AR System User Preference
The BMC Remedy Mid Tier does not use the operating system locale settings. It uses the
preference records created in the AR System User Preference form if the AR System server on
which the form resides is enabled as a preference server. (See Setting user preferences in the
BMC Remedy Mid Tier. For details about the fields on each tab in this form, see Setting the AR
System User Preference form.) If a user does not have a preference record, the default Java
settings for the operating system's locale are used.
Conversely, the browser honors operating system locale settings when the user is not using a
preference server and when no locale is set in the Options dialog box in the browser. The following
field types use the operating system's locale information when parsing:
Date/Time field
Date field
Time field
Currency field
Real Number field
Decimal Number field
Diary field and the date and time stamp for each entry
Note
Users who log in to the browser can choose to use local or centralized preferences. (Local
preferences are used when no preference server is designated or available.) Regardless
of whether centralized or local preferences are used, multiple users can use the same
client computer with individual preferences and customizations. See Setting user
preferences.
Page 1484 of 4705
Home
Defining business schedules using Business

Time
Business Time in BMC Remedy AR System is the ability to define periods of availability and
unavailability, workdays, and holidays to define business schedules using BMC Remedy AR
System commands.
Business Time introduction
Scheduling a time segment
Using time zones
Business Time 2.0 commands
Using the old Business Time forms
Migrating Workdays and Holidays to the Business Time Segment form
Business Time introduction

In this topic:
Business time architecture
How Business Time 2.0 works
Business Time 2.0 enables you to define periods of time as available or unavailable. To define
business time, you can use time segments such as workdays, holidays, or any other activity that
occurs in a business environment.
After you define the time segments, you can use the business time commands in your workflow.
The BMC Remedy AR System Business Time functionality is applicable to global enterprises with
multiple regional centers:
Businesses can use the availability function to block periods of time by region. For example,
a customer might want to make certain functions unavailable for Japanese offices during
Golden Week in Japan.
Businesses can use the Business Time function according to their own rules for shift work
during work days and during holidays. They can define the different shifts (for example, the
evening shift and the morning shift) and the holidays to capture their work environment.
Different offices can set up different holiday and break schedules. A central administrator
can enter and manage business time and holidays for all international locations in different
time zones.
Page 1485 of 4705
Home
Business time architecture

The Business Time Segment form is the main business time form and is used to define segments
of time. These time segments can then be used to define any kind of activity.
Note
If you used the Business Time Holidays and Business Time Workdays forms in prior
releases, you can still use them to define holidays and workdays with the old set of
Business Time commands. However, in Business Time 2.0, all activities (including
holidays and workdays) are defined in the Business Time Segment form, and you must
use a new set of commands to work with the time segments defined in that form. The "
offset" that was previously available in the Business Time Workdays form is now available
in the Business Time Segment form. The Business Time 2.0 commands provide the same
functionality as the old Business Time commands (Add, Subtract, and Diff); however, all
future enhancements will be made to Business Time 2.0 only .
You can use the following summary of system forms to define Business Time 2.0:
Business Time Segment Defines time segment as available or unavailable, optionally on
a one-time or a recurring basis.
Business Time Shared Entity Stores detailed information about the entity used in the
Business Segment-Entity Association form. An entity is a generic object such as an asset,
categorization, or location.
Create an entity only if you need to associate a time segment to it. After an entity is created,
it can be reused. (You do not need to create another one.)
Business Segment-Entity Association Stores associations between entities (such as
assets, change requests, and groups, individuals, companies, and locations) and activities
that apply to those objects. It associates records in the Business Time Segment and
Business Time Shared Entity forms in a many-to-many fashion.
Business Segment-Entity Association_Join Used for query purposes. Acts as a join
form between the following forms:
Business Segment-Entity Association
Business Time Segment
Business Time Shared Entity-Entity Association_Join_Join Used for query purposes.
Acts as a join form between the following forms:
Business Time Shared Entity
Business Segment-Entity Association_Join
To use the Business Time 2.0 commands (see Business Time 2.0 commands), you
must create entries in the Business Time Segment form. The remaining forms are
optional that you can use to store entities and relate them to the Business Time
Page 1486 of 4705
Home
Segment entries.
These forms contain fields with IDs that BMC Remedy AR System recognizes. You
can change the name of the forms, but do not make copies of them because the AR
System server will not be able to find the correct form for finding business schedules.
The following figure shows the relationships between these forms.
Forms used to schedule time in BMC Remedy AR System
Note
If you upgrade your Business Time objects from BMC Remedy AR System
5.0, delete the filter BusWk:ValidateTimes02. This filter is not intended for
use on BMC Remedy AR System versions 5.1 and later.
How Business Time 2.0 works

The Business Time Segment form represents a window of time that can be described as a one time
activity (which can span multiple days) or a recurring activity (which cannot span multiple days; it
must be scheduled within a 24-hour period).
An object in the Business Segment-Entity Association form can be associated with:
One or more entries in the Business Time Segment form
Optionally, one or more entries in the Business Time Shared Entity form
In Business Time 2.0, time segments are defined using "levels". Levels 1 and 2 are special levels.
Level 1 time segments are treated as available time (workdays), and Level 2 time segments are
treated as unavailable time (holidays). If no Level 1 time segments are defined, all days are
considered available.
If holidays are defined at Level 2, they can be overridden by time segments at Level 3 and above. If
you do not want to override holidays, define them at a high level. For more information, see
Page 1487 of 4705
Home
Understanding levels.
To define business time and implement it in your BMC Remedy AR System application, follow this
process:
1. Define any combination of time segments, business hours, and business holidays.
For workdays, define available time segments at Level 1.
For holidays, define unavailable time segments at Level 2 or higher.
Define other time segments at Level 3 or higher.
2. Add business time commands to workflow in your application.
3. Test the application.
Using the list of Time Segment IDs, Workday IDs, and Holiday IDs, the Business Time component
in AR System builds a list of available and unavailable time windows for every day in the list of IDs.
For example, consider an entity that has a Workday schedule from 8:00 A.M. to 5:00 P.M., and two
activities associated with it. The first time segment defines an available time window at a Level 3
from 10:00 A.M. to 2:00 P.M., and the second time segment defines an unavailable time window at
Level 4 from 1:00 to 4:00 P.M. The Business Time component in BMC Remedy AR System
computes the final time window list for a day as shown in the following figure.
Workday and activities for one day
The application commands described in Business Time 2.0 commands work from the final list.
Scheduling a time segment

The Business Time Segment form stores availability, level, date and time ranges, and recurrence
information about a time segment. You can add an entry to this form to schedule a business time
segment for an entity in a BMC Remedy AR System application, such as an asset or a change
request, or a group, company, or location.
Understanding levels
Defining a one-time segment
Page 1488 of 4705
Home
Defining a recurring time segment

Understanding time segment entity associations
Understanding time segment shared entities
Understanding levels
Levels define a priority between different time segments, and a higher level time segment takes
precedence over lower-level time segments. Levels can be from 1 to 1000.
Levels 1 and 2 have special meaning. Level 1 time segments are "available" and can be used to
define workdays. Level 2 time segments are "unavailable" and can be used to define holidays.
Other time segments at Level 3 and above can be either "available" or "unavailable."
Note
Because higher levels of available segments can override Level 2 time segments, if you
do not want to override holidays, define holidays at a level higher than all other levels.
For all Business Time commands, a higher-level time segment takes precedence over lower-level
time segments, except for the Application-Bus-Time2-Get-Free-Window command.
For same-level time segments, the order of overlapping activities is not guaranteed. The business
component in BMC Remedy AR System determines the final list for these time segments in the
order they are retrieved.
Creating non-conflicting levels

Levels are used to determine the order in which overlapping or non-overlapping time segments
take effect. In Workday and activities for one day example in Business Time introduction, Time
Segment 2 is at a higher level than Time Segment 1. Hence, in the final list, the time window 1:00
P.M. to 2:00 P.M. is defined as unavailable.
Defining a one-time segment

1. Open the Business Time Segment form in new mode.
Business Time Segment form, One Time tab
Page 1489 of 4705
Home
2. In the ID field, enter a unique identifier. Use this identifier to reference the time segment in
workflow.
The identifier can be non-unique in special cases. For more information, see Migrating
Workdays and Holidays to the Business Time Segment form .
3. In the Description field, enter a description for the time segment.
4. In the Availability field, select Available or Unavailable.
5. For the Enable option, select Yes to enable the time segment.
Do not select Yes if you want to temporarily disable the time segment.
6. In the Level field, select a level.
Business Schedule Activities have a default level of 3, but you can change this level to any
number from 1 through 1000.
If the schedules for two activities or business hours and holidays conflict, the event with the
highest number takes priority.

See Understanding levels for more information about levels.
7. In the Category field, enter a description for the category.
This field helps determine what type of schedule time segment the item is (for example,
blackout, maintenance, and so on.) Although it is not a required field, it can help you
categorize your time segments.
8. From the Timezone list, select a time zone.
See Using time zones for more information.
The Offset field remains on the form for backward compatibility purposes. For new business
time segments, use the Timezone field.
9. In the Action field, select one of the following options:
Create as Described Creates the scheduled time segment without checking to
determine whether the Start Date and Time and the End Date and Time conflict with
that of another scheduled time segment. This option creates a time segment with a
status of Published. It applies to both One Time and Recurring duration types.
Page 1490 of 4705
Home
Create Next Free Finds the next free date and time and automatically creates the
scheduled time segment, making sure that no conflicting time slot exists. If the
specified Start Date and Start Time, and End Date and End Time are not available,
the time segment is scheduled for the next available time slot. This option creates a
time segment with a status of Published. It applies only to the One Time duration type
.
Note
To find conflicting items for the Create Next Free and Find Next Free
options, add items to the Non-Conflicting Activities field. If you do not, the
time segment you originally entered is used. See step 15 for more
information.
Find Next Free Finds the next free time slot based on the Start Date and Start
Timeand the End Date and End Time, and puts the value into the Next Free Date/
Time field. This option creates a time segment with a status of Draft. It applies only to
the One Time duration type.
Publish Changes the status from Draft to Published so the time segment can be
used by business time application commands.
Remove Mark the scheduled time segment to be deleted in an escalation that runs
nightly.
Draft Changes the status from Published to Draft so changes can be made to the
time segment. (You cannot change a record after it is published. First, move it to
Draft and save it. Then, make your changes.)
When you select an Action, the status of Draft, Published, or Remove appears in
the read-only Status field. A status of Draft indicates that the time segment can be
modified, but not used by business time application commands until the status
changes to Published.
10. In the Duration Type field, select One time to create a single occurrence of the time
segment.
To create a recurring business time segment, see Defining a recurring time segment.
11. Enter the Start Date, Start Time, End Date, and End Time for the duration of the time
segment.
If your day ends at midnight, select the End of Day check box. Then, any value in the End
Time field is ignored, and the day ends at midnight.
12. In the Earliest Start Time field, enter the earliest preferred start time for which to schedule
the time segment.
The search for a start time starts with the Start Date and Start Time and find the first
available time with the specified duration. If no time slot is found within the same day, it
continues to the next day, starting after the Earliest Start Time. If this field is blank, the
search for the next available time continues from 12:00 A.M. of the next day if necessary.
13.
Page 1491 of 4705
Home
13. In the Latest End Time field, enter latest preferred time by which the time segment should
end.
14. In the End Date Search Range field, enter the last date to search for an available time slot
within the specified Start Date and End Date. (The default is the End Date plus six months.)
The Start Date Search Range field is set to the Start Date and Start Time.
15. In the Non Conflicting Activities field, enter the IDs of the Business Time Segment,
Business Times Workdays, and Business Time Holidays definitions to check for schedule
conflicts.
16. If you selected Find Next Free as the Action in the top portion of the form, click in the Next
Free Date/Time field and press Enter to find the next available time slot.
The next free period for the time segment appears in the Next Free Date/Time field. If the
value is the same as the Start Date and Start Time, that time is available. If the time is
different, the original time that was specified for the Start Date/Time was not available and
the value represents the earliest available time.
17. Save the form.
18. View the time segment.
19. If this time slot is not acceptable:
a. Select the Find Next Free option.
b. Search for the next free time slot.
c. Save the form.
Defining a recurring time segment

1. Complete steps 1 through 9 from Defining a one-time segment.
2. Select the Recurring option for the Duration Type.
The Recurrence Definition tab appears on the form.
Business Time Segment form--Recurrence Definition tab
(Click the image to expand it).
3.
Page 1492 of 4705
Home
3. Select start and end dates and times.

For recurring activities, the Start Date and End Date fields determine the range of the
recurrence, and the Start Time and End Time determine the duration of the time segment.
If your day ends at midnight, select the End of Day check box. Then, any value in the End
Time field is ignored, and the day ends at midnight.
4. Select the Recurrence Type, and specify the recurrence as dictated by the tab that appears
when you select the option. (All the options accept a start date and return the next date.)
Specific dates A semicolon-separated list of dates (for example, 01/24/09;01/25/
09).
Daily Every specified number of days, such as every four days.
Weekly Every specified number of weeks on a specified day, such as every three
weeks on Tuesday and Thursday.
Monthly
Specified day of every specified month, such as the 24th day every three
months.
Specified week day of a specified number of months, such as the second
Tuesday every three months. This could also be used to define quarterly
activities.
Yearly
Specified day of the month, such as every fifth day of April.
Every specified week day of a month, such as every second Tuesday of April.
5. Save the form.
Understanding time segment entity associations

The Business Segment-Entity Association form stores associations between the Business Time
Segment form and the Business Time Shared Entity form.
Business Segment-Entity Association form
The Business Segment-Entity Associations form contains the following primary fields:
Entry ID An identifier for an entity to which the time segment is being applied, such as an
asset or a change request.
Page 1493 of 4705
Home
Entry Owner ID An identifier for the parent object owner of the entity. Enables you to
identify the original owner to determine whether you can change the association.
Time Segment ID A time segment name that was defined on the Business Time
Segment form. For more information, see Scheduling a time segment.
Assignee Groups Groups specified on Business Time Segment form. For more
information, see Scheduling a time segment.
Understanding time segment shared entities

The Business Time Shared Entity form stores logical references to a scheduled time segment. An
entity can define any generic object (for example, a business event or an asset).
Only one entity of the same type can exist in this form. After an entity is created, you must reuse
the existing copy in the entity from this form.
Business Time Shared Entity form
The Business Segment-Entity Association form contains the following primary fields:
Entity Type Used to classify the type of entity being created. Depending on this value, it
determines how the values are mapped to the Attributes fields. For example, if you have
Entity Type defined as "Category," then you can map Attribute 1 to store Category 1 field
data, Attribute 2 to store Category 2 field data, Attribute 3 to store Category 3 field data, and
so on.
POID Contains the Parent Object Instance ID field. It is used to reference any desired
generic object. Typically, it references the Instance ID of the parent object.
Attribute fields Include a set of 10 generic attributes that can be used to describe an
entity. Any character values can be mapped into these fields to describe an entity.
Page 1494 of 4705
Home
Using time zones

The Business Time Segment form includes a Timezone list from which you can select time-zone
values. When the AR System server executes a Business Time command and encounters a time
segment with a time zone, it adjusts the time to match the time in the specific time zone.
Using the time zone value of the Level 1 time segment
Using offset hours in Business Time 2.0
The following scenarios in this topic show ways to complete the Business Time Segment form, and
the results of the chosen options:
Standard time zone difference between AR System server and the Schedule scenario
Daylight savings time zone difference between AR System server and the Schedule scenario
Undefined time zone scenario
Standard time zone difference between AR System server and the Schedule
scenario
Assumption: The AR System server is in PST (GMT -8:00) Pacific Time (US and Canada).
Schedule:
ID = Level1_Recurring_1_1_2000_8am_to_1_1_2031_5pm_Weekly_Once_Mon_
to_Fri_Asia_Calcutta
Level = 1
Availability = Available
DurationType = Recurring
StartDate = 1/1/2000
StartTime = 8AM
EndDate = 1/1/2031
EndTime = 5PM
Timezone = Asia/Calcutta
Result: The Schedule time shifts to 6:30 P.M. - 3:30 A.M. because the time difference between the
AR System server and the Schedule is 8 + 5.50 = 13.50 hours (meaning 13 hours and 30 minutes).
Daylight savings time zone difference between AR System server and the
Schedule scenario
Assumption: The AR System server is in PDT (GMT -7:00) Pacific Time (US and Canada).
Schedule:
Page 1495 of 4705
Home
Level = 1
StartTime = 8AM
EndDate = 1/1/2031
EndTime = 5PM
Result: The Schedule time shifts to 7:30P.M. - 4:30 A.M. because the time difference between the
AR System server and the Schedule is 7 + 5.50 = 12.50 hours (meaning 12 hours and 30 minutes).
Undefined time zone scenario

Assumption: The AR System server is in PST (GMT -8:00) Pacific Time (US and Canada).
Schedule:
ID = Level1_Recurring_1_1_2000_8am_to_1_1_2031_5pm_Weekly_Once_Mon_ to_Fri
Level = 1
StartTime = 8AM
EndDate = 1/1/2031
EndTime = 5PM
Result: The Schedule considers the AR System server time because no time zone is defined.
Therefore, StartTime-EndTime remains 8 A.M. - 5 P.M.
Using the time zone value of the Level 1 time segment

The Use Level 1 option in the Timezone list enables you to define time segments that use the
time-zone value of the Level 1 time segment. If the Level 1 time segment has no time zone defined,
the value of the server's time zone is used.
You can define a time segment that has its own time zone. Consider the time segments TS1, TS2,
and TS3 in the following case:
TS1 is available at Level 1 with the time-zone value of Asia/Calcutta.
TS2 is unavailable at Level 2 with the time-zone value of Use Level 1. (TS2 uses the time
zone of TS1.)
TS3 is available at Level 3 with the time-zone value of Asia/Singapore. (TS3 has its own
time zone.)
Page 1496 of 4705
Home
Sample schedule with the Use Level 1 option

Assumption: The AR System server is in the GMT + 5:30 - Asia/Calcutta time zone.
TimeSegment1:
Level = 1
StartTime = 8AM
EndDate = 1/1/2031
EndTime = 5PM
Result: The Schedule time remains 8 A.M. - 5 P.M. because the server and the Schedule are in
the same time zone.
TimeSegment2:
ID = Level2_Recurring_1_1_2000_10am_to_1_1_2031_11am_Weekly_Once_
Mon_to_Fri_Use_Level_1
Level = 2
Availability = Unavailable
StartTime = 10AM
EndDate = 1/1/2031
EndTime = 11AM
Timezone = Use Level 1
Result: The Schedule time remains 10 A.M. - 11 A.M. because the server is in the Asia/Calcutta
time zone and the Schedule (which uses the time zone of the Level 1 time segment) is in the Asia/
Calcutta time zone.
TimeSegment3:
ID = Level2_Recurring_1_1_2000_12pm_to_1_1_2031_1pm_Weekly_Once_
Mon_to_Fri_Asia_Calcutta
Level = 2
Availability = Unavailable
StartTime = 12PM
Page 1497 of 4705
Home
EndDate = 1/1/2031
EndTime = 1PM
Result: The Schedule time remains 12 P.M. - 1 P.M. because the server and the Schedule are in
the same time zone.
TimeSegment4:
ID = Level3_Avail_Recurring_1_1_2000_9am_to_1_1_2031_10am_Weekly_
Once_Mon_to_Fri_Australia_Sydney
Level = 2
StartTime = 9AM
EndDate = 1/1/2031
EndTime = 10AM
Timezone = Australia/Sydney
Result: The Schedule time is converted to ServerTime as 3:30 A.M. - 4:30 A.M. because the
Schedule time zone Australia/Sydney is in DST with an offset of 5.50 (that is, 5 hours and 30
minutes).
Using the four time segments and the Add command, the Business Time command is
Application-Bus-Time2-Add "<startTime>" <amount> <amountUnits> TimeSegment1 TimeSegment2

TimeSegment3 TimeSegment4
If startTime is 1/23/2008 1:00:00 AM, the following scenarios could occur:

Case 1: If you add 1 second, the result is 1/23/2008 3:30:01 AM.
Case 2: If you add 1 hour, the result is 1/23/2008 8:00:00 AM.
Case 3: If you add 2 hours, the result is 1/23/2008 9:00:00 AM.
Case 4: If you add 3 hours, the result is 1/23/2008 11:00:00 AM (10 AM-11 AM is
Unavailable).
Case 5: If you add 4 hours, the result is 1/23/2008 1:00:00 PM (10 AM-11 AM and 12 PM-1
PM are Unavailable).
Case 6: If you add 7 hours, the result is 1/23/2008 4:00:00 PM (10 AM-11 AM and 12 PM-1
Case 7: If you add 8 hours, the result is 1/24/2008 3:30:00 AM (10 AM-11 AM and 12 PM-1
The following figure illustrates this example.
Page 1498 of 4705
Home
Example of Use Level 1
Using offset hours in Business Time 2.0
Note
The Offset field on the Business Time Segment form remains for backward compatibility.
The use of this field is not recommended. Use time zones (see Using time zones) instead
of offsets in cases where offsets were used to compensate for time-zone differences. In
cases where offsets were used to specify time segments that span midnight, use multiple
time segments--one from Start Time to midnight and the other from midnight to End Time.
The Business Time Segment form includes an Offset field, which is used under certain
circumstances to adjust for the time-zone differences between the client and the server. All
Business Time 2.0 commands are executed on the server, and they take in and return timestamp
values.
The AR System server converts date/time strings to a timestamp value. When the client and server
are on different time zones, if the conversion of the date and time to a timestamp happens on the
client (such as with active links), the offset should be set to the time zone difference between the
server and the client. If the conversion happens on the server, no offset is required.
For cases where the time segment spans across midnight (as specified in Defining business hours
using offset hours for old Business Time commands), do not use offsets.
Because "One Time" time segments can span multiple days, these time segments can span
midnight. "Recurring" time segments cannot span midnight; therefore, you should create multiple
time segments--one that goes to midnight one day, and another that starts from midnight to the
next day.
The first Level 1 offset is considered and applied to all the time segments in the application
commands. Offset fields for non-Level 1 time segments are disabled.
Page 1499 of 4705
Home
Business Time 2.0 commands

In addition to defining recurrence activities, business hours, and business holidays, you must use
commands to enable Business Time in your BMC Remedy AR System application. Business Time
functionality is available within the Set Fields workflow actions, and it uses the $PROCESS$ syntax
to run an internal process within the server to perform the calculation.
The command arguments are positional in the syntax used to run the processes. You can omit
trailing arguments. However, to set a later argument, you must supply the arguments that come
before the one that you want to set. To pass a parameter, simply enter "" in its place.
Business Times commands take Daylight Saving Time (DST) into consideration. See
Application-Bus-Time2-Add for an example.
You can create the following business time calculations:
Application commands
Business Segment-Entity Association commands
Old Business Time commands
Note
Business Time commands work only with Date/Time fields (not Date fields or Time fields).

Business Time command parameters
Business Time application commands
Application-Bus-Time2-Get-Free-Window scenarios
Using application commands with daylight saving time
Application-Get-Next-Recurrence-Time
Business Time command parameters

Following are the parameters for the Business Time commands. Each parameter must be set apart
in double quotation marks.
<businessTimeSegmentName> Indicates which entry in the Business Time Segment
form contains a definition for the activity to use for this calculation. You can specify multiple
business activity names. Omitting this value specifies that no business activity is used for
this calculation.
<duration> Specifies the size of the time segment in seconds. Specify 0 to return the
next time segment.
Page 1500 of 4705
Home
<earliestStartTime> Working in conjunction with the <latestStartTime>,

specifies the time range within which the free window should exist. The specified duration (<
duration> parameter) must be less than this range. For example, if the earliest time is 4:
00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration>
seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the
duration is greater than the specified time range, no value is returned. If the <
earliestStartTime> is not specified, the default of 0 hours (the beginning of the day) is
used.
<endTime> Ending time of the interval of which to calculate the difference.
<endTimeRange> A date and time value that defines the end of a search for a time
window.
<entity> Can be an asset, individual, group, company, location, or anything you want to
link a schedule to.
holidayScheduleName> For old Business Time commands, indicates which entry in
the Business Time Holidays form contains a definition for the holiday schedule to use for this
calculation. Omitting this value specifies no holidays.
<latestEndTime> Working in conjunction with the <earliestStartTime>, specifies
the time range within which the free window should exist. The specified duration (<
duration> parameter) must be less than this range. For example, if the earliest time is 4:
00 P.M. and the latest end time is 10:00 P.M., a window is returned that is <duration>
seconds long and starts after 4:00 P.M., even if a window exists before 4:00 P.M. If the
duration is greater than the specified time range, no value is returned. If the <
latestEndTime> is not specified, the default of 24 hours (midnight) is used.
<level> Indicates the level of the time segment to be scheduled. The value can be an
integer from 1 through 1000.
<amount> Specifies an amount of time to offset the start time by. The amount> can be
an integer value of 0 or greater. If not specified, <amount> defaults to 1. You can use 0 to
indicate the next available time. For example, if your open hours are 8:00 A.M. to 5:00 P.M.
and the Start Time in Application-Bus-Time2-Add, Application-Bus-Time2Assoc-Add, and Application-Bus-Time-Add commands is 7:00 A.M., the return value
is 8:00 A.M.
In previous versions, <amount> was known as <offset>.
<amountUnits> The unit of time, which can be set to 1 for seconds, 2 for minutes, 3 for
hours, or 4 for days. Any other setting reverts to hours (3).
<startTime> Starting time to which to add business time.
<startTimeRange> A date and time value that defines the start of a search for a time
window.
<windowFlag> A bitmask value with:
Bit 0 Indicates the beginning of an available or unavailable time segment. The
values are 1 (available) and 0 (unavailable).
Page 1501 of 4705
Home
Bit 1 Indicates whether to retrieve just one segment or all the segments between
the start and end times. The values are 1 (retrieve all segments) and 0 (retrieve one
segment). The value returned in this case is a semicolon-separated list of values.
<workdayScheduleName> For old Business Time commands, an identifier indicating
which entry in the Business Time Workdays form contains a definition for the work schedule
to use for this calculation. Omitting this value specifies open 7 days a week, 24 hours a day.
Business Time application commands

In this topic:
Application-Bus-Time2-Add
Application-Bus-Time2-Diff
Application-Bus-Time2-Subtract
Application-Bus-Time2-Get-Next-Window
Application-Bus-Time2-Get-Free-Window
Important
The Olson (also Olsen) time zone format is the default on AIX when time zones are set
through System Management Information Tool (SMIT). When the Olson time zone format
is used with an AR System server running on AIX, however, the AR System server
miscalculates dates and times when executing Business Time application commands.
Therefore, BMC recommends that you use the POSIX time zone setting for AR System
servers running on AIX. When the POSIX format is used, the AR System server correctly
calculates dates and times affected by Business Time application commands.
Application-Bus-Time2-Add
The Application-Bus-Time2-Add command adds the requested offset to the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time into
the future.
Use the following syntax for the Application-Bus-Time2-Add calculation:
Application-Bus-Time2-Add *"*startTime" ["<amount>" ["<amountUnits>" ["<
businessTimeSegmentName1>" " <businessTimeSegmentName2>" . . . ]]]
The <startTime parameter> is required in this command. This parameter must be a value
such as a field reference ($<fieldName>$). Other fields are optional and use the default value if
not provided. You can specify multiple business activity names.
For example, to add one day, use the following calculation:
$PROCESS$ Application-Bus-Time2-Add "$<fieldName>$" "<amount>" "<
Page 1502 of 4705
Home
amountUnits>"
This adds one day to the value in <fieldName>. In the example, <fieldName> is <startTime>.
<amount> (offset) is set to 1, and <amountUnits> is set to 4 (representing days), thus adding 1
day to the calculation. The final syntax looks like:
$PROCESS$ Application-Bus-Time2-Add "$8/26/2004$" "1" "4"
Application-Bus-Time2-Diff
The Application-Bus-Time2-Diff computes the difference between the start time and the
end time. The command returns an integer representing the difference in seconds. Use this
command to compare two different times (start time and end time) to get the actual business time.
Use the following syntax for the Application-Bus-Time2-Diff calculation:
Application-Bus-Time2-Diff "<startTime>" "<endTime>" ["<
businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]]
The <startTime> and <endTime> parameters are required in this command. Other fields are
optional and use the default value if not provided. You can specify multiple business activity names.
Application-Bus-Time2-Subtract
The Application-Bus-Time2-Subtract subtracts the requested offset from the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time in the
past.
Use the following syntax for the Application-Bus-Time2-Subtract calculation:
Application-Bus-Time2-Subtract "<startTime>" ["<amount>" ["<amountUnits>"
["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]]]
The <startTime> parameter is required in this command. Other fields are optional and use the
default value if not provided. You can specify multiple business activity names.
Application-Bus-Time2-Get-Next-Window
The Application-Bus-Time2-Get-Next-Window command returns the start of the next
available or unavailable time segment that is <duration> seconds long. If <duration> is 0 (the
default), the command returns the start of available time segment or the start of unavailable the
time segment.
Additionally, depending on the <windowFlag>, the command returns one time segment or all the
time segments between <startTimeRange> and <endTimeRange>.
Page 1503 of 4705
Home
Use the following syntax for the Application-Bus-Time2-Get-Next-Window calculation:

Application-Bus-Time2-Get-Next-Window "<startTimeRange>" "<endTimeRange>"
["<duration>"] ["<windowFlag>"] ["<businessTimeSegmentName1>" "<
businessTimeSegmentName2>" . . . ]
Application-Bus-Time2-Get-Free-Window
The Application-Bus-Time2-Get-Free-Window command returns the start of the next
available or unavailable free time segment at the same level or a higher level that is <duration>
seconds long. A free time segment at Level <level> and Duration <duration> is one where no
other time segment at the same or higher level as <level> overlaps, or starts or ends in the <
duration> of this time segment. After a free time segment is obtained, it can be created as
available or unavailable. The default value for <duration> is 0, which returns the next available
time segment.
Use the following syntax for the Application-Bus-Time2-Get-Free-Window calculation:
Application-Bus-Time2-Get-Free-Window "<startTimeRange>" "<endTimeRange>"
["<level>"] ["<duration>"] ["<earliestStartTime>"] ["<latestEndTime>"] ["
<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . ]
The command considers all Business Time Segments at a certain level or above and treats them
as unavailable, regardless of whether they are available or unavailable. If Level 1 and 2 time
segments are present, they are always considered and are taken as available and unavailable,
respectively.
Application-Bus-Time2-Get-Free-Window scenarios
In this topic:
No Earliest Start Time or Latest End Time scenario
Earliest Start Time for Level 2 scenario
Earliest Start Time is specified or unspecified scenario
Duration of two hours scenario
Duration of 7200 seconds scenario
No Earliest Start Time or Latest End Time scenario

Application-Bus-Time2-Get-Free-Window "7/12/05 11:00:00 AM" "7/15/05 3:00
:00 PM" 2 3600 "" "" "" "Work1" "Act1" "Act2" "Act3"
Consider an entity that has the following conditions:
Work1has the following Workday schedule:
Available: Wednesday through Friday, 8:00 A.M. to 5:00 P.M.
Unavailable: Wednesday through Friday, 12:00 A.M. to 8:00 A.M. and 5:00 P.M. to
Midnight
Page 1504 of 4705
Home
Unavailable: Saturday through Tuesday, whole days

Act1 defines an available time window at a Level 3 from 10:00 A.M. to 2:00 P.M. on 7/13/05
.
Act2 defines an unavailable time window at Level 3 from 7:00 A.M. to 9:00 A.M. on 7/13/05.
Act3 defines an unavailable time window at Level 4 from 1:00 P.M. to 4 P.M. on 7/13/05.
A free window of duration 3600 seconds (1 hour) is required. There is no Earliest Start Time or
Latest End Time.
The following figure shows the return value for Get-Free-Window for a specific day. The two
Final lists show the final time window that Get-Free-Window uses in case a free window is
required at Level 2 or at Level 4.
For Level 2, the free window is available from 9:00 A.M. to 10:00 A.M. and from 4:00 P.M. to 5:00
P.M. Get-Free-Window returns 1121270400 (July 13, 2005, 9:00 A.M.).
For Level 4, the free window is available from 8:00 A.M. to 12:00 P.M. and from 3:00 P.M. to 4:00
P.M. Get-Free-Window returns 112166800 (July 13, 2005, 8:00 A.M.).
Application-Bus-Time2-Get-Free-Window command example
Earliest Start Time for Level 2 scenario

:00 PM" 2 3600 "11:00:00 AM" "" "" "Work1" "Act1" "Act2" "Act3"
In this scenario, if the Earliest Start Time for Level 2 is 11:00 A.M., the return value at Level 2 is
1121295600 (July 13, 2005, 4:00 P.M.).
Page 1505 of 4705
Home
Earliest Start Time is specified or unspecified scenario

:00 PM" 2 3600 "5:00:00 AM" "2:00:00 PM" "" "Work1" "Act1" "Act2" "Act3"
If the Earliest Start Time is 5:00 A.M. (or if it is not specified) and if the Latest End Time is 2:00 P.M
., the return value at Level 2 is 1121270400 (July 13, 2005, 9:00 A.M.).
Duration of two hours scenario

If the duration required is two hours, "" is returned for Level 2.
Duration of 7200 seconds scenario

If the Level is 4 and the duration is 7200 seconds, 1121266800 (July 13, 2005, 8:00 A.M.) is
returned.
Using application commands with daylight saving time

In this topic:
Adding 1 hour to the start time scenario
Difference of 1 hour between start time and end time scenario
When daylight saving time starts, the transition day has only 23 hours.
When daylight saving time ends, the transition day has 25 hours. It includes two numerically
identical hours:
1:30 A.M. daylight saving time (occurs first)
1:30 A.M. standard time (occurs an hour later)
Hence, for one hour each year, time keeping must distinguish between repeated hours.
The dates that daylight saving time starts and ends change year by year and city by city. To
accommodate this fluctuation:
1. Convert all times to Greenwich mean time (GMT).
2. Calculate your elapsed time.
3. Use locale tables to convert the displayed times to local time.
Page 1506 of 4705
Home
The Java Timezone class contains the locale-specific information for these calculations.
In the following examples, assume that the AR System server is in Pacific Standard Time (US and
Canada, GMT -8:00) and daylight saving time occurs on March 11, 2007 2:00:00 A.M.
"Work" defines the available time window at Level 1 on March 11, 2007 from 12:00 A.M. to 5:00
A.M. on the Business Time Segment form.
Adding 1 hour to the start time scenario

$PROCESS$ Application-Bus-Time2-Add "3/11/2007 1:00:00 AM" "1" "3" "Work"
This adds 1 hour to the start time and returns 1173607200 (that is, Sunday, March 11 03:00:00 A.M
. PDT 2007).
Difference of 1 hour between start time and end time scenario

$PROCESS$ Application-Bus-Time2-Diff "3/11/2007 1:00:00 AM" "3/11/2007 3:
00:00 AM" "Work"
The return value is 3600 seconds (that is, 1 hour).

In this topic:
Application-Bus-Time2-Assoc-Add
Application-Bus-Time2-Assoc-Diff
Application-Bus-Time2-Assoc-Subtract
Application-Bus-Time2-Assoc-Get-Next-Window
Application-Bus-Time2-Assoc-Get-Free-Window
If the Business Segment-Entity Association form contains entries for time segments, you can use
the following commands in place of the Application commands described in the previous section.
The following commands contain EntityID parameters so that you do not need to query the
Business Segment-Entity Association form and call the previous Application commands.
Application-Bus-Time2-Assoc-Add
Use the following syntax for the Application-Bus-Time2-Assoc-Add calculation:
Application-Bus-Time2-Assoc-Add "<startTime>" ["<amount>" ["<amountUnits>
" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "
EntityID1" "EntityID2"... ]]]]
Page 1507 of 4705
Home
Application-Bus-Time2-Assoc-Diff
Use the following syntax for the Application-Bus-Time2-Assoc-Diff calculation:
Application-Bus-Time2-Assoc-Diff "<startTime>" "<endTime>" ["<
businessTimeSegmentName1>" "<businessTimeSegmentName2>" . . . [-e "
EntityID1" "EntityID2"... ]]
Application-Bus-Time2-Assoc-Subtract
Use the following syntax for the Application-Bus-Time2-Assoc-Subtract calculation:
Application-Bus-Time2-Assoc-Subtract "<startTime>" ["<amount>" ["<
amountUnits>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>"
. . . [-e "EntityID1" "EntityID2"... ]]]]
Application-Bus-Time2-Assoc-Get-Next-Window
Use the following syntax for the Application-Bus-Time2-Assoc-Get-Next-Window
calculation:
Application-Bus-Time2-Assoc-Get-Next-Window "<startTimeRange>" "<
endTimeRange>" "<duration>" "<windowFlag>" ["<businessTimeSegmentName1>"
" <businessTimeSegmentName2>" . . . [-e "EntityID1" "EntityID2" . . . ]]
For more information, see the BMC Knowledge Base article KA311064.
Application-Bus-Time2-Assoc-Get-Free-Window
Use the following syntax for the Application-Bus-Time2-Assoc-Get-Free-Window
calculation:
Application-Bus-Time2-Assoc--Get-Free-Window "<startTimeRange>" "<
endTimeRange>" "<level>" "<duration>" "<earliestStartTime>" "<
latestEndTime>" ["<businessTimeSegmentName1>" "<businessTimeSegmentName2>
" . . . [-e "EntityID1" "EntityID2" . . . ]]
Recurrence is defined by a set of fields on the Business Time Segment form. The fields the range
from 2300 to 2341 and contain recurrence patterns. Field 2300 contains the Recurrence Definition
Name used in the Application-Get-Next-Recurrence-Time command. For more
information about how these fields are used, see Scheduling a time segment.
Fields 2300 to 2341 can be defined on any form, and the
Application-Get-Next-Recurrence-Time command is provided to get the next time. (You
can optionally create a custom form with field IDs in the range of 2300 to 2341 to contain
recurrence patterns, and specify that custom form in the
Application-Get-Next-Recurrence-Time application command.) For all the recurrence time
calculations, ICU library functions are used.
Page 1508 of 4705
Home
The Application-Get-Next-Recurrence-Time command performs a recurrence date

calculation by starting with the day after the start time and finding recurrence dates based on the
specified recurrence definition name. The return value is a semicolon-separated list of dates (in
seconds since epoch time).
The recurrence pattern specifies a day or days. The
Application-Get-Next-Recurrence-Time takes the day or days specified by the recurrence
pattern, and adds the starting time portion of the starting date and time to it to return a list of dates (
in seconds since epoch time). For example, if a recurrence is defined as "Tuesday of every week"
and the start time is 12/1/08 at 11:00 A.M. (a Monday), the value for 12/2/08 at 11:00 A.M. is
returned. However, if the start time is 12/2/08 at 11:00 A.M. (a Tuesday), the value for 12/9/08 at 11
:00 A.M. is returned.
The command syntax is as follows:
<formName> <startTime> <recurrenceDefinitionName>
The options for these recurrence time calculations are as follows:

<formName> --Form that contains the recurrence fields, such as the Business Time
Segment form.
<startTime> --The starting date and time from which the next recurring day is to be
calculated.
<recurrenceDefinitionName> --Identifier indicating the entry in the form (specified by <
formName>) that contains the recurrence pattern to use for this calculation. This is the name
in field 2300.
Following is an example of the command with $PROCESS$:
$PROCESS$ Application-Get-Next-Recurrence-Time "Business Time Segment" "4
/14/04 10:30:00 AM" "weekly"
weekly is an entry in the form that contains the recurrence fields, such as the Business Time
Segment form. The weekly entry is defined as Wednesday and Friday, every 3 weeks.
The return value is 1082136600, which corresponds to 4/16/04 10:30:00 AM . Calling
Application-Get-Next-Recurrence-Time again with a start time of 04/16/04 10:30 AM
returns 1083778200;1083951000, corresponding to 5/5/04 10:30:00 AM and 5/7/04 10:
30:00 AM.
Using the old Business Time forms

This section describes the following forms:
Page 1509 of 4705
Home
Note
BMC recommends not using the Business Time Workdays and Business Time Holidays
forms. These forms remain for backward compatibility.
Important
If you use Approval Server, do not stop using these forms. The AP:Process Definition
form references them. For more information, see the Setting up the approval process
section.

Scheduling workdays
Scheduling holidays
Tips for entering dates and times for holidays
Adjusting the time across midnight for holidays
Defining business hours using offset hours
Scheduling workdays
The Business Time Workdays form stores the day-to-day availability of each of your groups and
individuals, and a record of your company or location's business hours.
Business time in BMC Remedy AR System is calculated on the AR System server where the start
and end times on any given day must be in the range of 0-24 hours. Any business time outside this
range is considered invalid.
To define business hours

1. Open the Business Time Workdays form.
On the General tab, you can specify a unique identifier for a workday definition and the list
of open and close times for workdays you are defining.
Business Time Workdays form
Page 1510 of 4705
Home
2. In the Name field, enter a unique identifier.

Use this identifier to reference this schedule in all business hours calculations.
3. In the Submitter field, enter the name of the user who submitted the first version of this
schedule.
4. Use the Change History field to track structural or administrative changes to the definition.
5. In the Help Text field, enter the purpose of the schedule.
6. (Optional) In the Offset Hours field, enter the number of hours that you want to offset from
the time on the server.
Use the Offset Hours field to adjust a client business time to a server business time. An
example of a special case is a valid business time on the client several time zones away
from the server. The time on the client becomes invalid on the server if it crosses midnight
after the time zone adjustment.
For more information, see Using offset hours in Business Time 2.0 .
7. Click the Time Schedules tab.
Business Time Workdays form, Time Schedules tab
8. Enter the appropriate hours in the time blocks.

BMC Remedy AR System enables you to define up to four multiple non-overlapping time
blocks for hours of operation in a single 24-hour period.
To span midnight, show the day as split between two days (for example, a shift spanning
Tuesday and Wednesday). For example, End 4 on Tuesday has a time of 11:59:59 P.M.,
and Start 1 on Wednesday has a time of 12:00:00 A.M.
Time segments must be ascending and non-overlapping within a day. The following figure
shows an End time one second before the Start of the next time segment. (If Offset Hours is
used, the time segments must be non-overlapping before the offset hours are applied.)
Page 1511 of 4705
Home
Note
Create separate schedules for Daylight Saving Time as needed based on locale
and conventions for that locale.
9. Save the form.
Entering business hours with a one-hour gap

Business hours with a one-hour gap can occur when a one-hour lunch break is scheduled in the
work day. Use the Time Schedule Start and End times to specify that the business is open from 9:
00:00 A.M. to 12:00:00 P.M. and from 1:00:00 P.M. to 5:00:00 P.M., indicating a one-hour closed
time. Enter the information as shown in the following figure.
Business hours with one hour gap
Scheduling holidays
Use the Business Time Holidays form to define all scheduled holidays and other non-working days.
A holiday can be a full day or a few hours. Because of shift work, holidays might span over midnight
.
To set holiday times

1. Open the Business Time Holidays form.
2. Click the Holiday Definition tab.
Business Time Holidays form
3. In the Schedule Name field, enter the unique identifier for this holiday schedule.
Use this identifier to reference this schedule in all business hours calculations.
Important
Page 1512 of 4705
3.
Home
Enter the same name that you entered in the Name field of the Business Time
Workdays.
4. In the Holidays field, list the holidays that make up the holiday schedule.
Enter holiday time as:
date,startTime,endTime
For example:
07/4/09,9:00:00 A.M.,5:00:00 P.M.
is a holiday that starts at 9:00:00 A.M. on 7/4/09 and ends at 5:00:00 P.M. on the same day.
To separate the dates, press Enter or insert semicolons between the dates. The number of
dates that can be specified in this list is unlimited.
The holiday entry cannot span across midnight, and the Start time must be less than End
time. Holiday time uses the offset hours from the Workday schedule.
Only short date/time format is supported in the Business Time Holidays form. Long date
formats (such as January 1, 2005) are not supported.
The dates are interpreted on the server and follow the server's formatting rules. If clients are
configured for other date formats and the dates entered in the Business Time Holidays form
are entered in a client format incompatible with the server format, they are not correctly
interpreted as holidays, or they might be interpreted as a different day than was planned.
Note
The ARDATE format is not supported in Business Time Holidays form.
5. Click the Administrative Information tab.

The Holiday ID field contains the AR System ID for this schedule. The Change History field
is used to track structural or administrative changes to the schedule.
6. In the Help Text field, enter the purpose of the schedule.
7. Save the form.
Tips for entering dates and times for holidays

The following sections offer tips to help you properly enter dates and times into the Business Time
Holidays form.
Entering dates for an international server

When the server resides internationally, it recognizes the short date format of the server. For
example, the German Business Time Holiday value would be entered <dd.mm.yy>, which
matches the date convention of the locale.
Page 1513 of 4705
Home
Entering a holiday with no start time

To indicate a holiday without listing a start time, use the following format:
<date>,,
<endTime>
For example:
7/4/04,,5:00:00 P.M.
In this case, the start time defaults to 12:00:00 A.M.
Entering a holiday with no end time

To indicate a holiday without listing an end time use the following format:
<date>,
<startTime>
For example:
7/26/04, 2:00:00 P.M.
In this case, the end time defaults to 11:59:59 P.M.
Entering a holiday with no start time and no end time

To indicate a holiday that lasts the entire 24-hour day, use the following format:
<date>
For example:
7/26/04
In this case, the start time defaults to 12:00:00 A.M. and end time defaults to 11:59:59 P.M.
Adjusting the time across midnight for holidays

The implementation of business time calculations requires that Start Time be earlier than End Time.
However, when a holiday schedule crosses midnight, such as when Start Time is 10:00:00 P.M.
and End Time is 6:00:00 A.M., you must adjust the holiday schedule:
Page 1514 of 4705
Home
To adjust using Holidays time, enter the start time as one day and enter the end time on the
next day. It would look like:
12/25/04,10:00:00 P.M.,11:59:59 P.M.;

12/26/04,12:00:00 A.M.,6:00:00 A.M.
To adjust using Offset Hours, take your original Start/End time minus the value from Offset
Hours in the Business Time Workdays form to get the adjusted time. You can use either a
positive offset (which moves the times earlier) or a negative offset (which moves the times
later). The offset does not have to be unique. You can choose any value as long as the
adjusted times fall into the 0- to 24-hour range. For example, if a holiday starts at 10:00:00
P.M. on 12/25/04 and ends at 6:00:00 A.M. on 12/26/04, you can supply an offset of three
hours to adjust the holiday time to start on 12/26/04 at 1:00:00 A.M. and end at 9:00:00 A.M.
This adjusted time is entered into the Holidays field following the format:
12/26/04,1:00:00
A.M.,9:00:00
A.M.
Note
The offset hours is specified in Business Time Workdays as part of a workday schedule.
Defining business hours using offset hours

The use of the Offset Hours field as described in this section is not recommended in Business
Time 2.0.
Business time is calculated on the server and requires that start and end times be in the range of 024 hours. An invalid business time is adjusted using the Offset Hours field on the Business Time
Workdays form. An example could be a valid business time on a client several time zones away
from the server. The time on the client might become invalid on the server if it crosses midnight
after the time-zone adjustment. The Offset Hours field is used in this situation.
Setting a positive offset moves the time later, a negative offset moves it earlier. Unique offset times
are not required. Any adjusted range defined with the offset hours is valid in the AR System server
as long as it falls into a single 0-24 hour range . For tracking purposes, use the Scheduling Diary
field to document how the offset adjustment is made.
The Offset Hours field are useful in the following situations:
Business hours that span over midnight.
For example, a business's Open Time is 10:00:00 P.M. and its Close Time is 6:00:00 A.M.
Because the AR System server does not allow Business Time to span midnight, enter this
Page 1515 of 4705
Home
workday as 1:00:00 A.M. to 9:00:00 A.M. (0-24 hour range) with an offset of -3.
On the other hand, you could have specified a positive offset of 7 hours to adjust your
business hours to a new Open Time of 3:00:00 P.M. and a new Close Time of 11:00:00 P.M.
Business hours that span midnight with different time zones.
In this circumstance, you have to derive the offset hour by considering both factors. The goal
is to specify the offset hours to adjust the Open and Close Time to 0-24 hour range on the
server.
For example, the server is 6 hours behind the client in a different time zones. On the client,
the schedule is 2:00:00 A.M. and 10:00:00 A.M. Specify a positive offset number (6)
because the server is behind the client, to adjust 2:00:00 A.M. and 10:00:00 A.M. on the
client to be 8:00:00 P.M. and 4:00:00 A.M. on the server. Then, to adjust to the 24-hour
period, use a number (such as 5) to adjust the calculation, For example: 8 P.M. - 5 = 3 P.M.,
and 4 A.M. - 5 = 11 P.M. Considering both together, the final calculated offset is 6 + 5 = 11.

The following commands in this topic were used in the old Business Time scheme.
Application-Bus-Time-Add
Application-Bus-Time-Diff
Application-Bus-Time-Subtract
If you use the old Business Time forms, you can use these commands, but they do not work with
Business Time 2.0.
The parameters for these commands are defined in Business Time command parameters.
Application-Bus-Time-Add
The Application-Bus-Time-Add command adds the requested offset to the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time into
the future.
Use the following syntax for the Application-Bus-Time-Add calculation:
Application-Bus-Time-Add "<startTime>" ["<amount>" ["<amountUnits>" ["<
holidayScheduleName>" [HTMLUATarsadministering1030:"<workdayScheduleName>
"]]]]
The <startTime> parameter is required in this command. This parameter must be a value such
as a field reference ($<fieldName>$). Other fields are optional and use the default value if not
provided. You can specify multiple business activity names.
For example, add one day by using the following calculation:
$PROCESS$ Application-Bus-Time-Add "$<fieldName>$" "<amount>" "<
amountUnits>"
Page 1516 of 4705
Home
This adds one day to the value in $<fieldName>$. Show $<fieldName>$ as <startTime>.
Set the <amount> to 1 and set the <amountUnits> to 4 (representing days), thus adding one day
into the calculation. The final syntax looks like:
$PROCESS$ Application-Bus-Time-Add "$8/26/2004$" "1" "4"
Application-Bus-Time-Diff
The Application-Bus-Time-Diff command computes the difference between the start time
and the end time. The return is an integer representing the difference in seconds. Use this
command to compare two different times (start time and end time) to get the actual business time.
Use the following syntax for the Application-Bus-Time-Diff calculation:
Application-Bus-Time-Diff "<startTime>" "<endTime>" ["<
holidayScheduleName>" [HTMLUATarsadministering1030:"<workdayScheduleName>
"]]
The <startTime> and <endTime> parameters are required in this command. Other fields are
optional and default if not provided. You can specify multiple business activity names.
Application-Bus-Time-Subtract
The Application-Bus-Time-Subtract subtracts the requested offset from the start time and
returns a timestamp representing the time calculated. Use this command to recalculate time in the
past.
Use the following syntax for the Application-Bus-Time-Subtract calculation:
Application-Bus-Time-Subtract "<startTime>" ["<amount>" ["<amountUnits>"
["<holidayScheduleName>" [HTMLUATarsadministering1030:"<
workdayScheduleName>"]]]]
The <startTime> parameter is required in this command. Other fields are optional and use the
default value if not provided. You can specify multiple business activity names.
Migrating Workdays and Holidays to the Business Time

Segment form
This topic provides tips you can use when migrating your Business Time Workdays and Holidays to
the Business Time Segment form.
In this topic:
Migrating Workdays considerations
Migrating Holidays considerations
Page 1517 of 4705
Home
Migrating Workdays considerations

All workdays become a Weekly Recurrence time segment.
Time segments require a Start Date and End Date that define the recurrence range. Since
Workdays do not have a range, make sure that the Start Date and End Date fields
represent a large range.
Workdays can have up to 4 shifts. Each shift is a time segment, which can have the same ID
as another time segment.
Set the Level to 1 for all time segments.
Select the End of Day check box to indicate the end of the day instead of 11:59:59 P.M.
The ID field on the Business Time Segment form is the same as the Tag field on the
Business Time Workdays form.
If the Workday form has an offset and if multiple time segments correspond to this workday
entry, apply the offset to only one-time segment.
Migrating Holidays considerations

Use the Specific Dates tab in the Business Time Segment form to specify a list of dates (with
the same time range). Make sure that the Start Date and End Date are in that list of dates.
Set the Level to 2.
If holidays are defined with different start and end times, create different time segments.
They can all have the same IDs.
Select the End of Day check box to indicate the end of the day instead of 11:59:59 P.M.
The ID field on the Business Time Segment form is the same as the Tag field on the
Business Time Holidays form.

The alert system engages when a filter or escalation Notify action sends a notification through the
alert mechanism. This section describes how alerts work in BMC Remedy AR System .
For information about using the Notify action to send an alert and other methods of notification
delivery, see Notify action.
Alert system architecture

The alert system consists of the following components:
The BMC Remedy AR System server
The Alert Events form
The Alert List form and Alert List field type
The AR System Alert User Registration form
Plug-in server alert capability
An installed plug-in to send alerts via Web services
Page 1518 of 4705
Home
The BMC Remedy AR System server uses the installed alert forms and related workflow to
maintain a list of registered alert users, to store pending alerts, and to display each user's alerts in
an alert list.
Users can view their alerts in the alert list in a browser, or they can receive alerts outside of BMC
Remedy AR System, for example, over a social networking service.
Application developers can enable an application to notify users about alerts by using the Notify
workflow action with the alert delivery mechanism. By registering users for the appropriate alert
types, your application can send alerts to a plug-in. Through the plug-in server, alerts can be
delivered to various destinations outside of BMC Remedy AR System, such as a web service or a
social networking service.
Alert Events form introduction

If you choose Alert as the notification method when creating a Notify action for filter or escalation,
alerts are recorded as new requests in the Alert Events form when the workflow executes.
Alert events form
The Alert Events form is installed with BMC Remedy AR System. This form contains the alert
message, identification information about the source request, the name of the user to whom the
alert is directed, and information about the alert status.
The Read field is set to "X" when the user opens the alert. The Sent Successfully field is an
indication of whether the Alert was sent successfully. If a user is registered for more than one alert
destination, this field is set if the alert is delivered successfully to any one of the destinations. Use
of this field is optional and is controlled by the Update Sent Flag field in the AR System Alert User
Registration form. See Registering users for alerts.
You cannot delete the Alert Events form and its original fields, but you can add fields and workflow
to the form.
Page 1519 of 4705
Home
Viewing alerts
Users do not interact directly with the Alert Events form. Instead, users view their alerts by opening
a form that contains an alert list field in a browser.
The alert list field type is a special type of table field that automatically retrieves records for the
current user from the Alert Events form. Any form can contain an alert list field. The Alert List form
installed with BMC Remedy AR System contains only an alert list field and is the default form for
displaying alerts.
Alert list fields display the user's records from the Alert Events form. When a user clicks on an alert
in the list, BMC Remedy AR System opens the source request in the form that generated the alert.
To support such drill-down from the alert list table field, the form originating the alert must contain a
results list table field.
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.
The alert list displays alerts from multiple servers. For web clients, the alert list queries servers
configured in the mid tier. For more information, see Using the alert list in a browser .
If a web user has access to multiple forms that have alert list fields, BMC Remedy AR System uses
the first form that it finds that contains an Alert List. Therefore, if the user has permission to multiple
forms containing an alert list, you cannot always predict which form will be used. BMC recommends
making sure that each group can access only one alert list form. This option enables you to create
forms with different workflow and different fields for different groups.
Deleting unread alerts

The CleanupAlertEvents escalation is automatically created with the Alert Events form. If enabled,
this escalation deletes all unread alerts older than 30 days.
Initially, the CleanupAlertEvents escalation is disabled. You can enable it and customize it
according to your needs.
Registering users for alerts

The AR System Alert User Registration form is installed with BMC Remedy AR System. Entries in
this form identify each alert user and the method or methods by which they receive alerts. Users
can have multiple entries in this form, as long as each entry represents a different alert destination.
Page 1520 of 4705
Home
The AR System Alert User Registration form

The Alert User Registration form contains all the information maintained by the server in earlier
releases, as well as new fields to support sending alerts through the web services plug-in or any
other alert plug-in.
Note
The Alert User Registration form replaces the internal alert_user table of alert users that
the AR System server maintained in earlier releases. An upgrade routine transfers the
existing information from the server table to this form at the first server start up after
upgrading. After the data has been transferred to the form, the server table is no longer
used.
The alert method is determined by the value in the Plugin Name field. When the Web Services
Plugin Name is specified, you provide the end point URL for the Web service to which the alert will
be sent in the Plugin Values field. You must define the Web service using the WSDL installed with
BMC Remedy AR System. In this case, BMC Remedy AR System sends alerts to the plug-in server
for processing by a specified plug-in. For information about sending alerts by Web services, see
Using Web services with alerts.
You can configure other applications to register and deregister alert users by using C or Java API
calls, by using a Web service, or by creating and deleting entries manually. (To deregister users
through a Web service, you must use one of the deregister operations described in Registering and
deregistering users by web service.)
The following table describes the fields in the Registration tab of the Alert User Registration form:
Registration tab fields
Field name
Description
Page 1521 of 4705
Home
Registered
User
The AR System login name of the user being registered for alerts.
Registered
Time
The time that the user registered. This is the Modified Date core field and represents the time when the entry was
created or modified. BMC Remedy AR System uses this field to determine if the user registration has expired and
to identify unsent alerts.
Expiration
Time (secs
)
The time, in seconds, after which the user's alert registration should expire. If the value is zero, there is no time limit
. An escalation runs every 10 minutes to delete expired entries. If an entry has expired but the escalation has not
yet run, the user continues to receive alerts.
Short
Description
Used for optional supporting information. If you do not need to use this field, leave the default value N/A in the field.
Plugin
Name
Defines the way alerts are sent for this user registration. The drop-down field menu takes its entries from the AR
System Alert Delivery Registration form. Two methods are installed with BMC Remedy AR System:
Alert API Send alerts to a browser via the AR System Alert API.
Web Service Send alerts via web service, such as the AR System Alert Web services plug-in,
ARSYS.ALRT.WEBSERVICE.
To use the Web Service plug-in, you must create a web service using the installed AR System Alert Web service
WSDL. See Using Web services with alerts.
Defines the destination to which alerts are sent for this user registration.
Plugin
Values
If the Plugin Name is Alert API, this field contains the client and server IP addresses and the client port
number, formatted as semicolon-separated name-value pairs.
If the Plugin Name is Web Service, enter the end point URL of the Web Service you created using the Alert
Notification WSDL.
Encrypt
Plugin
Values
Used to store a value that must be encrypted. For, example if a plugin requires a password, store the password in
this field.
ReRegister
A display-only field that allows the entry to be modified with a new expiration time. This field is only used when
resetting the Expiration Time in a browser. If the Expiration Time must be set back to its previous value, then the
browser will not send the data to the BMC Remedy AR System server. The ReRegister check box allows the data
to get dirty so that the browser can send the data to the BMC Remedy AR System server.
For Web services, you use the Reregister method to reset the Registration Time. See Using Web services with
alerts.
Update
An optional status field that controls whether or not to update the Sent Successfully field on the Alert Events form
Sent Flag
when an alert is successfully delivered. Updating the Sent Successfully field for all Alert Events entries can have a
performance impact on a busy server, so this field allows you to manage performance by controlling whether the
Sent Successfully field is used.
Using the alert list in a browser

Browser users can view the alert list by opening a form that contains an alert list field, such as the
Alert List form or any form that you create, as long as it contains an alert list field.
In this topic:
To create and publish a web-based alert list
To enable a preference server for the Web
To configure user preference values for alerts on the Web
Page 1522 of 4705
Home
To create and publish a web-based alert list

1. Create a regular form on one server in your BMC Remedy AR System installation where the
mid tier is also installed.
2. Add an alert list field to the form.
3. Make this form accessible in a browser through a URL .
To enable a preference server for the Web

1. Make sure that one server in your BMC Remedy AR System installation is defined as a
preference server.
For more information about preferences, see Setting user preferences.
2. Under General Settings in the Mid Tier Configuration Tool, enter the name of the preference
server used by alert system users.
To configure user preference values for alerts on the Web

1. Open the AR System User Preference form in a browser.
2. For each user, set the following preferences.
These preferences are available on the Web view or on the Web tab of the Default
Administrator view of this form. See Preference forms for centralized preferences.
a. In the Alert Servers field, enter the name of each server (separated by commas)
from which users receive alerts.
Alerts from these servers are visible in the Web-based alert list. Users do not need to
be logged in to these servers to receive alerts or to display the originating request.
b. In the Refresh Interval field, enter the number of minutes between each automatic
refresh of the alert list.
A setting of 0 indicates no refresh interval.
Each server specified under Alert Servers is queried for new alerts, and these alerts
are displayed in the Web-based alert list.
Using Web services with alerts

BMC Remedy AR System can send alerts to the plug-in server for users registered with the Web
Services Plugin Name in the AR System Alert User Registration form. You can configure alerts to
go to the AR System Alert Web Services plug-in installed with BMC Remedy AR System, or to
another plug-in that you create.
Note
To send alerts via Web service, the AR System Web services plug-in
ARSYS.ARF.WEBSERVICE must be installed. See Setting up the environment for web
services.
Page 1523 of 4705
Home
The AR System Alert Web Services plug-in ( ARSYS.ALRT.WEBSERVICE) converts the alert
information, including the alert text, recipient, and alert destination, to an XML document. It then
passes the alert request to the Web Services plug-in, which must also be installed and running. The
Web Services plug-in sends the alert to the destination Web service.
You can also use Web services to register users in the AR System Alert Users Registration form.
To receive alerts via Web services, create a Web service that uses the Alert Notification .wsdl file (
alertNotification.wsdl) installed with BMC Remedy AR System. This .wsdl is installed in the <
ARSystemInstallDir>/pluginsvr directory.
For more information about using Web services with BMC Remedy AR System, see Publishing the
BMC Remedy AR System functionality as a web service .
To register a user to receive alerts through the AR System Alert Web Services
plug-in
1. Create a Web service that uses the alertNotification.wsdl.
2. Create an entry for the user in the AR System Alert User Registration form.
a. In the Registered User field, enter the user's AR System login ID.
b. In the Plugin Name field, select Web Service.
c. In the Plugin Values field, enter the End Point URL of the Web service that uses the
alertNotification.wsdl.
Registering and deregistering users by web service

The Alert Web Services plug-in contains the following methods and input parameters to allow
registration, re-registration, and de-registration of alert users via Web Services:
DeRegister --Deletes an entry that has the Web Service Plugin Type from the AR System
Alert User Registration form by using the Registered User name. The minimum values
required are Registered_User and DeRegister. DeRegister must be set to Yes. If the
remaining values are provided, they are used to search for an entry with those values.
Example:
<urn:Registered_User>?</urn:Registered_User>

<urn:Plugin_Name>ARSYS.ALRT.WEBSERVICE</urn:Plugin_Name>

<urn:Plugin_Values>?</urn:Plugin_Values>

<urn:DeRegister>Yes</urn:DeRegister>
Page 1524 of 4705
Home
DeRegisterOnRequestID --Deletes an entry that has the Web Service Plugin Type from
the AR System Alert User Registration form by using the Request ID of the entry. The
DeRegister element must be set to Yes.
Example:

<urn:DeRegister>Yes</urn:DeRegister>
<urn:Request_ID>?</urn:Request_ID>
GetByRequestID --Retrieves an entry from the AR System Alert User Registration form.
Example:
GetListByQual --Retrieves entries from the AR System Alert User Registration form by
using the qualification provided.
Example:
<urn:Qualification>?</urn:Qualification>
<urn:startRecord>?</urn:startRecord>
<urn:maxLimit>?</urn:maxLimit>
In this method, the default qualification is 'Registered User' = $USER$. The default
qualification is used if no Qualification element is present or if the Qualification
element is empty (for example, <urn:Qualification></urn:Qualification> ).
To see all the registered users, enter the qualification in the format <urn:Qualification>
'Registered User' LIKE "%%" </urn:Qualification> .
Note
You must be a member of the Administrator group to see all the registered users. If
a non-administrator uses this qualification, they will see only those records for
which they have permission.
Register --Creates an entry in the AR System Alert User Registration form.

Example:
<urn:Short_Description>?</urn:Short_Description>

Page 1525 of 4705
Home


<urn:Enc_Plugin_Values>?</urn:Enc_Plugin_Values>

<urn:Expiration_Time__secs_>0</urn:Expiration_Time__secs_>

<urn:Update_Sent_flag>?</urn:Update_Sent_flag>
ReRegister --Resets the value in the Registration Time field. The minimum value
required to be sent is the value in Expiration Time (secs). The value of this field can be the
same as what it was originally to reset the registration rime. If required, the remaining values
can also be sent to modify them along with resetting the registration time.
Example:


<urn:Short_Description>N/A</urn:Short_Description>



<urn:Enc_Plugin_Values>?</urn:Enc_Plugin_Values>
<urn:Expiration_Time__secs_>?</urn:Expiration_Time__secs_>

<urn:Update_Sent_flag>?</urn:Update_Sent_flag>
Assigning requests with the Assignment Engine

The Assignment Engine is installed with BMC Remedy AR System. By following a simple process,
you can automatically assign users to specific requests.
The Assignment Engine uses processes instead of workflow to automatically assign requests to
individuals. You can install this feature by using the BMC Remedy AR System suite installer.
The Assignment Engine is an AR System interface that processes the assignment of requests. It is
a rule-based application. The Assignment Engine administrator defines the processes and rules. A
process can have multiple rules.
An entry in the Application Pending form provides the process name and request ID of the
application request. Based on this input, the Assignment Engine executes the associated rules
against a form where the assignee information is stored. The correct assignee is located and is set
in a preconfigured field on the request form.
Page 1526 of 4705
Home
If multiple assignees are available, the predefined assignment methods are used to identify an
assignee for the request. See Integrating the BMC Remedy Assignment Engine into an application .
Auto-assignment methods
Assignment process flow
Assignment Engine Administration Console introduction
Configuring a private queue for the Assignment Engine
Assignment Engine forms
For information about configuring assignments using BMC Remedy ITSM, see Configuring
assignments.
Auto-assignment methods
The assignment method determines who is assigned to an issue when more than one person
matches the qualification. In such cases, the following assignment methods can be specified in an
assignment rule to automatically assign the issue:
Round Robin Assigns the issue to the person who has gone the longest since receiving
an assignment.
For example, if person A was last assigned an issue at 9:00 A.M., and person B was
assigned an issue at 10:30 A.M., person A is selected.
Load Balance by Number Assigns the issue to the person who has the fewest number
of issue assignments.
For example, if person A is assigned 2 issues and person B is assigned 3 issues, person A
is selected.
Load Balance by Capacity Assigns the issue to the person who has the largest unused
capacity.
For example, if person A has a capacity rating of 10 and is assigned 5 issues, then the
unused capacity is 5. Similarly, if person B has a capacity rating of 20 and is assigned 8
issues, then the unused capacity is 12. In this case, person B is selected because of the
higher unused capacity.
Note
For the Load Balance by Number and Load Balance by Capacity assignment methods,
it is possible that two or more people qualify for an issue. In such cases, the assignment
does not happen in alphabetical or random order, but in the sequence in which the
records are fetched. This sequence is determined by the sort order on the assignee form,
if specified; else, in the order in which the records are created.
Page 1527 of 4705
Home
Assignment process flow

The assignment process flow is as follows:
1. The BMC Remedy AR System client sends a request along with an application
command.This command tells the Assignment Engine which process should be run to
perform auto assignment.
2. Assignment Engine starts the process.
3. If a rule returns a set of assignees, Assignment Engine skips the execution of the remaining
rules defined in the process, and starts applying the assignment method. However, if a rule
does not return a set of assignees, Assignment Engine runs the next rule in the process.
4. Using the assignment method, Assignment Engine identifies a single assignee and the
request is assigned.
5. After the request is assigned, the assignee record is updated, and the assignment process is
successful. This record consists of the last assigned request time and the number of tickets
currently assigned to the assignee.
6. If all the rules fail to return a set of assignees, the assignment process fails.
Assignment Engine Administration Console introduction

To set up auto-assignment processes, forms, and rules, you use the Assignment Engine
Administration Console.
The Assignment Engine Administration Console has these tabs:
Processes Lists the processes that the Assignment Engine can use. Each process has a
Process Name.
Note
BMC recommends that you use unique process names.
Each process consists of a request form and a set of sequential rules, all of which you enter
using the procedures described in the following sections.
Forms Shows all forms registered with the Assignment Engine. To list forms used by a
specific process, select the process name from the Show For Process list. The Forms tab
also has a Related Processes table that shows the process for the form selected in the table.
If the form is used in more than one process, the Related Processes table lists all those
processes.
Rules Shows all the rules in the Assignment Engine. To list rules used by a specific
process, select the process name from the Show For Process list. The Rules tab also has a
Related Processes table that shows the process for the rule selected in the table. If the rule
is used in more than one process, the Related Processes table lists all those processes.
Page 1528 of 4705
Home
Configuring a private queue for the Assignment Engine

To configure a private queue, add the following entries in the ar.cfg file (or configure the following
properties in ar.cfg file):
Property
Description
Private-RPC-Socket
Configures an RPC socket on the given port number.
Private-RPC-Socket: <portNumber> <minThreads> <maxThreads>
For example, Private-RPC-Socket:390633 1 2 This property configures a private socket on an empty

port, with the minimum and maximum threads.
AE-RPC-Socket
Establishes a private queue between the Assignment Engine and the AR System server, thus
improving the Assignment Engine performance.
AE-RPC-Socket: <portNumber>
For example, AE-RPC-Socket:390633.
Note
After this connection is established, all communication between the AR System server and
Assignment Engine will proceed through this channel.
Note
After you configure these properties, you must restart the server for the changes to take
effect.

The following table lists the forms that are installed when you install BMC Remedy Assignment
Engine.

Form name in BMC Remedy Developer
Studio
Description
ASE:Administration
Allows you to configure processes, rules, and forms for Assignment Engine.
ASE:Admin-ServerSettings
Allows you to configure logging for Assignment Engine.
ASE:AssignAssoc_AssignForm
This form is a join form of ASE:Assignment Association and ASE: Form

Information.
Page 1529 of 4705
Home
Form name in BMC Remedy Developer

Studio
Description
Note
Assignment Engine uses this join form for internal processing.
ASE:AssignAssoc_AssignRules
This form is a join form of ASE:Assignment Association and ASE: Assignment

Rules.
Note
ASE:Assignment Association
Stores the process-to-form and process-to-rule mapping information.
ASE:Assignment Process
Stores information about the processes that are configured with Assignment
Engine.
ASE:Assignment Rules
Stores information about the rules that are configured with Assignment Engine.
ASE:AssignmentDetail
This form is a join form of ASE:Assignment Association and ASE:

ProcessRuleForm.
Note
ASE:Config
A back-end form that stores information related to logging and configuration.
ASE:DialogYesNo
A dialog box; not listed in the Object List.
ASE:Form Information
Stores information about rules configured with Assignment Engine.
ASE:LocalizedString_MenuItems
A menu; not listed in the Object List.
ASE:ProcessRuleForm
Stores the process-to-rule mapping.
ASE:SearchRulesDialog
A dialog box; not listed in the Object List.
To set up assignments, you use only a few of these forms. See Integrating the Assignment Engine
into an application.

Full text search (FTS) is installed by default with the BMC Remedy AR System server. This section
discusses the capabilities, performance, and administration of the FTS feature.
Setting up FTS to search across multiple forms
Re-indexing considerations
Page 1530 of 4705
Home
Defining a field for FTS

How FTS indexing works
Performing searches with FTS
FTS index migration
Enabling FTS high availability
FTS is typically much faster than using the native database searching functionality when searching
in long text fields. It is also the only method available in BMC Remedy AR System for searching
text within attached documents.
With FTS, you can use your knowledge base. You can access your company's history of solving
problems, which is sometimes stored in long text fields or attachments. With the FTS option, you
can easily search long text fields to find solutions to related problems.
FTS solves many problems that users encounter when performing database searches, including:
Searching long text and attachment fields. The FTS option enables you to index character,
diary, and attachment fields for searching, and then matches entries from those fields
against the search criteria that you specify. Like database indexes, an FTS index can greatly
decrease the time required for a database search.
Improving search performance by searching large volumes of data.
Defining how the server interprets wildcards to customize search performance to your
specific needs.
Ranking search results according to their relevance to the search criteria. The more relevant
a search result is, the greater the weight. For more information, see Causing accrued and
weighted results with FTS.
To enable FTS
1. Install FTS with BMC Remedy AR System. (See the Installing section.)
2. Configure the server for FTS. (See Configuring full text search.)
3. Index fields for FTS. (See Defining a field for FTS.)
4. (Optional) Add a form search field to a form. (See Providing a shortcut for specifying
expanded FTS qualifications.)
5. (Optional) Set up forms for multiple-form FTS. (See Setting up FTS to search across multiple
forms.)
6. Re-index, as needed. (See Re-indexing considerations.)
Setting up FTS to search across multiple forms

You can set up full text search (FTS) to search across multiple forms.
Page 1531 of 4705
Home
To set up FTS to search across multiple forms

1. Configure each form so that it can be included in a multiple-form FTS (see Configuring forms
for multiple-form FTS).
2. Configure the server for multiple-form FTS (see Configuring the relevancy weight for fields in
a multiple-form FTS).
3. Update the AR System Multi-Form Search form (see Performing searches on multiple forms)
.
4. Create or modify a form and workflow that enable users to search across multiple forms (see
Creating a form and workflow to search across multiple forms ).
5. (Optional) Use date and time fields on your search form (see Using date and time fields on
your search form0.
Behavior of multiple-form FTS

If a user does not have permission to see a form or field, that form or field does not
participate in multiple-form FTS.
If a user does not have permission to the Request ID field (field ID 1), the entire row is
eliminated from the multiple-form FTS results.
If a user does not have permission to see any of the FTS-indexed fields on a form (based on
row-level security), the entire row is eliminated from the multiple-form FTS result. The reason
for this policy is because BMC Remedy AR System cannot determine the value of the field
that caused the entry to appear in the search results and whether the user has permission to
see that field.
If a user does not have permission to see the Full Text MFS Category Name field or Title
field, those fields are empty in the search results. The special handling of these fields is
because they are used as filters to narrow down the search results. (These fields do not
participate in multiple-form FTS.)
Configuring forms for multiple-form FTS

This topic explains how to set form properties to include a form in a multiple-form search.
To configure a form for a multiple-form FTS

2. Define the fields used in a full-text search. Any form with full-text indexed fields is eligible for
multiple-form searching by default.
See Defining a field for FTS.
3. Select the Definitions tab in the form editor.
4. Expand the Other Definitions panel and then the Full Text Search panel as shown in the
following image:
Full Text Search panel
Page 1532 of 4705
4.
Home
5. To exclude a form that has indexed fields from a multi-form search, select Exclude from
multi-form search.
6. (Optional) Enter field names in the following fields to set weighted relevancy fields:
Title Enter the field that represents the title for the form. This field's contents
appear in the search results. Text found in this field is given a higher relevancy weight
than other fields on the form (based on what you enter in Title Field Weight field on
the FTS tab of the AR System Administration: Server Information form). For example,
you might enter the Summary field as the Title field because users are more likely to
enter text that would be found in the Summary field.
Environment Enter the field that represents the environment for the form. This
field's contents appear in the search results. Text found in this field is given a higher
relevancy weight than other fields on the form (based on what you enter in the
Environment Field Weight field on the FTS tab of the AR System Administration:
Server Information form). For example, the form might contain a field that holds
environment information such as an Operating System field.
Keywords Enter the field that would hold the words that would be included in a
search. This field's contents appear in the search results. For example, a keyword
might be printer. If you might enter the Problem Area field in the Keywords field.
When a user enters printer in a search, if that word appears in the Problem Area field
, that search result would have a higher relevancy weight than other fields on the form
(based on what you entered in Keywords Field Weight field on the FTS tab of the
AR System Administration: Server Information form).
You can enter only fields that have been indexed for FTS, and you cannot enter the
same field in more than one of the weighted relevancy fields.
For more information about the Title Field Weight, Environment Field Weight, and
Keywords Field Weight fields, see FTS tab configuration options.
7. Select the scan times for updates to fields that have been indexed for FTS.
Scan times affect only join, vendor, and view forms. For more information, see Scheduling
scans for updates.
8. Save the form.
Page 1533 of 4705
Home
Configuring the relevancy weight for fields in a multiple-form FTS

You can set the relevancy of items in search results so that fields with higher relevancy appear
higher in the search results.
Use the FTS tab of the AR System Administration: Server Information form to configure the
relevancy weights for:
Title field weight
Environment field weight
Keyword field weight
See FTS tab configuration options for more information.
You can set a title field, environment, and keyword on each form. See Configuring forms for
multiple-form FTS.
Note
You must re-index data so that any changes to the relevancy weights are applied to the
existing data.
Performing searches on multiple forms

The AR System Multi-Form Search (MFS) form serves as an interface (or API) for BMC Remedy
AR System applications to be able to perform searches on multiple forms within the system. If you
search from a global search field, such as RKMs search, or the global searches supplied by ITSM
applications, MFS search is trigerred.
The tabs on the AR System Multi-Form Search form represent the logical flow for you to follow to
set up a multiple-form search:
Search Terms Enter the terms to search for.
Filter Enter criteria to limit (or "filter") the entries to be searched.
Result Data Enter the additional information you want returned to users (beyond the
standard results) after they run a search.
Note
A full-text search adds wildcards to search strings, but wildcards are not used in searches
across multiple forms.
Page 1534 of 4705
Home
For example, if you search for doc with full-text search, the percent wildcard (%) is added
before and after the string (for example, %doc%). Results can include strings such as
Doctor, Dock, doctrine, and haddock.

Conversely, for searches across multiple forms, wildcards are not added. It is assumed
that the applications knows what the actual terms are (because the application is already
using full-text search and controlling it more closely).
Entering search terms

The Search Terms tab contains fields in which your application will place text that will be searched
across all FTS-indexed forms and fields and to which the user has permissions (unless limited to a
subset as defined on the Filter tab. See Entering search criteria). The fields on the Search Terms
tab are:
Must Have
May Have
Must Not Have
All the fields are optional, but the Must Have or May Have field must include data to obtain search
results. Additionally, the Must Have or May Have field must include data if the Must Not Have field
is supplied with a value.
Parenthetical AND, OR, and NOT queries can be constructed within the Must Have, May Have, and
Must Not Have fields. For example, in the May Have field, you could construct a complex
parenthetical query such as:
(keyboard OR mouse) AND computer AND NOT printer
You can also shorten the AND NOT to simply NOT.

This produces a result where the entries searched must have computer, and must also have either
a keyboard or a mouse, and they must not have a printer.
If you perform an accrue type search in the May Have field (such as keyboard,mouse,
computer), the search results contain keyboard or mouse or computer. If you use the same
accrue search in the Must Have field, the search results contain only entries that contain all three.
If the May Have field and Must Have fields each contain a term, the only entries returned are
entries that match the Must Have field. However, any entries that also contain the words in the
Page 1535 of 4705
Home
May Have field have a higher score than entries that contain only words found in the Must Have
field. For example, if keyboard is in the May Have field and mouse is in the Must Have field, all
entries returned contain mouse, but entries that contain both keyboard and mouse have a higher
score than those entries that contain only mouse.
Entering search criteria

The Filter tab enables you to limit the entries to be searched. The fields on this tab are optional.
They are:
Form List Enter a list of form IDs for forms that you want to search. Separate the IDs with
semicolons. If this field is blank, all FTS-indexed forms and fields (which the administrator
does not specifically exclude and to which the user has rights) are searched.
Search Filter Enter an AND /OR /NOT qualification that uses the configured category
fields (defined by Full Text MFS Category Name field property) as well as create and
modify date fields. For example, you could supply the following search filter to limit the
search:
('status' = "Draft" OR 'status' = "SME Review") AND 'ProductTier1' = "Hardware"
In addition to using category fields, you can use the fields in the following table in a search filter
qualification.
Fields for search filter queries

Field name
Description
createTime
Enables filtering for a specific create date or date range.
modifiedTime
Enables filtering for a specific modify date or date range.
entryId
Enables filtering to a specific entry ID.
schemaId
Enables filtering to a specific form ID.
When you filter with dates, you can use the =, <, >, <=, >= operators, for example:
The following qualification limits entries to those created only on September 1, 2009:
'createTime' = "1251784800"
The following qualification limits the entries to only those created since September 1, 2009 (
open ended):
'createTime' >= "1251784800"
Page 1536 of 4705
Home
The following qualification limits the entries to those created only between (and including)
the dates of September 1, 2009, and September 15, 2009:
'modifiedTime' >= "1251784800" AND 'modifiedTime' <= "1252994400"
The following qualification limits the entries to those created only between (and excluding)
the dates of September 1, 2009, and September 15, 2009:
'modifiedTime' > "1251784800" AND 'modifiedTime' < "1252994400"
Entering search results data

On the Result Data tab, you design how the result data is returned to the user. Result data is for
affecting the data that is to be returned in the search results and to allow defining columns relevant
to that data in a result list.
To configure what should be returned with each result, choose an option from Search Result
Option:
No Excerpt/WAH (the default) Returns only the text that was searched for. (It does not
return an excerpt or the words surrounding the result.) This is the most efficient option.
Excerpt --- Returns the first thirty words of the resulting hit so that the user can read a
summary of the content. This option is less efficient than None, but more efficient than
Words Around Hit.
Words Around Hit (WAH) Returns excerpts that contain the text from the search as well
as surrounding text. The text that was searched for is surrounded by brackets ([]). For
example, if printer was searched for, a result might be setting up the printer in the room 1B .
Count Only Returns the potential number of matches for the search. (The count is taken
before row level permissions are applied, which may reduce the actual result set.)
The following fields are returned with every search request:
Form
Entry ID
Title
Excerpt or Words Around Hit (if requested)
Weight (relevancy score)
Create Date
Modify Date
Page 1537 of 4705
Home
The Optional Return Fields area on the Result Data tab enables you to map a defined category
field to one of the Result fields. You can configure up to 20 result fields.
If the name of a category field is supplied in any result field at the time of the search, then that
result field is populated with the values from that category field. For example, if you enter the
following qualification, the values from the status filter field are returned in Result 1:
'Result 1' = "status"
Note
To define a category field, enter a category name in the Full Text MFS Category Name
field property for the field. For more information, see Defining a field for FTS.
Creating a form and workflow to search across multiple forms

After you have configured your forms and chosen which forms should be excluded from multi-form
search, you can create a form and workflow that enables users to search across multiple forms. For
example, you can create a simple search capability across all forms by providing a display-only
form that contains fields such as:
A character field where users enter the terms they want to search
A character field where users enter the terms they do not want in the results
A menu to choose the forms from which to search
Fields to enter a date range
A table field to display results
The following figure shows the example MFS:MultiFormSearch form, which is installed with BMC
Remedy AR System. You can study this form and its workflow to understand how multi-form search
works.
Example form that enables users to search across multiple forms
Page 1538 of 4705
Home
Using date and time fields on your search form

You might want to include a date and time field on a search form that you create for your users. For
example:
From Date: [1258959600]
If you use the date and time in a filter query, send a normalized value (not the original date and
time string) through the filter. The normalized value is the same as the value on the AR System
server. (The date and time in the previous example is November 23, 2009, 12:00:00 A.M.)
To normalize the date and time value

1. Include a hidden integer field on the form.
2. If you have an event that constructs your filter query, create a Set Fields active link that
copies the value of the date and time field to the hidden integer field.
This causes the client to convert the date and time string to the appropriate integer value,
which takes into account the locale and time zone of the client and normalizes it to the date
and time used by the server, for example:
Hidden_Integer [1250143200]
3. Use the value of the hidden integer for the value of the date that you are passing.
The resulting filter query would look something like this:
'modifiedTime' >= "1250143200"
Re-indexing considerations
Most of the time, you should not have to rebuild your FTS indexes because the AR System server
periodically optimizes them after BMC Remedy AR System requests are added, changed, or
deleted. Some exceptions are:
Page 1539 of 4705
Home
If you change your Ignore Words List, you must rebuild the FTS indexes (re-index). See
How FTS indexing works.
If you change the Case Sensitivity setting, you must rebuild the FTS indexes, and the
re-indexing is started automatically when the change is saved.
Updates to entries for join, vendor, and view form types are not always generated in the
same manner as regular forms. See Scheduling scans for updates.
To rebuild the index for a specific field, you must clear the field for indexing on the Database
Properties tab of the Field Properties window, save the change, reselect the field for indexing, and
save the change.
Note
After upgrading FTS, you must re-index FTS to complete the FTS index upgrade process.
To re-index FTS
1. Open the AR System Administration: Server Information form.
2. Click the FTS tab.
3. Select the Reindex check box.
4. Click OK.
Time required to rebuild a set of indexes
Re-indexing due to field and form property changes
After modifying the Ignore Words List, Root Word List, or Thesaurus
Time required to rebuild a set of indexes
Note
BMC recommends that you perform bulk indexing during off-peak hours, such as during a
maintenance window.
Do not rebuild indexes during normal production hours. Because re-indexing rebuilds your entire
set of FTS indexes from scratch, it can take a long time, depending on the following factors:
The number of fields selected for full text search
The amount of data in each field indexed for FTS in each AR System request
The system load
Whether your indexes are on NFS-mounted or local directories
Page 1540 of 4705
Home
For more information about locating your FTS indexes, see Estimating the size of the FTS index .
Re-indexing due to field and form property changes

To ensure that you re-index at the appropriate time for your environment, be aware of the following
changes that result in field re-indexing:
For multiple-form FTS, when you change the name in the Title field, the new Title field is
re-indexed for all existing entries. This updates the Title field values in the FTS index.
If you remove the field name in the Title field, the field is re-indexed to remove the Title field
values from the index.
When you add, remove, or change the Full Text MFS Category Name field property for a
field, the field is re-indexed.
For more information, see Defining a field for FTS.
If you change the Literal FTS Index field property for a field, the field is re-indexed.
After modifying the Ignore Words List, Root Word List, or Thesaurus
When you modify the Ignore Words List, Root Word List, or Thesaurus and you do not re-index,
your changes affect only entries inserted, deleted, or modified after that time.
For example, if you added network to the Ignore Words List, the FTS index ignores the word
network only for BMC Remedy AR System requests added or modified from this time forward.
However, the FTS index with the word network would still exist for all requests created before the
Ignore Words List was modified.
When you re-index all the fields in all your forms that are currently flagged as indexed for FTS, you
create a new FTS index that ignores the word network in all requests.
To change the Ignore Words List, Root Word List, or Thesaurus, see Configuring FTS for
localization or FTS tab configuration options.
Note
If you modify Ignore Words List, Root Word List, or Thesaurus, you must restart the
Defining a field for FTS

Indexing table fields
Boosting document relevance
Page 1541 of 4705
Home
You can index only the following field types for FTS:
Character
Diary
Attachment fields
Table fields (multiple-form searches only)
Index only frequently searched fields, such as work diaries and descriptions of problems, especially
if the underlying database does not support searches of these fields. For example, you could
perform a search for one or more keywords in a diary field that would retrieve and weigh all BMC
Remedy AR System requests that describe how to solve a problem suggested by those keywords.
You would perform a search on keywords or phrases such as:
Forms, tools, screens, and hardware and software products
Descriptions of problems or solutions
Other areas of interest
When you define a field as indexed for FTS, it might take some time before that field is available for
searching if the form has entries. Indexing a field can take several hours, depending on the amount
of data in that field, the system load, and other factors. While a field is being indexed for FTS, you
can still do non-FTS searches on that field if the underlying relational database permits it.
For each field that you index for FTS, the amount of disk space required for the FTS index can
grow significantly. To estimate approximately how much space is required for your FTS index, see
Estimating the size of the FTS index .
Do not define fields for FTS during normal production hours, especially if you have many BMC
Remedy AR System requests in your database. Indexing uses database and AR System server
resources, which can have a significant impact on the performance of your system.
Note
The Index For FTS property does not appear for field types that are not valid for full text
search.
To define a field for FTS

1. In Developer Studio, open the form.
2. Select the field.
3. Set the Index For FTS property to one of the following options:
FTS and MFS--Indexes the field for both field based searching and multi-form
searching.
Page 1542 of 4705
3.
Home
MFS Only--Indexes the field only for multi-form searching and field based searches
on this field will use the database searching capability.
4. If the field is defined for literal (whole field) searching, set the Literal FTS Index property to
True.
The search engine builds a different type of index for this type of searching, so it must be
specified at design time.
5. (optional) If the field is defined as a rich-text-format field, set the Strip Tags For FTS
property to True.
This optional step enables you to remove all HTML tags from the text of the field before the
data is sent for FTS indexing. When you change this property, the field is automatically
re-indexed.
6. (optional) If the field is on a form that will be part of a multiple-form search, update the field
properties as follows:
a. Enter a new or existing category name in the Full Text MFS Category Name field
property for the field.
At index time, the server checks whether an entry has any fields with a category
name (defined in the Full Text MFS Category Name field property). If so, the server
also indexes the field as that category name.
b. If the field is a table field that should be included in multiple-form searches, select
True for the Index for MFS property.
BMC Remedy AR System begins to index the field for FTS.
The FTS index for a field is automatically updated and does not require manual
administration when you create, delete, or modify requests, provided that the field is a
character, diary, or attachment field on a regular form or view form with data that is not
changed from outside of BMC Remedy AR System.
Indexing table fields

You can enable table fields to be searched in multiple-form searches, but not in regular full text
searches. If a table field is indexed, the server retrieves only the character data and ignores
columns of other data types (such as columns from numeric data fields). The server concatenates
the character data from the table and inserts a space character between the data from the fields.
For example, suppose the following table is indexed.
Log Entry
Entry Time
Entry Author
Sent email to customer
325983991
Demo
Still waiting to hear from customer.
325985020
Demo
Customer responded.
325986800
Demo
This table would generate the following character string for indexing:
Page 1543 of 4705
Home
Sent email to customer Demo Still waiting to hear from customer. Demo Customer responded
. Demo
A string like this is created for each entry in the parent form using the table field rows that
correspond to that parent form entry.
Note the following caveats when indexing table fields:
All qualifying rows are indexed for the table field, regardless of the maximum rows value set
for table field entry retrieval.
For example, if you limit table field retrieval to 100 rows but 110 entries qualify, the server
includes all 110 entries in the character string it builds. If a search term is found only in the
10 entries the user does not see, it may not be apparent why the table field qualified as a
search hit. However, if the table is re-sorted, the search term could appear in the resorted
entries. (Note that table-field chunking is not relevant to indexing, but a search term might
not be displayed in the chunk the user is viewing.)
Permissions and row-level security is not enforced during searching on table fields, so a user
could potentially retrieve search hits from table field columns that the user cannot view.
Because character data is concatenated for table field searches, the server cannot eliminate
the data from inaccessible columns. If a table field contains highly sensitive data, you should
not index it for a multiple-form search.
BMC Remedy AR System does not automatically detect when entries are added or changed
in a supporting form, but the parent form entries should be re-indexed.
You can manually re-index a table field to keep the index up to date, but no automatic
solution exists. Instead, to keep table field indexes up to date, create workflow that pushes
updates to the parent form entries when changes are made to entries in the supporting form.
When a change is detected in the parent form entry, BMC Remedy AR System re-indexes
the entry, including the table field. Some applications update only the table field supporting
the form through parent form interaction. In those cases, the parent form might already be
experiencing an update, and additional workflow is not necessary.
Some table fields are not eligible for multi-form search indexing. If the table field qualifier has
EXTERNAL qualifications or display-only field references and the Index for MFS field property
is set to True, an error is returned when the user tries to save the form.
In many cases, you can achieve the necessary search functionality by creating a copy of the
displayed table field and making that copy a hidden table field on the form. This hidden table
field can have a simpler qualification containing only database fields, making it eligible for
multi-form search indexing. The goal is to index (in the copied table) all of the table field data
that can be seen when viewing the displayed table field. Many times the additional
qualification clauses that contain display-only fields are used to dynamically filter the table
field rows. By removing those clauses, the indexing occurs on all the rows in an unfiltered
manner. Because multi-form searching is not field specific, indexing a copy of the field with a
modified qualifier can produce the necessary results.
Page 1544 of 4705
Home
Boosting document relevance

To influence the relevance score that the search engine calculates for returned results, add a
reserved ID field (177) with a data type of Real to a form. The range of the boost value is 0 to 2000.
The default boost is 1.0 (the neutral value).
To increase the relevance, an entry must have a document boost value of 1.1 to 2000. The higher
the value, the more relevant the entry is. To decrease the relevance, an entry must have a
document boost value of 0 to 0.9. The lower the value, the less relevant the entry is.
How FTS indexing works

BMC Remedy AR System uses the arserverd process (arserver.exe on Windows) to insert,
update, or delete data in the FTS indexes. Threads from the Full Text Indexing queue perform the
indexing. This queue has one thread by default, which is sufficient for very large indexing
environments. You can configure more indexing threads for FTS. However, you must exercise care.
For more information, see the "Defining queues and configuring threads" section in Setting ports
and RPC numbers.
The indexing mechanism is based on an asynchronous queue, which is based in an internal system
table (ft_pending) in the database during the originating transaction. The originating transaction
typically involves a create entry, set entry, merge entry, or delete entry operation on a form where a
field indexed for full text search exists.
A full text dispatcher thread processes the indexing tasks in real time on a first-in, first-out basis,
queuing them for indexing threads to process. As a result of this indexing model, the performance
of the originating transaction is affected only marginally by inserting the indexing task record into
the system table, and is not subject to delays associated with full text indexing. However, the data
might not be immediately available for searching. The size of the delay depends on the size of the
indexing queue and the availability of system resources to perform the indexing.
Note
BMC recommends that you perform bulk indexing during off-peak hours, such as during a
maintenance window.
If the administrator has disabled indexing, indexing tasks are still recorded, preserving the changes
for later inclusion when indexing is enabled.
How FTS indexing works for attachments
How FTS indexing works for localization and attachment file formats
Causing accrued and weighted results with FTS
Page 1545 of 4705
Home
Tokenization rules used in FTS

Estimating the size of the FTS index
How FTS indexing works for attachments

Indexing for attachments is selected on a per-field basis, not by attachment pool. Therefore, it is
possible to index only some of the attachment fields in a pool. The advantage to indexing only
some of the attachment fields is that you can designate (and appropriately name) "buckets" for
attachments likely to have value when indexed, as opposed to those that will not. The system
attempts to index any attachment that is placed into an attachment field indexed for FTS. By
guiding users to place attachments in the appropriate "buckets," the system can avoid unnecessary
processing.
Note
Attachments with unsupported data formats are not indexed successfully. If an attachment
cannot be indexed, only the Full Text Indexer log indicates this issue. The error log does
not note that the attachment cannot be indexed. See Full text search indexer logging.
For HTML and XML file attachments, only the content (not the metadata) is indexed. That is, the
elements and their attributes are not indexed.
The following formats are supported for FTS of attachment files:
Hypertext markup language (HTML) format
XML and derived formats
Microsoft Office document formats (Word 97 and later--see the note that follows)
OpenDocument format (OpenOffice 1.0 and later--see the note that follows)
Portable document format (PDF) (versions 1.0 through 9.0)
Electronic publication format (digital books)
Rich text format (RTF)
Compression and packaging formats (.zip, .tar, .bzip2, .ar, .cpio )
Text formats (Most Unicode and ISO 8859 documents in plain text)
Audio formats (extracts Lyrics [if present] and any metadata from MP3, MIDI, and other
simple audio formats)
Image formats (extracts metadata from image formats supported by the java platform)
Video formats (supports only Flash video format using a simple parsing algorithm)
Java class files and archives (extracts class names and method signatures from Java class
files and the .jar files containing them)
The mbox format (extracts email messages from the mbox format used by many email
archives and UNIX mailboxes)
Page 1546 of 4705
Home
Note
New versions of file formats for vendor products are assumed to be compatible with
previously supported versions. In the event that a vendor does not provide backwards
compatibility, BMC reserves the right to rescind support for a specified version of a
vendor's product and document such incompatibilities once confirmed. BMC might, at
BMC's discretion, attempt to address a discovered incompatibility by modifying the current
version of BMC Remedy AR System. However, if major architectural changes in a vendor
product require significant BMC development to achieve tolerance, support for the vendor
product may be deferred to a later version of BMC Remedy AR System.
How FTS indexing works for localization and attachment file formats
With some special considerations for attachment fields, the full text feature can index any content
where the character set is compatible with the AR System server's character set. If the AR System
server is running as a Unicode server, the full text feature has no restriction on the encoding format
of the data content. You can index and search content in multiple languages.
With a non-Unicode AR System server, the data content must be compatible with the server's
character set. When indexing and searching attachments with common formats, such as Microsoft
Office documents and PDF documents, the full text feature can process the data without a
dependency on the server's character set. For plain text files, the full text feature requires that the
server recognize the character set of the data.
Note
The locale of the AR System server defines the locale by which all text is processed.
Language text can be indexed and searched, but the analysis (stemming, thesaurus, and
root words) is applied according to the rules for the server's locale. For example, if the
server is set up for English (en), all words (whether they are English or any other
language) are processed as if they were English.
Causing accrued and weighted results with FTS

FTS provides quick and consistent access to AR System requests for which a user is searching.
Users can use a special accrue operator (the LIKE operator with comma-separated words, for
example) to cause BMC Remedy AR System to accrue and retrieve all requests that contain any or
all words from a comma-separated list (for example, computer, PC, and error number 3794).
FTS assigns a weight to requests retrieved in an accrue operation. Weight is an integer value from
0 to 100. With weight, BMC Remedy AR System can sort requests in a results list using a "the
more, the better" approach. If a user sets the Field Sort Order in the browser to include WEIGHT in
descending order, the more search terms found in a request, the higher in the list it appears in the
Page 1547 of 4705
Home
set of retrieved requests. The closer Weight is to 100, the better it matches the search criteria.
For more information about modifying results list attributes to include FTS weights, see Displaying
FTS weight in a results list.
Tokenization rules used in FTS

Tokenization is the process of breaking words into discrete tokens to insert them into an index and
to search on the tokens. Following are the basic rules of tokenization used in FTS for indexing and
searching.
For literal fields, the content of the field is treated as a single token with no modification. For
example, x-y=z becomes x-y=z (one word). All the text constitutes the token or word stored in the
index. It can be found in a search only by supplying the exact matching string. That is, searching for
y does not find a match, but searching for x-y=z does find a match.
For non-literal fields, the following rules apply:
Words are split at punctuation characters, and punctuation is removed. However, a dot that
is not followed by white space is considered part of a token.
one:two becomes one two (two words).
Alpha#Omega becomes Alpha Omega (two words).
x.y.z becomes x.y.z (one word).
Words are split at hyphens unless the token contains a number, in which case the whole
token is interpreted as a product number and is not split.
x-y=z becomes x y z (three words).
KX-13AF9 becomes KX-13AF9 (one word).
Email addresses and internet host names are recognized as one token.
someone@bmc.com becomes someone@bmc.com (one word).
www.bmc.com becomes www.bmc.com (one word).
In words with no spaces, the ampersand (&) is retained.
Smith&Brown becomes Smith&Brown (one word).
Estimating the size of the FTS index

Place the FTS index in a directory that has sufficient disk space. The directory must be large
enough to accommodate at least twice the amount of data indexed for FTS. For example, if the
total amount of data in all fields to index for FTS in all forms is 100 MB, then at least 200 MB of disk
space is required for the indexes. (This example is only an approximation.)
To estimate the size of the FTS index

1. Estimate the amount of text in your database.
For example, take a small sample of requests and calculate the average size of data in the
field. Then, multiply this average by the number of BMC Remedy AR System requests to
derive the size of text in your database.
2.
Page 1548 of 4705
Home
2. Multiply by a minimum of 2.
The ratio of the size of the FTS index to source text can differ widely based on, for example,
the size of your Ignore Words List.
Performing searches with FTS

FTS is transparent to users. If the server has a Full Text Search license and the full text feature is
configured correctly, full text searching is activated.
If full text searching is activated and the field is indexed for FTS, FTS is used.
If full text searching is not activated or the field is not indexed for FTS, AR System uses the
search capability of the underlying database. Under these conditions, attachment fields have
only their names searched.
Field permission-related behavior for FTS fields is the same for non-FTS fields.
Users enter search criteria in the same way, whether they are using FTS or not, with the exception
of accrual searches.
Searching in a field indexed for FTS
Searching for words or phrases
Performing an accrue search
Performing a literal search
Searching for variations of word stems
Searching with a wildcard character
Using the query-by-example method
Restricting search criteria with a parametric FTS
Limitations of FTS
Searching in a field indexed for FTS

In most cases, performing a qualified search on a field indexed for FTS returns results consistent
with a database search. Users can still use the search strings and search patterns they are already
familiar with.
The search method that the FTS engine uses depends on the following factors:
The original search criteria entered by the user
The query-by-example (QBE) match settings of the field
The FTS Search Options setting of the server
The type of full text index created for the field
Page 1549 of 4705
Home
FTS uses these factors to determine the final search criteria. Succeeding factors override
preceding factors. For example, if a user includes a leading wildcard as part of a full text search but
the FTS Search Options setting is set to Ignore Leading Wild Card, FTS ignores the wildcard that
the user entered. See Using the query-by-example method for more information.
The FTS engine uses the final search criteria to search the contents of all requests indexed for that
field, and it uses one of the following search methods:
Word or phrase search
Accrue search
Literal search
Note
All the following examples use FTS in the Advanced Search Bar, not QBE. They assume
that the FTS Search Option is set to Query Unchanged.
Searching for words or phrases

During a word or phrase search, the FTS engine finds requests that contain the specified word or
phrase in the field. To perform a word or phrase search, use double-quotation marks around the
words to search for. The syntax for the search qualification is
<field> LIKE " <word1> <word2> . . . <wordN>"
For example, to search for the phrase "firewall blocked", type:
<field> LIKE "firewall blocked"
With this example, a full text search finds requests with the phrase "firewall blocked" with the
search for blocked expanded to the word stem block with any of its variants.
Note
The use of wildcards in a word or phrase search affects how stemming is used. For more
information, see Searching for variations of word stems .
The following table outlines the expected search results using a word or phrase search.
Results of searches that use a word or phrase search
Page 1550 of 4705
Home
Qualification
Example data
Matches
<field> LIKE "firewall blocked"
firewall blocks access
firewall will block access

firewall blocking my access
firewall blocked her access
firewall did not block access

have the firewall block access
firewall is not working

try blocking his access
<field> LIKE "%firewall block%"



<field> LIKE "%firewall blocks%"

<field> LIKE "blocks"
<field> LIKE "%blocks%"
Page 1551 of 4705
Home

Performing an accrue search

During an accrue (OR) search, the FTS engine finds requests that contain any of the specified
words in a field, instead of matching a string of characters. The FTS engine matches the pattern of
the characters specified in the search. To perform an accrue search, use double quotation marks
around the words to search for, separating the words with a comma. The comma is the accrue
operator. The syntax for the search qualification is:
<field> LIKE "<word1>,<word2> . . . <wordN>"
For example, if you wanted to search for the words "firewall" and "blocked," enter:
<field> LIKE "firewall,blocked"
For this example, a full text search will find requests with any occurrence of the words firewall or
blocked with the search for blocked expanded to the word stem block with any of its variants.
Note
You can use the accrue operator only with fields indexed for FTS. Using the same
operator for a field that is not indexed for FTS causes the AR System server to search for
the literal string with a database search.
The following table shows the expected search result using an accrue search.
Results of searches that use an accrue search
Qualification
Example data
Matches
<field> LIKE "firewall,blocking"
Page 1552 of 4705
Home
<field> LIKE "firewall,blocked%"
Performing a literal search

Unlike accrue searches and word or phrase searches (which are word-based), the FTS engine
uses a literal search to find requests that match the string of characters based on the contents of
the entire field. Literal searches are possible only if the field has been indexed for literal searching,
and if it is, only literal searching is possible, not accrue searches or word or phrase searches.
Literal searching is useful mainly for performing case-insensitive searching on short character fields
, like name fields, with a very small set of requests matching the search criteria. However, you can
add a leading or trailing wildcard to increase the scope of a literal search. If you use both a leading
and trailing wildcard, a literal search becomes the equivalent of a word or phrase search. The
syntax for the search qualification is:
<field> LIKE "<stringToBeSearchedFor>"
For example, to search for the word "firewall," enter:
<field> LIKE "firewall"
With this example, a full text search finds requests where the entire content of the field is firewall (
or Firewall if searching with case insensitivity).
The following table outlines the expected search results using a literal search.
Results of searches that use a literal search
Page 1553 of 4705
Home
Qualification
Example data
<field> LIKE "firewall"
Matches

<field> LIKE "firewall will block access"


<field> LIKE "%firewall%"

<field> LIKE "firewall%"


<field> LIKE "blocks"
Page 1554 of 4705
Home

<field> LIKE "%blocks%"

Searching for variations of word stems

The FTS engine uses stemming to search for common variations of word stems. For example, a
word search for the term block returns requests containing these terms:
block
blocks
blocked
blocking
Searching for blocking returns the same set of requests.
Stemming is not used in the following searches:
Wildcard searches For example, if the search term is %blocking%, only requests
containing blocking" are returned.
Case-sensitive searches For example, a case-sensitive search for block returns only
requests containing block.
Searching with a wildcard character

Users can use the percent sign (%) wildcard for any type of search to broaden the set of matching
requests. For example, searching with the term %fire returns requests with fire and backfire.
Searching with fire% returns requests with fire and firewall. Searching with %fire% returns all
combinations.
Page 1555 of 4705
Home
Note
A full-text search adds wildcards to search strings, but wildcards are not used in searches
across multiple forms.
For example, if you search for doc with full-text search, the percent wildcard (%) is added
before and after the string (for example, %doc%). Results can include strings such as
Doctor, Dock, doctrine, and haddock.
Conversely, for searches across multiple forms, wildcards are not added. It is assumed
that the applications knows what the actual terms are (because the application is already
using full-text search and controlling it more closely).
Using the query-by-example method

If you do a search inside a form by filling out fields in the form, you are doing a traditional FTS QBE
search (for any of the fields that are FTS enabled). The query-by-example (QBE) Match field
property affects QBE searches as follows:
If the property is not set to Equal, appropriate wildcards are added to the search terms
automatically.
If the property is set to Equal, you must add the appropriate wildcards to the search terms.
Note
Attachments cannot be searched with the QBE method unless a special Form Search field
is present on the form. For more information, see Providing a shortcut for specifying
expanded FTS qualifications.
Users can enter a QBE in any field indexed for FTS, according to the following syntax:
left,center,right
However, the property settings influence how an accrue search works, as shown in the following
table.
Effects of QBE Match property settings on accrue searches
Page 1556 of 4705
Home
QBE Match
property
setting
Effect on search criteria
Anywhere
%left,center,right%
The client adds wildcards to the start and end of the search. The server makes a special interpretation of these
search criteria for a full text search and places a leading and trailing wildcard around each search term. For
example:
%left%,%center%,%right%
Leading
left,center,right%
The client adds a wildcard to the end of the search. The server makes a special interpretation of these search
criteria for a full text search and places a trailing wildcard after each search term. For example:
left%,center%,right%
Equal
left,center,right
The client does not add any wildcards to the search string, but it uses the EQUAL (=) operator instead of the LIKE
operator. This has no effect on the server's full text search.
Restricting search criteria with a parametric FTS

Returning a large result set is a common issue with a search system. With a parametric full text
search, users can restrict the search criteria by combining FTS and non-FTS fields in a search.
Doing so helps the server filter out irrelevant entries and dramatically reduce the size of the result
set.
Users can search terms in multiple fields for a QBE search or specify an advanced search like the
following example:
:<FTSfield> LIKE "firewall" AND 'Create Date' >= "01/01/06"
This qualification returns all entries that contain firewall and were created on or after January 1,
2006.
Limitations of FTS
Limits to performing a full text search include:
In accrue searches, you cannot search for most punctuation marks because they are treated
as word separators.
In accrue searches, do not use words from the Ignore Words List. For example, if the word
the is in the Ignore Words List, searching on the phrase the, database, request in the
Short Description field might return requests with the word the in them, but it is not used in
the search itself. For additional information about the Ignore Words List, see Configuring the
Ignore Words List.
Submitted or modified requests might not appear immediately in the results list if you are
searching on a field enabled for FTS. Sometimes a short delay occurs between the time the
request is submitted or modified in the database and the time that the request is available for
searching in the FTS index.
Page 1557 of 4705
Home
The indexing of fields on form types that require scanning for changes (join, vendor, and
view forms with data updated outside of BMC Remedy AR System) does not recognize the
deletion of entries and does not remove the indexing for those entries from the index. You
must manually reindex those form types occasionally to remove deleted entries from the
index.
Searching conducted within filter workflow that involves qualifications with full text indexed
fields can produce unexpected results if the searching depends on data that was created
during the same filter sequence. Database searches can find data that was recently created,
but full text searches cannot. To preclude the use of full text searching during a filter that
conducts this type of search, select the Use FTS in Workflow option on the FTS tab of the
AR System Administration: Server Information form. For more information, see FTS tab
configuration options.
Full text searches that involve a field reference to the right of the relational operator are not
supported. A warning message occurs that indicates that the query was treated as a
database query instead of an FTS query. The presence of 'Target' in the following
example returns the warning message if the Short Description field is indexed for FTS:
'Short Description' LIKE 'Target' + "ing"
If no variables are to the right of the LIKE keyword in the statement, FTS handles the search
. For example:
'Short Description' LIKE "block" + "ing"
In this example, the search is handled by FTS because the known values ( block and ing) are
combined to form one known value ( blocking).
FTS index migration

AR System uses the Lucene 4.9 search engine for Full Text Search (FTS) and uses a
schema-specific multi-file index format to optimize read/write operations, resulting in searches that
are about three times faster and indexes that are about 40 percent smaller than the Lucene 2.9
index used in earlier releases.
FTS migration utility

The Full Text Search (FTS) index migration utility arftsutil migrates the 2.9 index to the 4.9
multi-file format. The arftsutil utility does two things:
1. Updates Apache Lucene 2.9 indexes to 4.9
2. Splits the index into multiple schema-specific files
The two versions of arftsutil are:
Page 1558 of 4705
Home
arftsutil.bat - For Windows servers

arftsutil.sh - For UNIX servers
The arftsutil utility is embedded in the AR System interactive GUI installer and runs automatically if
a single-file Lucene 2.9 index is detected. If the GUI installer detects that a Lucene 4.9 index is
present, it does not execute arftsutil again.
The AR System GUI installer has no option to override automatic migration but you can bypass the
migration by running the installer in silent mode with the following option:
-J BMC_AR_SKIP_FTS_INDEX_MIGRATION=true
To manually migrate a 2.9-based index, run arftsutil from the command line.
Windows servers:
<C:\BMCRemedy\AR>\arftsutil.bat -d <COLLECTION DIR PATH>
-c <FTS
CONFIGURATION DIR PATH>
UNIX or Linux servers:
</BMCRemedy/AR/arftsutil.sh -d <COLLECTION DIR PATH>

DIR PATH>
-c <FTS CONFIGURATION
Note
Schema-specific index files are stored in the Full-Text-Collection-Directory configuration
parameter in the ar.cfg file, with a unique schemaId subdirectory for each schema index.
For example, if the ar.cfg file specifies the collection directory as C:\Program Files\BMC
Software\ARSystem\ftsconfiguration\collection and the search user creates a schema
named TestForm that has a schema ID of 1234, the index documents for this schema are
created under C:\Program Files\BMC Software\ARSystem\ftsconfiguration\collection\
1234.
Related topics:
Performing a new installation
Running the installer in silent mode
Page 1559 of 4705
Home
Enabling FTS high availability

Enhancements to Full Text Search including High Availability improve reliability, scalability, and
performance. The following topics are covered here:
Full Text Search High Availability overview
Video: Full Text Search High Availability for server groups
Full Text Search High Availability overview

In a server group environment, Full Text Search (FTS) can be configured for high availability (HA)
so that search requests are completed even when a server in the group becomes unavailable. By
designating multiple servers as indexer servers, if one server goes down another will execute
queued search requests. Under the FTS HA model:
Every server with valid AR System Server Group Operation Ranking acts as an indexer
server.
Each indexer has its own copy of indexes.
The searcher server sends the search requests to indexer servers.
In event of an indexer server failure or service interruption, a search request is routed to the
highest ranking available indexer server to complete the search request.
FTS
You can install more than one FTS server in a server group as shown in the diagram. Each of these
servers operates as an independent FTS server, providing high availability and service failover. In
prior releases, one server in a server group acted as the FTS server.
Refer to High-availability architecture for FTS detailed information about how FTS high availability
works in a server group environment.
Page 1560 of 4705
Home
Note
To enable high availability and failover, all FTS plug-ins must run on same port.

Under the FTS HA model, each primary FTS indexing server has its own virtual queue of data to
index. When AR System queues data for indexing in parallel to AR Database changes in data, it
queues separately for each primary FTS indexing server as designated by the AR System Server
Group Operation Ranking form for FTS.
In a server group, the server that owns the full text indexing operation processes all pending
indexing tasks regardless of their server of origin. The other servers have read-only access to the
index files. When full re-indexing occurs on any server, the re-indexing takes place on the
designated indexer only.
FTS is configured after all servers in the group have been installed and configured to run within a
server group. For best results, locate FTS collection directory and the FTS configuration on the
same computer.
To set up FTS in a server group

1. Rank the FTS servers in the AR System Server Group Operation Ranking form. For more
information, see Setting failover rankings for servers and operations . Only servers with a
valid AR System Server Group Operation Ranking work as indexer servers. Every server
with a Null FTS operation rank works as a searcher server.
Note
You should use the FTS indexing server, which is ranked 1 in the AR System
Server Group Operation Ranking form, for searching and the indexing server that is
ranked 2 as the failover server.
> General > FTS Configuration.
3. Complete the form according to FTS Configuration form in the AR System Administration
Console.
Video: Full Text Search High Availability for server groups

This brief video explains FTS High Availability and other recent enhancements to FTS.
Page 1561 of 4705
Home
Related topics:
Configuring FTS High Availability failover after an upgrade

When upgrading to BMC Remedy AR System 9.0, it may be necessary to reconfigure the AR
System Server Group Operation Ranking form to enable failover, ensuring that search requests are
fulfilled if one of the indexer in your server group becomes unavailable. If you upgrade to BMC
Remedy AR System 9.0 from earlier versions, consider the following:
Upgrading from 7.6.04, 8.0, 8.1, or 8.8: You should reconfigure failover in the FTS ranking
form, after the upgrade is complete. In this case, an extra plugin entry ARSYS.ARF.FTS
ARSYS.ARF.FTS is created on the indexer machine. There is no impact of this entry and
you can ignore it.
Upgrading from 7.6.04 SP5, 8.1 SP1 or SP2: You need not reconfigure failover in the FTS
ranking form.
To enable failover with the AR System Server Group Operation Ranking form , refer to Setting
failover rankings for servers and operations.
For information on enabling FTS high availability, refer to Enabling FTS high availability.
Related topic
Controlling BMC Remedy AR System through

email
This section explains how to transform email into an interface that communicates with the BMC
Remedy AR System server using the BMC Remedy Email Engine service.
BMC Remedy Email Engine terminology
How BMC Remedy Email Engine works
Setting up UNIX mailboxes
Creating and using email templates
Email Engine forms
Page 1562 of 4705
Home
BMC Remedy Email Engine terminology

Term
Meaning in the context of BMC Remedy Email Engine
Mail
server
A computer system within your environment that is running a third-party software program that processes incoming
and outgoing email messages. Examples include the Microsoft Exchange server or the UNIX sendmail program.
Failover
mail
A mail server that acts as a failover system, assuring uninterrupted processing of messages, when the primary mail
server stops working. You can define this by using the BMC Remedy AR System Email Failover Mail Server form.
server
For more information, see Multiple mail server support.
Email
account
A user account on a mail server that permits a user to transmit or receive email messages.
Note
An email account is not the same as an email address. An email account consists of a user name and often
includes a password. Users must log in to the mail server by using an email account before they can send
and receive email.
Mailbox
An entry in the BMC Remedy AR System Email Mailbox Configuration form, which resides on your AR System server
. A mailbox contains all of the information required by BMC Remedy Email Engine to access mail from a mail server
or to request that mail be sent by a mail server. As such, a mailbox can contain such information as the name of the
mail server, the protocol used by that mail server for sending or receiving mail, and email account information (if
required). Mailboxes are configured to be either Incoming mailboxes or Outgoing mailboxes.
Incoming
A mailbox containing the information required by BMC Remedy Email Engine to connect to and read email messages
mailbox
from a specific email account on a mail server. Email messages in this email account are assumed to be directed to
the BMC Remedy Email Engine. The installation program provides an option for creating and configuring an initial
incoming mailbox. You can use this mailbox to get started with BMC Remedy Email Engine; you can then change
these settings or configure additional mailboxes.
Outgoing
mailbox
A mailbox containing the information required by BMC Remedy Email Engine to create and send messages. BMC
Remedy Email Engine uses this mailbox to send notifications, send the results of queries, and so on. The installation
program provides an option for creating and configuring an initial outgoing mailbox. You can use this mailbox to get
started with the BMC Remedy Email Engine; you can then change these settings or configure additional mailboxes.
Instruction
A term used in the following ways:

In a broader sense, instructions see all the parameters contained in an email message that perform certain
actions; for example, logging in to the server, querying for all tickets assigned to a user, and returning the
results in HTML format.
In a narrower sense, instructions see a specific set of actions used in an email message; for example, Query,
Submit, or Modify. The term Instruction can also be used as an alias for Action in a label/value pair.
How BMC Remedy Email Engine works

Improving the appearance of your email
Multiple mail server support
Page 1563 of 4705
Home
This topic presents a sample scenario that demonstrates how Email Engine interacts with the BMC
Remedy AR System and your mail server. The following figure presents a sample environment for
an Email Engine implementation, including the flow of activity.
How Email Engine interacts with the AR System server
In the XYZ Company, Shelly needs a list of the latest issues stored in the Help Desk (HD) Incident
form. She wants the results of this query to be returned in an easy-to-read email. Also, Shelly wants
to make sure that her coworkers, Katie and Mark, will be copied with the results of this query. All of
the steps that Email Engine and the users must take to make this happen follow.
1. The local administrator installs Email Engine, configuring Incoming and Outgoing mailboxes
to work with the company mail server.
After Email Engine is started, it contacts the AR System server. It then reads all the entries
in the AR System Email Mailbox Configuration form and creates Incoming and Outgoing
mailboxes based on that information.
2. After the administrator notifies the user base that Email Engine is running, Shelly composes
an email instructing the Email Engine to perform a query of the HD Incident form. She uses
specifically formatted instructions to be read and understood by the Email Engine. She
sends this message to an email account on the company mail server that Email Engine polls
for incoming.
3.
Page 1564 of 4705
Home
3. After waiting for a prescribed polling period, Email Engine logs in to the company mail server
by using the email account information gathered during step 1. Because the mailbox
information tells the Email Engine that this email account is to be treated as an Incoming
Mailbox, the Email Engine reads the most recent emails from this account, by using one of
several email protocols (POP3, IMAP4, MBOX, or MAPI), including the email that Shelly sent
.
4. Email Engine interprets the instructions and translates them into API calls to the AR System
server, attempting to fulfill her query request.
5. The AR System server responds to Email Engine API calls with the appropriate query
information for the HD Incident form.
6. Email Engine uses the formatting instructions in the Outgoing Mailbox to construct an email
message to the company mail server. Email Engine then transmits the message with
instructions to send the message to Shelly, Mark, and Katie, by using the outgoing email
protocol (SMTP or MAPI).
7. Shelly, Mark, and Katie log in to the mail server, and they find the email constructed by the
Email Engine, which contains a neatly formatted list of the most recent requests.
This example illustrates the relationship between the Email Engine and other systems in a
simplified environment. Your environment might differ from the one presented here. For example,
the Email Engine might reside on the same system as the AR System server. Alternatively, you
might configure the Incoming Mailbox and Outgoing Mailbox to use the same email account on your
mail server, and so on. Many of the configuration options available are explained in the upcoming
sections. Also, as you proceed through this section, you will learn about the other Email Engine
features for processing email.
Improving the appearance of your email

The administrator at XYZ is pleased by the response of the BMC Remedy AR System user
community to the Email Engine. Users feel comfortable using email to query the AR System server
and to submit and modify entries. However, he hears occasional grumbling in the hallway. Why is
Email Engine so featureless? Can it not look more like email that comes from a favorite online
auction website or online bookstore? the following figure illustrates a solution, showing how the
Email Engine can assign HTML templates to outgoing email.
Templates dynamically assigned through workflow
Page 1565 of 4705
Home
Realizing the importance of BMC Remedy AR System notifications, the administrator takes steps to
replace the plain text email generated by the Email Engine. To improve its look and feel, he designs
attractive HTML pages to use as header, footer, result, and content templates. He works with a
graphic artist to create interesting bitmaps.
Most important, he designs a data-driven workflow that dynamically assigns the correct templates
based on the ticket's impact. The templates are designed so that users can quickly tell whether a
ticket's impact is urgent, high, medium, or low.
The following steps illustrate the scenario:
1. Shelly is visiting an important client in Chicago. She needs information from the corporate
website within the hour to close an important deal, but the web server is down and her web
client keeps returning error messages. She composes an email with status marked Urgent
and sends it to the Incoming mailbox.
2. The Email Engine receives the email from the mail server. It parses the instructions in her
email, and makes the appropriate API calls to the AR System server.
3. The server fires a filter that triggers a Notify action. Under normal circumstances, email
notifications are formatted with a standard HTML header and result template. But if a
submission is marked Urgent, the filter workflow creates an email notification with the Urgent
header template.
4. The Email Engine constructs the message according to formatting instructions contained in
the Outgoing Mailbox it is using. This message consists of the field values from the HD
Incident form (submitter, short description, status, assignee, and so on) along with the
Page 1566 of 4705
Home
header and reply templates that are stored by the AR System server in the AR System Email
Templates form. The Email Engine then transmits the message to the mail server with
instructions to send the message to Francie Frontline, the first-line Customer Support
engineer.
5. Francie Frontline logs in to the mail server to see if she has new mail. She sees the Urgent
email constructed by the Email Engine. She clicks the URL in her email, and the ticket opens
in her browser. Because the email is marked Urgent, its importance jumps to the top of her
To Do list. She troubleshoots and quickly resolves the problem. When Francie marks the
ticket as Fixed, the server fires a filter Notify action. Shelly then receives an email notification
from the system that her web access problems have been solved. She can now access the
information she needs to close her sale.
For more information, see Dynamically assigning templates to outgoing email.
Multiple mail server support

You can configure multiple mail servers for a Email Engine installation. For each configured mail
server, you can specify a failover mail server. If the mail server being used stops working, the Email
Engine switches to the available failover mail server and continues processing mails. The following
figure depicts this functionality.
Multiple mail servers configured for failover
In the illustration, M1 is specified as the primary mail server, and M2 and M3 are specified as
failover servers. If the Email Engine detects that M1 is not working, it checks whether M2 is
available, and if so, it switches to M2.
Page 1567 of 4705
Home
The Email Engine then tries to connect to M1, and if that is not yet working, it connects to M2. Then
, if the Email Engine detects that M2 is not working, it checks for the availability of M1. If M1 is still
not working, it looks for the failover server for M2, which is M3. If M3 is available, it switches to M3
and continues processing messages as described in the preceding note.
If none of the configured mail servers is working, the Email Engine produces an error and stops
processing.
When switching from a server being currently used to its failover server, an entry is added to the
stderr.log (Windows) or emaild.sh_log (UNIX) file. However, when switching back from the
failover server to the primary server, no change is made to stderr.log or emaild.sh_log.
Note
The multiple mail server support is currently available for the SMTP protocol only.

This section provides the following information and instructions for creating and transmitting
outgoing email messages from the Email Engine:
How outgoing email works
Types of outgoing email
Sending notifications
Sending outgoing email with the Email Messages form
Sending professional looking reply emails
Encoding user-defined text in outgoing HTML email
How outgoing email works

The following figure presents a sample scenario that demonstrates how the Email Engine sends
outgoing notifications.
How the Email Engine sends outgoing email notifications
Page 1568 of 4705
Home
In this scenario, John, the local BMC Remedy AR System administrator, has decided to test the
notification capabilities of the Email Engine.
1. In the XYZ Company, the IT department has a service-level agreement (SLA) that urgent HD
incident tickets must have a response in one hour. The AR System administrator designs an
escalation that triggers a Notify action to send an email notification to the backline support
engineers if the SLA is not met. Because of a sudden swell of incoming tickets, the front line
engineers cannot respond to one of the urgent request in one hour. As a result, the AR
System server triggers an escalation.
2. Because John has configured the Notify escalation to use email as the notification
mechanism, when the escalation is triggered, the AR System server creates an outgoing
record in the AR System Email Messages form. The Email Engine monitors the AR System
Email Messages form for all outgoing messages, and then sends the messages to the
outgoing mailbox on the mail server.
3. The Email Engine constructs the message according to formatting instructions contained in
the Outgoing Mailbox it is using. This message consists of the field values from the HD
Incident form (submitter, short description, its urgent status, assignee, and so on). The Email
Engine then transmits the message to the mail server with instructions to notify Bob Backline
, the back line Customer Support engineer.
4. Bob's email client receives the new email. He reads that an urgent ticket has been assigned
to him. Most importantly, Bob sees that all the necessary details of the ticket are contained in
the email constructed by the Email Engine.
For more information, see the following sections:
Defining a workflow to send email notifications
Types of outgoing email

Page 1569 of 4705
Home
Note
The examples of outgoing email in these sections make extensive use of label/value pairs,
aliases, variables, templates, and special keyword syntax as message content; the Email
Engine ignores any other text. For more information, see the detailed reference material
and examples of their use in Creating and using email templates.
This section describes the different types of outgoing email in the Email Engine:
Notifications The most important use of outgoing email is using workflow to send
notifications to users. AR System uses the Email Engine to send all notifications, not just
email. You must install the Email Engine to send notifications from the AR System server.
Replies to senders A common function of outgoing email is making replies to senders (
who send email to the incoming mailbox) with results. When you created an incoming
mailbox, one crucial task you performed was associating an outgoing mailbox, specifically for
the purpose of replying to emails that require a response, for example, query results. For
more information, see Sending professional-looking reply email.
Messages form You can send outgoing email using the AR System Email Messages
form. You can type the message, or specify contents templates to use in the body of the
email. Typically, you only use the AR System Email Messages form for configuring or
troubleshooting the Email Engine. The average user never sees or needs this form.
Sending notifications
Dynamically assigning templates to outgoing email
Displaying date-time or numeric values in email notifications
Deleting email notifications
Using templates with outgoing email
The most important use of the Email Engine is sending notifications to users because AR System
uses it to send all notifications, not just email. You must install the Email Engine to send
notifications from the AR System server.
One major benefit of the Email Engine is the ability to notify users with a professional-looking
HTML-formatted email. The following figure illustrates a notification that a ticket was created and
sent to a user. In the notification email, users can then click a URL to open the ticket in a browser
and view additional details about the ticket.
Page 1570 of 4705
Home
An email notification sent by the Email Engine

If you choose Email as the delivery mechanism when creating a Notify filter or escalation, you can
send the following types of information in an email notification:
Text messages
Contents of selected fields (if the user being notified has the appropriate permission for
those fields)
Attachments (if an attachment field exists on the form)
Shortcut (if you select the Add Shortcut option in the Notify dialog box, a shortcut is as an
attachment to the email notification; this shortcut provides a link to the entry on the AR
System server.)
To send email notifications, you must install the Email Engine. The Email Engine can be installed
on a separate server from the AR System server processing the workflow. When you install Email
Engine, point to the AR System server you intend to use. For more information about using filter or
escalation workflow, see the Filter and escalation workflow considerations.
Note
If you create notifications using the Submit execute condition with join forms, the fields
returned in the notification message will not be populated. This is because there is no
Request ID with join forms during a Submit operation.

When the filter or escalation is triggered (for example, from a filter submit or modify action), the AR
System server logs a message containing the notification text (and, optionally, field contents) on the
AR System Email Messages form. The Email Engine then picks up the entries from the form,
processes them, and sends the email notifications to the designated user or group.
Page 1571 of 4705
Home
In a Notify action from filter or escalation workflow (see the following figure), you can select Email
as a notification mechanism. When you select Email, the bottom part of the window displays three
tabs Fields, Messages, and Templates that are used to define the configuration and contents
of your email message.
The Email Engine must be running to enable you to send email notifications. You can set some
configuration options in the Create Filter (or escalation) dialog box when you create a Notify filter or
escalation to customize your email.
To define a workflow to send email

1. Make sure that you have an outgoing mailbox configured with Default Outgoing Mailbox
set to Yes, or set Mailbox Name in the workflow to the configured outgoing mailbox.
Otherwise, you will not receive any notifications.
For more information, see Configuring outgoing mailboxes.
2. Create your Notification filter or escalation.
3. Click the If Action tab or the Else Action tab.
4. From the New Action list, select Notify.
The Notify Filter (or escalation) page of the Create Filter (or escalation) dialog box is
displayed. The fields required to define the Notify filter or escalation appear.
5. In the Text field, enter the text of the message.
You can use the Text list to insert fields from the current form or keywords into the text. The
field or keyword will be expanded when the notification is sent, to a maximum of 32 KB.
You can include sophisticated BMC Remedy AR System functionality in the text of an email
notification. The following figure demonstrates the use of a URL that performs a search that
goes directly to the request the user needs to view.
*The $Impact$ incident, <a href="http://polycarp/arsys/servlet/ ViewFormServlet?

server=polycarp&form=HD+Incident&eid=$Request ID$">$Request ID$</a>, has been
assigned to you.*
This URL appears in the notification email as a link that the user clicks to display the ticket in
a browser.
A direct access URL used in email notification
Page 1572 of 4705
Home
For more information, see URLs for forms and applications.

6. In the User Name field, enter the name of the users or groups to notify. For each recipient,
an entry is made in the AR System Email Messages form (see the following figure). You can
enter a maximum of 255 characters.
To specify one or more recipients, enter any of the following choices separated by hard
returns (the server evaluates each line separately) in the User Namefield:
AR System user logins
AR System groups
Email addresses
Include the email domain name if you are entering an email address (for example,
Joe.User@acme.com) or a keyword (for example, $USER$@acme.com). The order
in which these entries appear is the order in which the Email Engine searches for
addresses. If the contents of the User Name field do not match an existing User or
Group definition, the system interprets the field contents as a literal address and
sends the notification to that address by SMTP, IMAP, MAPI, or POP mail protocols.
This address can be an email address representing users who are not using BMC
Remedy AR System, an alias for a group, or an email address representing a
program.
Warning
Do not use group notifications as an email system for broadcast type items
because the server processes a notification for each member. An email alias
is more efficient. If you are using a field reference (for example, $Submitter
$), do not include the domain name as part of the notification because the
email address is being read from the Email Address field of the user's entry
in the User form.
Page 1573 of 4705
Home
7. Enter a value in the Priority field; ranges of 1 to 10 are acceptable. By default, emails are
sent out from the Email Engine in the order they were received, not in the order of priority.
8. To set properties in the EmailDaemon.propertiesfile so that the Email Engine sends
high-priority emails first and then lower priority emails, change the following property as
shown:
*SortMessages=true*
For more information, see Email daemon issues when AR System server stops .
9. From the Mechanism field, select Email.
The Fields, Messages, and Templates tabs are activated. For more information, see
Defining fields in email notifications and The Messages and Templates tabs.
10. Select the Add Shortcut check box to include the originating request as an ARTask
attachment in the email that is sent.
11. Save the filter or escalation.
Defining fields in email notifications

Use the Fields tab to define the subject line of the email and to indicate which fields (if any) to
include in the body of the email.
Subject line and fields in an email notification
Page 1574 of 4705
Home
To define the Fields tab

1. Enter the text that will appear in the subject line of the email.
Subject text can include the use of keywords, for example, $USER$. The field or keyword
will be expanded when the notification is sent. If you enter a field name in the Subject Line
field, the notification will contain the value of the field in the database. You can enter a
maximum of 255 characters.
2. Select which fields have the content you want to select in the email (in addition to the
notification text).
Note
The Request ID of entries from display or vendor forms are not returned in
notifications.
The options are:

None None of the fields is included with the notification.
All All of the fields in the request are included with the notification.
Selected Selected fields from the fields list are included with the notification.
Changed Only fields that have changed in the current transaction are included with
the notification.
Note
If you use a content template to format the email, the template will override
any of the options that are selected. For example, if an administrator
selected All, but the template only uses a few fields, only the fields in the
template appear in the email.
Make sure that all fields used as variables in header, footer, and content templates
are selected in the Include Fields list of the filter. (For more information, see Variables
.)
To be able to send the field contents, make sure that users being notified have the
necessary permissions. See Access control.
The order of fields included in an email notification is strictly based upon their
arrangement in the form view. Using their X and Y coordinates, the order of fields
begins top left to right, then down (in a zigzag-like pattern). Fields excluded from the
form's default view are randomly included at the bottom of the list. If a form includes
page fields, the pages are ignored. The order of fields included in the notification is
still based on their actual X and Y coordinates in the form.
3.
Page 1575 of 4705
Home
3. To include attachments in an email notification, select the attachment fields from the Fields
list.
Including attachments with notifications
Make sure the receiver of the notification has permission to the attachment field on the BMC
Remedy AR System form. The following figure shows that this notification will be sent to the
ticket assignee ($Assigned To$). To receive the attachment, the $Assigned To$ group
must have permission to the field, which the BMC Remedy AR System administrator defines
when the field is created.
After the notifications are sent, the message status changes in the Email Messages form
from Yes to Sent.
If you chose to delete Notification messages in your mailbox configuration, the notification
email entry is deleted from the Email Messages form. (See Deleting email notifications.)
The Messages and Templates tabs

The Messages and Templates tabs allow you to determine at run time which user the email came
from, which mailbox to use, which templates to use, and so on. The fields in these tabs are optional
. If you leave these fields blank, the settings relating to the mailbox entered in the Mailbox Name
field apply. Or, if the Mailbox Name field is empty, the default outgoing mailbox settings apply. The
default outgoing mailbox is the first mailbox created, or you can specify another mailbox in the AR
System Email Mailbox Configuration form.
Any entries in the fields in the Messages and Templates tabs will override the default settings. If
there are no entries in the Messages and Templates tabs, and no default mailbox exists, an error
message will be generated.
Defining messages in email notifications

Use the Messages tab to override your mailbox configuration settings for the Notify action. If you
leave these fields blank, the values in your notification email default to your current mailbox
configuration settings.
To define the Messages tab

1. In the Mailbox Name field, enter the name of the outgoing mailbox that you want to handle
the notifications if you do not want to use the default mailbox.
You can use a field or a keyword to substitute the mailbox name. This mailbox name should
correspond to a valid mailbox configured in the AR System Email Mailbox Configuration form
.
2. Enter information in the From, Reply To, CC, and BCCfields:
Page 1576 of 4705
Home
2.
If you make multiple entries in these fields, separate the entries by hard returns. The
maximum size of these fields is 32000 characters.
You can use the following entries in the fields:
AR System user logins
AR System groups
Email addresses--Include the email domain name if you are entering a user's
name (for example, Joe.User@acme.com) or a keyword (for example, $USER
$@acme.com).
A field
A keyword
The order in which these entries appear is the order in which the Email Engine
searches for addresses.
If you fill in these fields, the Email Engine populates the equivalent fields in the AR
System Email Messages form for the appropriate user name (the following figure).
However, if the information for these fields in the AR System Email Messages form is
supplied from the AR System Email Mailbox Configuration form (that is, a specified
mailbox, or a default mailbox that has already been configured), you need to display
and save the AR System Email Messages form before you see the entries.
3. In the From field, enter the name to be displayed to indicate where the mail is from.
If this field is blank and there are no entries in the From field on the Advanced tab of the AR
System Email Mailbox Configuration form for the specified mailbox, or for the default mailbox
, there will be no entry in the email to indicate who the email is from.
4. In the Reply To field, if you enter a group name, a reply will be sent to all the names in the
group.
If this field is blank, and there are no entries in the Reply To field on the Advanced tab of the
AR System Email Mailbox Configuration form for the specified mailbox, or for the default
mailbox, there will be no entry in the email to indicate any Reply To.
5. In the CC and BCC fields, if there are no entries in these fields or the Default Addressing
section of the Advanced tab of the AR System Email Mailbox Configuration form for the
specified mailbox, or for the default mailbox, no copies of the email will be sent.
If you specify multiple recipients in the User Name field (see the following figure), the name
or names specified in the CC and BCC fields on this form will appear only in the CC and
BCC fields of the AR System Email Messages form entry for the first user listed in this User
Name field. The permissions applied to the recipients of the CC and BCC fields will be the
same as those of this first listed user. This might be a security issue, especially if you list a
group name with some ambiguity about which is the first name on the list. You might list
names individually in the User Name field so that you have more control over the permission
status.
6. In the Organization field, enter a company name, an organization, a keyword, or a field
reference to a name that you would like to appear on the email.
Page 1577 of 4705
Home
Defining templates in email notifications

Use the Templates tab to define any templates to use in the email. If you leave these fields blank,
the values in your notification email default to your current mailbox configuration settings. You could
create workflow that substitutes a specially designed urgent template to alert a manager to the
email's importance. The following figure illustrates an email sent by the Email Engine if an urgent
ticket is created and no user is assigned (( 'TR.Impact' = "Urgent") AND ( 'Impact' !
= 'DB.Impact') AND ( 'Assigned To' = $NULL$ ) ).
An Urgent email generated by the Email Engine
Tip
A more "advanced" solution can use a Set Fields action to dynamically set template
values using data-driven workflow on a transaction basis. For example, a filter could read
a value from a hidden field on a form. By default, a notification would use a default header
template. But if a ticket was marked Urgent, workflow would substitute a value that uses
the Urgent header template instead. For more information, see Dynamically assigning
templates to outgoing email.
To define the Templates tab

1. In the Header, Content, and Footer fields, specify the names of the templates to use for a
header, content, or footer of the email notification.
You can enter the name of the template directly, or enter a field reference or keyword that
leads indirectly to a template name. The templates specified here must be stored in the AR
System Email Templates form, and the name must be the same as that entered in the
Template Name field of the AR System Email Templates form.
For more information about creating and using templates, see Creating and using email
templates
When you create a content template for_email notifications_, the variable format must
correspond to a field's database name and not the field label.
If you are using a content template for email notifications and you want to see the notification
text in the corresponding email, you must use the following variable format in the content
template:
Page 1578 of 4705
Home
*#$$AR Notification Text$$#*
To create a content template to show Status History when doing email notifications,
represent the Status History in the following formats:
*#$$Status History.New.USER$$# #$$Status History.Closed.TIME$$#*
These formats are based on AR System core field ID 7. The Status History strings shown
here as examples could also be displayed languages other than English.
Note
You cannot use BMC Remedy AR System keywords in content templates for
outgoing emails in notifications.
2. Click Add Action, and save your changes to the filter or escalation.
The system determines which templates to use in the following order:
a. The template entries in this tab.
b. The templates set as defaults for the mailbox entered in the Mailbox Name field of the
Messages tab of the Notify action dialog box.
c. The templates set as defaults for the default mailbox.
d. No templates are used.
If no template is used for the Content, the order of fields included in an email
notification is strictly based upon their arrangement in the form view. Using their X
and Y coordinates, the order of fields begins top left to right, then down (in a zigzag
pattern). Fields excluded from the form's default view are randomly included at the
bottom of the list. If a form includes page fields, the pages are ignored. The order of
fields included in the notification is still based on their X and Y coordinates in the form.
Dynamically assigning templates to outgoing email

The Email Engine gives developers more control over the content and format of email sent from AR
System. Content creation and formatting (including the use of graphics) are accomplished by
designing and storing the templates and images in the AR System Email Templates form. The
Email Engine then uses templates stored in this form to format outgoing email.
The Notify filter and escalation action integrates with Email Engine templates, allowing dynamic
template assignment. With templates stored as "data in a form," you can see them using workflow.
The Templates tab of the Notify action allows you to assign header, content, and footer templates.
As demonstrated in , you can hard-code these templates by using the template name. You could
also dynamically assign templates through workflow.
Page 1579 of 4705
Home
Suppose that the XYZ software company uses four HTML header templates (already stored in the
AR System Email Templates form) to provide a banner at the top of outgoing emails that are sent
when records are assigned. The templates are designed so that technicians can quickly tell if an
incident's impact is urgent, high, medium, or low.
The header template to use for an incident based on the impact
Impact
Template Name
Urgent
Header_Urgent.htm
High
Header_High.htm
Medium
Header_Medium.htm
Low
Header_Low.htm
You can create a data-driven approach to dynamically assign the correct template for the
appropriate impact.
The following procedure assumes your Email Engine is properly configured, your users have their
own email mailboxes set up, and you have created and stored your templates. This procedure
requires that you first create the following BMC Remedy AR System objects:
Two regular forms (XYZ Templates and XYZ Incidents)
Selection field on templates form
Hidden character field on the incident form
Filter using Set Fields and Notify actions
Search menu for template form (optional)
To dynamically assign templates to outgoing email

1. Create a regular form (for example, XYZ Templates).
2. Add a selection field to the XYZ Templates form.
This field should use the same attributes you plan to use to determine template assignment.
In this example, the Impact selection field attributes are used: Low, Medium, High, and
Urgent.
3. Create a character field (for example, Template Name) to store the value of the template to
be used.
4. (Optional) Attach a character field search menu that queries the AR System Email
Templates form as a further enhancement.
5. In a browser, open the XYZ Templates form in New mode.
6. Create the records for each Impact type, selecting the proper value for the Template Name
field.
Four records are created one for each of the impact values.
7. Create a regular form (for example, XYZ Incidents).
8.
Page 1580 of 4705
Home
8. Add a hidden character field (for example, Header Template) to the XYZ Incident form (the
following figure).
This field stores the name of the header template to be used with each incident when it is
created or modified.
A form with hidden fields
9. Create a filter to set the value for the Header Template field on the XYZ Incident form.
a. In the Basic tab, select XYZ_Incidents as the form.
b. Select Submit and Modify as the execute conditions.
c. Enter 'TR.Impact' != $NULL$ as the Run If qualification.
Here you want the filter to execute on Submit or Modify whenever the value of the
Impact field changes (that is, when the filter detects there is a new transaction value
in the Impact field).
10. In the If Action tab, create a Set Fields action with the following parameters:
a. Read the value for the field from the XYZ_Templates form.
b. Enter 'Impact' = $Impact$ as the Set Fields Run If qualification.
c. Select Header Template as the field name and $Template Name$ as its value.
With this workflow, the name of the proper template, based on its impact, is stored
with each incident. Here you define the filter to query the XYZ Templates form created
earlier where 'Impact' = $Impact$, and you set the value of the Header Template
field on the XYZ Incident form from the value of the template name field on the XYZ
Templates form.
11. On the filter, create a Notify action.
a. Place the variable $Header Template$ in the Header field.
b. Enter other parameters as needed, for example, $Submitter$ as the user name,
relevant text (including request ID of the ticket), and so on.
The result of this filter is data-driven automatic template assignment workflow.
12. In the XYZ Incidents form, create a new ticket (for example, for Joe User) and assign it an
urgent value.
The filter workflow executes and creates a new ticket. This workflow will also create an email
Page 1581 of 4705
Home
notification with the proper header template dynamically assigned based on its impact level.
When Joe User opens his email client, he receives the following email:
An email notification with the Urgent header template
You could enhance this with a content template used specially for urgent tickets.
Displaying date-time or numeric values in email notifications

When the AR System server sends data to a client with a different locale, the format for numeric
and date/time data might change to accommodate the client locale. For example, date/time or
numeric values stored on the AR System server have a decimal separator, but when this data is
relayed to a German client, the decimal separator is displayed as a comma.
Email notifications do not go through this client transition; therefore, the data in the notification is in
the same format as that stored on AR System server. This might result in incorrect date/time and
numeric values being displayed in a notification to different locales. For more information, see
Submitting email requests across different time zones .
Deleting email notifications

Using the AR System Email Mailbox Configuration form, you can configure your email system to
automatically delete notification messages from the AR System Email Messages form after they
have been successfully sent. This default setting reduces the number of records stored in your
message form.
Tip
Most of the time, you will use the AR System Email Messages form for troubleshooting the
Email Engine. When you first start using the Email Engine, you might not want
notifications automatically deleted to make sure they are sent to the expected users,
outgoing email is formatted correctly, and so on. But after your Email Engine is running
correctly, you should automatically delete email notifications, unless you are using email
Page 1582 of 4705
Home
templates to modify records; otherwise, your server can quickly fill up with email
notifications. If you configure the system to delete messages automatically, the Email
Engine will not permit you to modify records. The Email Engine includes a security feature
that checks the outgoing records to verify that incoming email with a modify action comes
from the same server.
To delete email notifications

1. In the AR System Email Mailbox Configuration form, open the entry of your outgoing mailbox
, and click the Advanced Configuration tab.
Option to delete outgoing notification messages
2. Set the Delete Outgoing Notification Messages field to Yes.

For more information, see Configuring advanced outgoing mailbox properties.
Using templates with outgoing email

Email templates can help you with outgoing mail from the Email Engine, for example, with email
generated from notification actions or escalations. A mail template exported with BMC Remedy
Developer Studio lists all the available field labels you could use, for example, in creating an
outgoing email. Replies to incoming email are not discussed in this section. For information, see
Sending professional looking reply emails.
You can use content templates with notifications or escalations to arrange the fields and values of
the entry that triggered the notification. Content templates used with notifications or escalations can
contain the following information:
Plain text
Variables
For example, the #$$AR Notification Text$$# variable is replaced by the text entered in the
Text Field of Notification group in BMC Remedy Developer Studio.
Core fields
For example, core fields are replaced with their actual values in the email that is sent out.
You use the following syntax with core fields:
#$$<DatabaseNameOfField>$$#
Page 1583 of 4705
Home
Form fields
You can use the fields on the form on which the notification action or escalation is based in
content templates. You use the following syntax with form fields:
#$$<DatabaseNameOfField>$$#
Content templates used with notifications or escalations cannot contain the following
information:
Keywords Keyword substitution in content templates is not implemented in Email Engine
7.0.00 and later. As a result, $USER$ or $DATABASE$ in a content template will not be
replaced with actual values.
Field IDs Field IDs are not substituted with entry values. As a result, #$$536870925$$#
is incorrect. Instead, you should use #$$Id_Integer$$# where Id_Integer is the database
name of the field.
The following example illustrates a content template for outgoing notifications:
#$$AR Notification Text$$#

CORE FIELDS:
----------------RequestId: #$$Request ID$$#
EmployeeName:#$$Name_Char$$#
Submitter:#$$Submitter$$#
ShortDescr:#$$Short Description$$#
LastModifiedBy:#$$Last Modified By$$#
Modified Date:#$$Modified Date$$#
Status:#$$Status$$#
StatHist-User:#$$Status History.New.USER$$#
StatHist-Time:#$$Status History.New.TIME$$#
StatHist-Time:#$$Status History.New.TIME$$#
Employee Info General Fields:
-----------------------------Employee Name : #$$Name_Char$$#
Employee Id: #$$Id_Integer$$#
Employee Salary in Decimal : #$$Salary_Decimal$$#
Employee Salary in Currency : #$$Salary_Currency$$#
Employee Gender : #$$Gender_Dropdown$$#
Employee Marital Status : #$$Marital Status_Radio$$#
Employee Interests: #$$Interests_Dairy$$#
Employee Skills : #$$Skills_CheckBox$$#
Employee Vacation Left : #$$Vacation_real$$#
PresentOrPermAddChoiceField : #$$PresentOrPermAddChoiceField$$#
PresentOrPermAddChoiceField : #$$PresentOrPermAddChoiceField$$#
Joining Details:
--------------JoiningDate_Date : #$$JoiningDate_Date$$#
JoiningDateTime_DateTime : #$$JoiningDateTime_DateTime$$#
Joininig Date_Time : #$$Joininig Date_Time$$#
Page 1584 of 4705
Home
XML outgoing content templates

You can specify outgoing content templates in XML format, as shown in the following example:

<Root>
<NotificationText>#$$AR Notification Text$$#</NotificationText>
<RequestID>ReqId: #$$Request ID$$#</RequestID>
<Submitter>Sub: #$$Submitter$$#</Submitter>
<ShortDescr>SD: #$$Short Description$$#</ShortDescr>
<EmpName>Emp Name: #$$name_char$$#</EmpName>
</Root>
HTML outgoing content templates

You can specify outgoing content templates in HTML format. HTML outgoing content templates can
contain graphic images. The following code is an example of HTML outgoing content template that
contains a GIF image:
<html>
</Root>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Lighthouse</title>
</head>
<body>
<p><font face="Arial Black"> #$$AR Notification Text$$# </font></p>
<p><img border="0" src="./images/lighthouse.gif" width="174" height="188"></p>
<p><font face="Arial Black"><b>Lighthouse</b></font></p>
<p><font face="Arial Black"> RequestID: #$$Request ID$$# </font></p>
<p><font face="Arial Black"> EmployeeName:#$$Name_Char$$#</font></p>
</body>
</html>
Sending outgoing email with the Email Messages form

Sending outgoing email in plain text
Sending outgoing email in HTML
Including attachments with outgoing email
Displaying advanced options for outgoing email
Determining message content of outgoing email
Character sets in outgoing mail
Adding extra custom headers to outgoing SMTP emails
Page 1585 of 4705
Home
You can use the AR System Email Messages form to send outgoing email, as shown in the
following figure.
You can type the message, or specify content templates to use in the body of the email. To send
email from the Email Engine, you must use a specific label/value pair syntax along with the Action
label in the body of the email.
You can add the content from the From, To, Subject, etc. fields to the body of the email. You can
insert a string value of the field that you want to add on the AR System Email Messages form. For
example, if you want to insert the email address from the From field in the body of the email, you
must insert the #$18086$# variable, where 18086 is the ID of the From field.
You can include attachments with your email using the Attachments tab. From the Advanced
Options tab, you can use a template, substitute variables, or an alternate attachment as your body
content. (For information, see Displaying advanced options for outgoing email.)
Warning
When sending HTML messages, any content in Plain Text Body tab is ignored. To send
plain text messages, make sure that all the required content is in the Plain Text Body tab
and that the HTML Body tab is empty.
Page 1586 of 4705
Home
Sending outgoing email in plain text

You can use the Email Engine to send outgoing email in plain text. Plain text email can include the
results of queries, submissions, or modifications to entries contained on your AR System server.
These emails can be formatted using templates that specify the layout of a message in plain text,
HTML, or XML.
To send outgoing email in plain text

1. Open the AR System Email Messages form in New mode in a web client (as shown in the
following figure).
Tip
To view the AR System Email Messages form in a browser, use this syntax: http:///
arsys/forms//. For more information, see URLs for opening forms and applications.
2. From the Mailbox Name menu, select an outgoing mailbox to use for your email message.
The settings in the AR System Email Mailbox Configuration form for the specified mailbox
will be used, unless overridden by entries in the AR System Email Messages form. If you
leave this field empty, the default outgoing mailbox will be used. (For more information, see
Configuring outgoing mailboxes.)
3. Select Outgoing from the Message Type list.
4.
Page 1587 of 4705
Home
4. Click the Message tab and fill in the header information.

The From, Reply To, Organization, To, CC, and BCC fields will be populated automatically
when you enter the mailbox name if they have been configured in the AR System Email
Mailbox Configuration form. You can override these settings here.
a. In the To field, enter the name of the user you are sending the email to.
b. Enter other information as needed, for example, an organization.
5. Enter a subject line for your email in the Subject field.
6. Optionally, enter a priority number between 1 to 100 in the Priority field.
Use the following table to determine what value to use in the email message within AR
System to get the desired Microsoft Outlook priority.
Email Engine priorities mapped to Microsoft Outlook priorities
Email Engine Priority
Microsoft Outlook Priority
Normal
High importance
High importance
Normal (default)
Low importance
...
...
100
Low importance
By default, emails are sent out from the Email Engine in the order they were received, not in
the order of priority. But you can set properties in the EmailDaemon.properties file for the
Email Engine to send high priority emails first and then lower priority in that order.
Use the following properties:
To ignore priority (default):
*SortMessages=false*
To use the priority:
*SortMessages=true*
For more information about using the EmailDaemon.properties file, see Email
daemon issues when AR System server stops .
7. Click the Plain Text Body tab and enter your message text.
There are no syntax requirements for typing "plain" text in your outgoing message. However,
any label/value pairs that you include must follow their specific syntax. For more information,
see Creating and using email templates
To add an attachment, see Including attachments with outgoing email.
Page 1588 of 4705
Home
To send the email with a template other than the default templates for the specified
mailbox, see Using the Templates tab.
To add an attachment alternative to be used for the content of your email instead of
typing content in the body panes, or using a template, see Using the Variable
Replacement tab.
8. Click Send to send the mail from the outgoing mailbox to the user.
Sending outgoing email in HTML

You can use the Email Engine to send outgoing email messages that include the results of queries,
submissions, or modifications to entries contained on your AR System server. These emails can be
formatted using templates that specify the layout in plain text, HTML, or XML.
RTF field support in BMC Remedy Email Engine

BMC Remedy Email Engine supports Rich-text-formatting (RTF) formatting applied to the text in the
email messages. Also, you can see the attached images inline with the text.
Following are the limitations for the outgoing email notifications in BMC Remedy Email Engine to
support RTF functionality:
The number of attachment fields in a mail must match the number of attachments.
While creating the notification filter from the Fields list section, select all the attachment
fields from the attachment pool associated with the RTF field.
For using RTF fields with images, embedded images can only be sent by using the
attachment pool with the RTF field.
For attachments in the outgoing mails,
Do not change the text in the Description field on Image options dialog box.
Do not change the content of the alt and title attributes, because these are
auto-generated by the mid tier, and will be used by the Email Engine for finding the
name of the image.
Do not copy-paste the images. You must insert the images using the image option on
the RTF field. Otherwise, the images might not appear inline with the text.
To send outgoing messages in HTML

1. Open the AR System Email Messages form in New mode to create an outgoing message.
For sample contents of an outgoing message, see Sending outgoing email with the Email
Messages form.
2. Click the HTML Body tab.
3. Enter HTML content, as shown in the following example:
Server: polycarp<BR>
Login:Francie Frontline<BR>
Password <input type="password" name="Password" size="15" maxlength="14"> <BR>
Key:1234<BR>
Page 1589 of 4705
Home
Action: Modify<BR>
Form:TestSecurityForm<BR>
Request ID: 000000000000003<BR>
Assigned To <input type="text" name="!4!" size="20" value="Assignee"> <BR>
Short Description <input type="text" name="!8!" size="40" value="Enter a short
description"> <BR>
Status
<input type="radio" value="New" name="!7!"/> New
<input type="radio" value="Assigned" name="!7!" /> Assigned
<input type="radio" value="Fixed" name="!7!"/> Fixed
<input type="radio" value="Rejected" name="!7!"/> Rejected
<input type="radio" value="Closed" name="!7!"/> Closed
<BR>
In addition to HTML formats, any label/value pairs that you include must follow specific
syntax requirements. For more information, see Creating and using email templates
For how to define HTML, especially input type controls, see any standard HTML reference
book or reputable online source ( http://www.w3.org/ ). Additional HTML examples are
demonstrated in Sending modify instructions in HTML.
The Email Engine generates the email, as shown in the following figure.
An outgoing email in the HTML format
This outgoing email contains the following HTML input features:

Password control field Users become nervous about sending passwords in clear
text. For security, this HTML message includes a Password control field as an input
type. When the user enters their password, the text is masked; asterisks appear
instead of the typed symbols or letters, as shown in the following figure.
A Password field with encryption
Page 1590 of 4705
Home
Text input fields Users modify the contents of the Assigned To and Short
Description fields by using text input fields.
Radio buttons Users modify the status by selecting an input type Radio control
field. They can select only one radio button option.
For information about encoding user-defined markup text in outgoing email messages
, see Encoding user-defined text in outgoing HTML email .
Including attachments with outgoing email

Attachments are sent with an email using the AR System Email Messages form and the AR System
Email Attachments form. The AR System Email Attachments form stores attachments for incoming
and outgoing emails. It also stores attachments for templates, such as a graphic for an HTML
template. The system associates the attachment with a specific email in the AR System Email
Association form.
Note
Having a large number of records in the email messages and email attachment forms
might degrade the performance of the Email Engine.
Also in this topic:

#Modifying an attachment
#Deleting an attachment
To add attachments to your email

1. In the AR System Email Messages form, click the Attachments tab.
2. Click Add Attachment to open the AR System Email Attachments form.
3. Select Email from the Type list.
4. Right-click in the attachment pool and choose Add from the menu.
5.
Page 1591 of 4705
Home
5. In the Add Attachment dialog box, navigate to the appropriate location and open the file.
The file is added to the list of attachments. If you are using a Windows system, you can also
drag and drop a file into the attachment pool.
6. Enter a name for the Attachment in the Attachment Name field.
If you do not specify a name, the system will see the attachment by its file name and location
. To change the name:
a. Select the item in the attachment pool, and click the edit button in the Attachment
Name field.
The name of the attachment is displayed in the Attachment Name field.
b. Edit the file name as needed.
7. Click Save.
To add previously saved attachments to email

1. In the Attachments tab of the AR System Email Messages form, click the arrow next to the
blank field at the bottom of the pane.
2. Select the attachment.
3. Click the Add Existing button.
Your attachment is added to the list in the attachment pool.
When you send or save your email, the email and the attachment are associated through the
AR System Email Association form. The system will assign the association a unique ID.
Modifying an attachment
Use the following procedure to modify attachments in outgoing email.
To modify attachments
1. Click the Attachments tab in the AR System Email Messages form.
2. Select the attachment you want to modify.
3. Click the Modify Attachment button to open the AR System Email Attachments form.
4. Click Search to locate the attachment.
The attachment appears on the attachment list.
5. Modify the attachment as required. You can also modify the Attachment Name.
6. Click Save to save your modification.
Deleting an attachment
Use the following procedure to delete attachments in outgoing email.
To delete attachments
1. Click the Attachments tab in the AR System Email Messages form.
2. Select the attachment you want to delete.
3.
Page 1592 of 4705
Home
3. Click Delete Attachment to open the AR System Email Association form.

4. Close this form.
5. Click the Refresh Table button to refresh the table in the Attachments tab of the AR System
Email Messages form.
The attachment is deleted from the list.
Displaying advanced options for outgoing email

For outgoing messages, you can include advanced options like replacing variables. You can also
view information and error messagess of the outgoing message. To display the Advanced Options,
Message Information, and Errors tabs, perform the following tasks:
To display advanced options
Advanced Options tab
Using the Templates tab
To add templates to outgoing email
Using the Variable Replacement tab
To replace a field value using a variable replacement
Using the Attachment Alternatives tab
To add an attachment alternative
Message Information tab
Errors tab

1. Create an outgoing message.
2. Select Yes in the Display Advanced Options field of the AR System Email Message form.
3. Select one of the advanced option tabs: Advanced Options, Message Information, or Errors.

The Advanced Options tab lets you replace templates, add variables, or use alternative
attachments.
Using the Templates tab

The Templates tab enables you to include a content, header, or footer template with your outgoing
email:
Content templates replace the body of the email so that you do not have to enter anything in
the body tab of the AR System Email Message form.
The content can be associated with a specific form and contain the fields and their
corresponding values relating to a specific record. You can create these templates in a text
editor or export them using BMC Remedy Developer Studio.
You can also specify actions to be performed when the Email Engine parses contents of the
email. The content template can also contain formatting instructions.
Page 1593 of 4705
Home
Header and footer templates are used to place lines of text or graphics on an outgoing
message. If header and footer templates are specified in content templates as a label/value
pair, they will be applied to the email reply.
All the templates you use here must be previously stored in the AR System Email Templates form.
If you leave Template fields blank, the system uses the default templates for the mailbox in the
Mailbox Name field, or it uses the default mailbox and its settings if no Mailbox Name is entered.
The template specified here will override those configured for the specified mailbox, or the default
mailbox.
For information about configuring your outgoing mailbox, see Configuring outgoing mailboxes.
To add templates to outgoing email

1. In the outgoing message, display the advanced options.
2. Click the Advanced Options tab, and then click the Templates tab.
3. Select templates from the relevant menu lists, or enter the name of a template as defined in
the AR System Email Templates form.
The AR System Email Messages form Advanced Options, Templates tab
(Click the following image to expand it.)
Using the Variable Replacement tab

The Variable Replacement tab (the following figure) enables you to replace any variables in the
template with a value at the time of execution. This applies only to the specific outgoing email and
the templates specified in the Templates tab.
The AR System Email Messages form Advanced Options, Variable Replacement tab
Page 1594 of 4705
Home
You can use the Field Values field or the Qualification field with a particular form to retrieve
required data and substitute it in the email.
To replace a field value using a variable replacement

2. Fill in header information.
3. Enter Yes in the Display Advanced Options field.
4. Click the Advanced Options tab.
5. Click the Templates tab.
6. Select a content template.
For example, this content template (which modifies an entry) uses the following label/value
pairs:
*Server: polycarp
Login:
Password:
Key:
Action: Modify
Form: TestSecurityForm
Request ID: \[$$#$$Request ID$$#$$\]
Submitter !2!:
Short description !8!:
This template includes a variable value for the Request ID field by replacing the Request ID:
00000000001 label/value pair with Request ID:[HTMLUATarsadministering1030:$$#$$
Request ID$$#$$].
7. Click the Variable Replacement tab.
8. Enter a value for a variable in the template in the Field Values field, as shown in the
following figure.
For example, with the following variable in your template:
Page 1595 of 4705
8.
Home
Short Description !8!: #$$Short Description$$#
you would enter in the Field Valuesfield:
!Short Description!: Create entry for new hire.
This value will then be substituted for the variable when the outgoing email is sent.
When an entry is created in the Email Messages form for the outgoing message, the Field
Values field of the Variable Replacement tab is populated with the database name of the
field and its value in the entry. This database name is matched with the database name that
is specified within #$$...$$# in the content template, and a substitution is made accordingly.
So, make sure to use the exact database name in the content template delimited by #$$...$$
#.
If you create an outgoing email from the Email Messages form instead of using a notification
or escalation, then you can use the field ID in the Field Values field of the Variable
Replacement tab. In the same tab, you can specify the form name and qualification criteria.
As a result, when the outgoing email is sent, the qualification criteria is evaluated, entries
that match the criteria are retrieved, and the values of the entries are substituted for the field
IDs in the Field Values field.
If a template is specified in the Templates tab and the template contains field IDs, then those
field IDs are substituted with the values of field IDs in the field value of the Variable
Replacement tab of the Email Messages form.
9. Enter the name of the server on which the form resides.
10. Enter the name of the AR System form to which these values apply.
11. Enter any access information necessary in the AR System Server TCP Port field and the
AR System Server RPC Number field.
12. Enter a qualification in the Qualification field to search for the Request ID of a record on
which you want to perform an action (the following figure).
This action will be specified in a Content template.
The AR System Email Messages form Advanced Options, Variable Replacement tab
Page 1596 of 4705
Home
13. Send the outgoing email.

The Email Engine searches the specified form for the record, and then it substitutes the
Request ID parameter in the Content template with the Request ID value (00000000001)
found with the query (the following figure).
An email messages with the qualification replaced
You can also make this static in the Content template by specifying Request ID:
00000000001 instead of the variable Request ID: [HTMLUATarsadministering1030:$$#$$
Request ID$$#$$], but using the Variable Replacement feature allows more flexibility.
Using the Attachment Alternatives tab

The AR System Email Messages form Advanced Options, Attachment Alternatives
Page 1597 of 4705
Home
The Attachment Alternatives tab enables you to add the content of your email as a plain text or
HTML attachment, instead of typing it into the Body field in the Message tab. The contents of the
attachment appear in the body of the email.
To add an attachment alternative

2. Fill in header information.
3. Enter Yes in the Display Advanced options.
4. Click the Advanced Options tab.
5. Click the Attachment Alternatives tab.
6. In the attachment pool, perform the following tasks:
a. Right-click an attachment field corresponding to the contents of the attachment.
b. Select Add to open the Add Attachment dialog box.
c. Select a file.
7. Select an encoding for the attachment or leave the field empty to use the system default.
The system needs to be able to read and parse the contents of these attachments when it
creates the outgoing email. You can attach only one of each type of alternative attachment
to a message form. These attachments are stored as part of the message in the message
form.

The Message Information tab records status information about the email, such as the Message ID,
the dates sent and received, and if there is any delay in sending the message.
Errors tab
The Errors tab enables users to view error messages if an email is not sent correctly. For example,
if the To field has an invalid character like a space, then an error is generated and is viewable in
the Error tab.
Page 1598 of 4705
Home
Determining message content of outgoing email

When sending an email message, the message content is determined according to the following
sequence:
1. If you supply a template, the system uses it as the message body, and uses the following
rules for variables:
If you supply an attachment in the Values attachment field of the Attachment
Alternatives tab of the AR System Email Messages form, the attachment will be used
to determine the values for variables contained in the template.
If you do not supply an attachment in the Values attachment field, but you supply
information in the Field Values or a qualification in the Qualification field of the
Variable Replacement tab of the AR System Email Messages form, the information
will be used to determine values for variables contained in the template.
If you do not supply field values, but your content template contains a query to obtain
information to substitute in the email, the query information will be used to generate
the message. For query information to be used, a form, server, and qualification must
be supplied. If any one of these items is missing, the message creation will fail.
Note
In terms of performance, a query against another server is more expensive
than a query against the current server. If you are going to send many
emails based on information queried from another server, set up an email
system on another server.
If none of these points is true, the system uses the template as is.
2. If you do not supply a template, but attach a file (HTML or plain text, or both) to the Content
attachment fields in the Attachment Alternatives tab of the AR System Email Messages form,
the system uses these attachments as the content.
3. If none of the items in the previous steps is supplied, the system uses the contents of the
Body fields in the Message tab of the AR System Email Messages form for the body of the
email (HTML or plain text, or both).
Character sets in outgoing mail

The JavaToMimeMapping.properties file contains a list of character set conversions for your
outgoing mail. You can find this file in the Email Engine installation directory.
Adding extra custom headers to outgoing SMTP emails

Email Engine allows you to specify a custom header for outgoing SMTP messages using the
AdditionalMailHeaders property. See Controlling BMC Remedy AR System through email . You
can also provide additional custom headers to an outgoing message.
Page 1599 of 4705
Home
To add an extra custom header

1. Create an entry in the EmailDaemon.properties file as follows:
AdditionalMailHeaders=X-Loop-Detect,
<customHeader>
2. Restart the Email Engine service.

3. Create an outgoing message using the AR System Email Messages form.
a. Specify the values for mandatory fields and add all the other information you want to
send.
b. In the Subject field, add the following lines:
<subjectName>
X-Loop-Detect: <headerValue>
<customHeader>: <headerValue>
c. Send the email message.

To add multiple custom headers to emails, specify the comma-separated headers in
EmailDaemon.properties, and specify their values when creating outgoing
messages.
Note
Information about custom headers is present in the
EmailDaemon.properties file, which cannot be updated dynamically.
Hence, you can not provide additional headers for a message dynamically.
Sending professional looking reply emails

One of the major benefits of the Email Engine is the ability to send email messages that are
professional looking.
Adding a header
Creating a result template for reply email
Creating result templates for outgoing email
Creating content templates for outgoing email
Creating status templates for outgoing email
Page 1600 of 4705
Home
Email messages consist of header, content, result, and (optionally) footer components. Each
component can be text or HTML. Usually, header and footer templates are used as defaults in the
outgoing mailbox, and content templates are used in outgoing messages or filter notifications.
A reply email in ASCII format
Imagine a user sends an incoming email to search for all urgent open tickets. Without the use of
header or content templates, the Email Engine returns the following reply email.
This email, as illustrated in the following figure, is a simple ASCII-format message generated by the
Email Engine. It is functional but quite plain.
The following figure shows the same outgoing email generated by the Email Engine, but this time
configured to use an HTML header template and an HTML result template when replying.
A reply email with HTML templates
Page 1601 of 4705
Home
The difference between the two outgoing emails is evident. The ASCII email contains all the
important details, but is plain. Using HTML templates, outgoing email conveys the same information
but is much more inviting to read.
Note
Although most mail clients can display HTML, there might be some clients that cannot
display HTML. Assess which mail clients are supported in your organization before
implementing a pure HTML solution.
Adding a header
Adding a header to outgoing email messages can enrich the user experience. With a basic
knowledge of HTML, you can make your messages look professional. Adding a header requires
creating a template, and then configuring the outgoing mailbox to use the new default header
template.
Note
To add a footer template, you would use the same steps as described in the following
procedure.
To add a header template

1. Create a header image for the banner in your outgoing message.
2. Create an HTML header file (header_default.html ) that contains the LogoTriangle.gif
bitmap.
The following sample HTML header file includes the bitmap:
<html>
Page 1602 of 4705
Home
<head>
<title>Default Header</title>
</head>
<body>
<table width="816" bgcolor="#0069A5">
<tr>
<td vAlign="top" width="196"><img src="LogoTriangle.gif" width="200" height="90"
lowsrc="LogoTriangle.gif"></td>
<td vAlign="top" width="608">
<div align="center">
<p> </p>
<p><b><font face="Geneva, Arial, Helvetica, san-serif" size="4" color="white"
Email Engine Demo </font></b></p>
</div>
</td>
</tr>
</table><hr>
</body>
</html>
This HTML code creates the following header.

A header template
3. Create an entry in the AR System Email Templates form for your header template:
a. Select HTML as the template format, enter Header Default as the template name,
and add header_default.html as an attachment.
b. Click Add Attachment in the Template Attachments tab.
4. In the AR System Email Attachments form, select Template as the type, enter
LogoTriangle.gif as the attachment name, add LogoTriangle.gif as an attachment, and
save the email attachment entry.
5. In the AR System Email Templates form, click Refresh Table to display the bitmap template
attachment, and save the template entry.
For more information, see Adding attachments to HTML templates.
6. In the AR System Email Mailbox Configuration form, open the outgoing mailbox entry.
7. Under the Advanced Configuration tab, specify Header Default as the default header
template.
8. Send a sample outgoing email. The following figure displays the email sent by the Email
Engine to your mail client.
An outgoing message with a header template
Page 1603 of 4705
Home
Creating a result template for reply email

If you do not specify a result template for reply email, the Email Engine uses a default formatting for
the returned data. To make this information easier to read, you can format this data by creating a
result template with field variables. To allow users to see the formatted results of their email action,
you can easily create a result template in a text editor. The following result template is a simple
example that formats the returned text with field variables:
XYZ Corporation
#$$Submitter$$# has successfully created a #$$Status$$# ticket.
Ticket Number: #$$Request ID$$
#$$Assigned To$$# has been assigned to your request.
Problem Description: #$$Short Description$$#
Using an HTML result template (as shown in the following figure) gives you greater control over the
appearance of the returned data and makes the return email look much more professional. For
more information about data formats and labels, field variables, and result templates, see Creating
and using email templates
The following example walks you through the procedure for using result templates with outgoing
email. The example is simple but complete, and you can easily add more functionality.
To use HTML result templates with outgoing email

1. Make sure the Email Engine is properly configured to send reply results. For more
information, see Configuring BMC Remedy Email Engine for replying with results .
2. Create a result template for your reply email. The following figure is an HTML result template
designed for this exercise. The fields that are referenced in the result correspond to fields
used in the HD Incident form. The variables for field values must use the field name (its
database name) as the variable name, not the field ID.
An HTML result template
Page 1604 of 4705
Home
3. Create an entry in the AR System Email Templates form for your result template.
4. Export an email template from the HD Incident form.
For more information, see Exporting mail templates.
5. Create a new email in your email client and address the email to the Email Engine inbox
account.
6. Copy and paste the contents of the exported email template into the new email, and then fill
out the required information for the template.
7. Add the result template parameter to the email, and then make sure you filled in all the
required fields.
Your email should look like the following example:
#
# File exported Tue Sep 28 17:01:33 2004
#
Schema: HD Incident
Server: POLYCARP.eng.bmc.com
Login: Demo
Password:
Action: Submit
Result: Results Template Default
# Values: Submit, Query
Format: Short
# Values: Short, Full
Last Name+ !536870916!: Stamps
First Name !536870917!: Ivan
Location !536870918!: Sunnyvale
Email Address !536870920!: stamps3@eng.bmc.com
Phone !536870919!: 408-555-1212
Category !536870913!:
Networking Type !536870914!:
VPN Item !536870915!: Cisco
Problem Summary ! 8!: Need to install VPN Client.
Status ! 7!: New
# Values: New, Assigned, WIP, Resolved, Closed
Submitter ! 2!: $USER$
Impact !536870927!: Low
# Values: Low, Medium, High, Urgent
8.
Page 1605 of 4705
Home
8. Send the email to the incoming mailbox.

If you properly configured the Email Engine and included all the required fields and the result
template in your email, you should receive a reply email (as shown in the following figure)
that includes the results of your submission.
A reply with results email
For more information, see Email reply using result templates in HTML format .
Creating result templates for outgoing email

You can use XML when creating templates for outgoing email. The following example uses XML
format when creating a result template. The results from a query are returned in XML.
To use XML with outgoing email

1. Create a template file (for example, result_employee.xml) using XML format:
<?xml version="1.0" encoding="UTF-8" ?>

<Employee name="#$$Employee Name$$#">
<age>#$$Age$$#</age>
<salary>#$$Salary$$#</salary>
<address>
<street>#$$Street$$#</street>
<city>#$$City$$#</city>
<state>#$$State$$#</state>
<zip>#$$Zip$$#</zip>
</address>
</Employee>
This simple example contains an XML attribute ( name), an attribute value (#$$Employee
Name$$#), and several elements (age) with their values (#$$Age$$#).
Page 1606 of 4705
Home
Tip
You can easily validate your XML file by displaying it in a browser.
2. Add the template as a text template to the AR System Email Template form.
The name of this XML template is employee. For information, see Storing templates in the
AR System Email Templates form.
3. Send an incoming email to the Email Engine that queries the server and returns the results
using the XML template, for example:
Action:Query
User: Demo
Server:polycarp
Schema:employee
Result Template:employee
Employee Name \! 536870913\!:John Doe
This email specifies that the employee XML template be used in the outgoing email to return
the results of the query.
The following figure displays the outgoing email generated by the Email Engine.
A reply from the Email Engine using an XML template
Observe how the query results of this email are displayed in XML format. If your outgoing
mailbox is configured to include an HTML header, the resulting email (combining an HTML
header template with an XML result template) would no longer be displayed in purely XML
format.
Page 1607 of 4705
Home
Creating content templates for outgoing email

Rather than entering raw HTML into your outgoing email, you can create HTML templates to
include content similar to header templates. For example, if you need to send a questionnaire
seeking input from users, you can include HTML fields in the email message so that users can
enter input using text boxes, radio buttons, and so on, instead of as plain text.
For information about encoding user-defined markup text in outgoing email messages, see
Encoding user-defined text in outgoing HTML email .
To add content to an outgoing email message

1. Create an HTML template that you will include in your outgoing message.
The following sample HTML template defines font styles and colors in the <BODY> tag. You
can include embedded styles in your content file, but the Email Engine does not support
linking your HTML template to a cascading style sheet.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">

<HTML>
<HEAD>
<TITLE>BMC Picnic</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#FF0000" VLINK="#800000" ALINK="#
FF00FF" BACKGROUND="?">
<i><font color="blue" face="Arial, Helvetica"> <h1>BMC Company Picnic</h1></font>
</i><hr>
<i><font color=#777777 face="Arial, Helvetica"><h3>Are you coming to the BMC
company picnic?
<input type=radio name="F7">Yes</radio>
<input type=radio name="F7">No</radio></font></i><br/>
<i><font color=#777777 face="Arial, Helvetica">Number of additional guests <
input type=text name="Num_Guests" size=2></font></i></input>
</BODY>
</html>
2. Create an entry in the AR System Email Templates form for your content template, for
example, BMC_Picnic_Invite.html.
3. Open the outgoing mailbox entry in the AR System Email Mailbox Configuration form.
4. Under the Advanced Configuration tab, specify BMC_Picnic_Invite.html as the content
template.
5. (Optional) Include a header or footer template.
Otherwise, your email will use any default templates configured for your outgoing mailbox.
6. Send a sample outgoing email.
The following figure displays the outgoing email sent by the Email Engine to your mail client.
An outgoing message with the header and HTML content templates
Page 1608 of 4705
6.
Home
Creating status templates for outgoing email

When an error occurs while executing instructions from an incoming email, the Email Engine
automatically generates an outgoing email with relevant status information. This system-generated
email is simple, containing only basic information, for example, the type of instruction that failed,
error messages, and so on:
Instruction: Query
Instruction Number: 1
Instruction Template:
Message Type:
Message Number: 24
Message Text: No matching requests (or no permission to requests) for qualification
criteria.
Appended Text: TestSecurityForm
By using an HTML status template, your outgoing email can look more professional as well. The
following procedure shows you how to create an HTML template that formats status more
attractively.
To include status templates with outgoing email

1. Create a status template.
The following sample HTML template is created to display status:
<html>
<head>
<title>Status Template</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso- 8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table width="75%" border="1" cellspacing="1" cellpadding="3">
<tr>
<td colspan="4">
Page 1609 of 4705
Home
<div align="center"><b>Your request to the AR Server returned the following

error. If you have questions, contact your <a href="mail%20to:%20stamps1@
eng.bmc.com">Administrator</a>.</b></div>
</td>
</tr>
<tr>
<td width="12%">Error Number</td>
<td width="28%">#$$ActionStatus.Number$$#</td>
<td width="18%">Message 1</td>
<td width="42%">#$$ActionStatus.Text$$#</td>
</tr>
<tr>
<td width="12%">Error Type</td>
<td width="28%">#$$ActionStatus.Type$$#</td>
<td width="18%">Message 2</td>
<td width="42%">#$$ActionStatus.AppendedText$$#</td>
</tr>
</table>
</body>
</html>
This HTML template defines a simple table with two rows for the error number and error
types. It also includes an email address that users can respond to if they have questions. Of
course, your HTML template could include color, special fonts, and so on.
2. Create an entry in the AR System Email Templates form for your status template, for
example, Status_default.html.
3. Open the outgoing mailbox entry in the AR System Email Mailbox Configuration form.
4. Under the Advanced Configuration tab, specify Status_default.html as the status template.
5. (Optional) Include a header or footer template.
The sample email shown in the following figure uses the default header template configured
for the outgoing mailbox.
6. Send an incoming email to the Email Engine that will generate an outgoing status email, for
example, a query that returns no records.
The following figure displays the outgoing status email generated by the Email Engine.
An outgoing message with the default header and HTML status templates
Page 1610 of 4705
Home
Including incoming body in outgoing email

By default, outgoing error messages generated by Email Engine do not contain the body of the
original incoming email request. To help users troubleshoot failed email requests for submit, modify
, and query actions, use the variable #$$ORIGINALMAIL$$# to include the incoming body in
outgoing messages.
To include the incoming body in outgoing email

1. Add the variable #$$ORIGINALMAIL$$# to a status template.
2. Associate the status template with your system's outgoing email messages.
See Using status templates with outgoing email .
When Email Engine generates an error message based on a status template containing the
variable #$$ORIGINALMAIL$$#, it replaces the variable with the body of the original email
message.
For example, a user submits an email request that includes this information:
Schema: HD Incident
Server: reepicheep.eng.bmc.com
Login: Demo
Password:
Action: Submit
Description !8!: My mouse isn't working.
StatusTemplate: MyStatusTemplate
The status template associated with the user's request, MyStatusTemplate, includes these
label/value pairs:
Error Number: #$$ActionStatus.Number$$#

Error Type: #$$ActionStatus.Type$$#
Error Text: #$$ActionStatus.Text$$#
Error Appended Text: #$$ActionStatus.AppendedText$$#
Error Appended Text: #$$ActionStatus.AppendedText$$#
Page 1611 of 4705
Home
Original Mail: #$$ORIGINALMAIL$$#
If the user's submission fails, Email Engine generates an error message based on
MyStatusTemplate. Because the value of the Original Mail label in that template is the
variable #$$ORIGINALMAIL$$#, the original email body is put in place of that variable in the
error message:
Error Number: 307

Error Type: 2
Error Text: Required field (without a default) not specified
Error Appended Text: 2
Original Mail:
Schema: HD Incident
Login: Demo
Password:
Action: Submit
Description !8!: My mouse isn't working.
Including incoming attachments in outgoing email

To include attachments to incoming requests in outgoing error messages, the associated status
template must contain the variable #$$ORIGINALMAIL$$#, and the incoming request must contain
the following information:
Correct login, password, server, and schema (form name) values
IDs of the attachment fields
Names of the attached files
For example, a user submits an email request that includes this information:
Schema: HD Incident
Login: Demo
Password:
Action: Submit
Description !8!: I need a new mouse for my computer.
!536880912!: file1.txt
!536880913!: file2.txt
Using that information, Email Engine gets the appropriate HD Incident form from the specified
server and then gets the attachment information from the specified attachment fields. If the HD
Incident form does not contain field 536880913, Email Engine cannot get file2.txt. Thus, if the
submission fails, the user receives an error message that includes the original email message and
only one attachment, file1.txt.
Page 1612 of 4705
Home
Encoding user-defined text in outgoing HTML email

You can encode user-defined markup text in outgoing email messages by enclosing the text within
the following markers:
[#ENCODE_HTML_START#]
...
[#ENCODE_HTML_END#]
Important
You can only specify these markers directly in the HTML Body tab, or in an HTML content
template, or both.
If you include user-defined markup text in outgoing HTML messages, the recipient client does not
render the text as HTML. Instead, it displays the text as is.
For example, consider that you enter the following markup in the message body:
<html>
<body>Leave application <br> Approved <br>
<Timespan="app.calendar" string=$today$/>
</body>
</html>
When the message is received, the email client attempts to render the text as HTML. The output
appears as follows:
Leave application
Approved
You need to indicate that the following text is user-defined markup, which should not be rendered
as HTML content:
To indicate user-defined markup, construct the message body as follows:
<html>
<body>Leave application <br>
Approved <br>
[#ENCODE_HTML_START#] <Timespan="app.calendar" string=$today$/>
Page 1613 of 4705
Home
[#ENCODE_HTML_END#]
</body>
</html>
When the message is received, the email client correctly renders the user-defined markup as
follows:
Leave application
Approved

This section provides the following information and instructions for sending email messages to the
AR System server by using the Email Engine:
How incoming email works
Sending a query instruction to the Email Engine
Sending a Submit instruction to the Email Engine
Sending a Modify instruction to the Email Engine
Creating workflow to modify requests
Searching for an entry to modify
Displaying advanced options for incoming email
Syntax for incoming email
Syntax for variables in templates
Character sets in incoming mail
How incoming email works

The following figure presents a sample scenario that demonstrates how the Email Engine receives
incoming email.
How the Email Engine receives incoming email
Page 1614 of 4705
Home
1. In the XYZ Company, the AR System administrator has configured the Email Engine to
receive email submissions by using email as a client to the AR System server. To make
email easier to use, he has created and sent to his user base several email templates that
cover typical work situations, for example, submitting entries to the HD Incident form, and
querying the status of their tickets.
2. Joe User cannot print his document because his printer has a paper jam that he cannot fix.
He opens one of the email templates and sends an email to submit a request to the HD
Incident form.
3. The Email Engine receives the email from the mail server. It parses the instructions in his
email, and makes the appropriate API calls to the AR System server.
4. The server creates an entry in the HD Incident form. Slightly suspicious of using email to
create trouble tickets and also wanting to verify the status of his printer problem, Joe User
opens the HD Incident form in a browser. He finds his entry already assigned to the frontline
Customer Support engineer who is fixing the printer.
For more information, see Sending a submit instruction to the Email Engine .
Sending a query instruction to the Email Engine

The easiest way to send queries to the Email Engine is to think of email as simply another client of
BMC Remedy AR System, like the mid tier. When performing queries with the mid tier, users must
perform certain basic actions, for example, logging in, opening a form, and performing a query.
Using email as a BMC Remedy AR System client is no different. To execute query instructions to
the Email Engine, the following information must be included:
AR System server name
AR System Login and Password to authenticate a user
Form name on which to execute the instruction
Page 1615 of 4705
Home
Query action
The major difference between the mid tier and an email client is that the mid tier sends its queries
directly to the AR System server, while incoming email is first processed by the Email Engine and
then sent to the server.
Limiting query results by using email qualifications
Sending email query instructions using the Format label
Entering field criteria using shorthand syntax
To send a query
1. Create a new email message in your mail tool.
2. Address the email message to the incoming mailbox.
3. To execute a query that returns all fields of all entries in the HD Incident form, enter the
following information in your email message to the Email Engine:
Schema: HD Incident
Server: polycarp
Login: Francie Frontline
Password: <userPassword>
Action: Query
Tip
Copy and paste these examples into your mail client, and then modify them as
needed.
The following figure shows the minimum information you need to send a query email. Here a
label called Action specifies an instruction. To send a query to the Email Engine, the label
Action must be set to Query.
A query instruction email
Page 1616 of 4705
Home
4. Send your email.

An incoming email received and an outgoing mail sent
5. Optionally, use the AR System Email Messages form to verify that the Email Engine has
received your email.
After the Email Engine has parsed the instruction and sent the query to the AR System
server, the server returns the query results that the Email Engine sends back to the email
client (as shown in the following figure).
Otherwise, the Email Engine will return an error message that indicates missing parameters
or an error while parsing the qualifier.
6. Open the returned email to see the results of your query (the following figure).
Page 1617 of 4705
Home
The query results returned

Tip
One benefit of the Email Engine is that outgoing email from the Email Engine can
include a formatted header or footer, like the HTML header template shown in the
following figure. For more information, see Incoming and outgoing mail templates.
This email message sent from the Email Engine shows that all fields of all entries in the HD Incident
form were returned. In effect, your email query was an unqualified search of the HD Incident form,
useful for the example, but certainly a performance impact on the server. You should always
include a qualification in your email queries.
Limiting query results by using email qualifications

You can limit the entries that a query returns by using a label called Qualification. The syntax of
the value given to the qualification is the same as what is used in the Advanced Search Bar in the
mid tier. As a result, any search that executes in the Advanced Search Bar in the mid tier will also
work with the Qualification label.
Tip
Create a user-defined instruction that runs the query. This allows the user to quickly
execute queries based on instructions that the administrator has predefined.
Page 1618 of 4705
Home
To include qualifications in an incoming email message

1. Create an email.
2. To execute a query that returns all tickets that Francie Frontline submitted, include the
Qualification label with the following query value in your email message to the Email Engine:
Schema: HD Incident
Server: polycarp
Action: Query
Qualification: 'Submitter' = "Francie Frontline"
In the qualification, the field name Submitter must be the same as the database name of the field.
Also, field names are case sensitive, and must exactly match the database name of the field.
You can also query entries by using field IDs instead of the database name of the field. For
example, the following Qualification label will produce the same results when the Submitter field
has a field ID of 2.
Qualification: '2' = "Francie Frontline"
In your qualification, you can include relational operators. The following qualification retrieves an
entry whose employee ID = 9 and that was submitted by Francie Frontline.
Qualification: 'Employee_Id' = 9 AND 'Submitter' = "Francie Frontline"
Sending email query instructions using the Format label

The confirmation email sent from the outgoing mailbox ( The query results returned) lists all the
fields of the form. This is the default behavior of query instructions. You could use the Format label
to send an email query instruction that includes only the fields specified in the results list of a form.
To use the Format label

1. Create an email.
2. To execute a query that returns only the fields specified in the results list, include the Format
label with the Short value in your email message to the Email Engine:
Schema: HD Incident
Server: polycarp
Action: Query Format: Short
Page 1619 of 4705
Home
If the Format is not explicitly specified, by default, it will be automatically assigned a value of Full,
which will return all fields in the form.
Entering field criteria using shorthand syntax

Like the mid tier, which allows you to enter criteria into form fields themselves (without entering
them into the Advanced Search Bar), the Email Engine supports a "shorthand" syntax of
qualification criteria.
For example, when the Submitter field has a field ID of 2, the following syntax produces the same
results as if you had entered "Francie Frontline" in the Submitter field in the mid tier:
!2!: Francie Frontline
You can use this same shorthand syntax to search for request IDs. The following template
searches for request ID from the HD Incident form:
Schema: HD Incident
Server: polycarp
Login: Demo
Password:
Action: Query
!1!:TT00000000119
Your email query can include multiple fields to search for all new urgent requests:
File exported Tue May 21 21:38:47 2004

Schema: HD Incident
Server: polycarp
Login: Demo
Password:
Action: Query
Status !7!: New
Caller Impact !536870927!: Urgent
If the qualification does not match any entries, the email returned from the Email Engine will
indicate this.
Sending a Submit instruction to the Email Engine

You can use email as a client of BMC Remedy AR System to submit entries on the server.
Supplying actual field values using keywords
Specifying confirmation email field content using the Format label
Page 1620 of 4705
Home
Including attachments with incoming email

To submit an entry into a BMC Remedy AR System form, send an email with instructions with the
Action label set to Submit.
To execute submit instructions to the Email Engine, the following information must be included:
AR System server name
Form name on which to execute the instruction
Submit action
Any mandatory fields
To use the Submit action label in an incoming email

3. To execute a submit action that creates an entry that contains the text "Printer not working"
in the Short Description field of the HD Incident form, enter the following information in your
email message to the Email Engine:
Schema: HD Incident
Server: polycarp
Action: Submit
!Submitter!: Francie Frontline
!Short Description!: Printer not working
The field name between the exclamation marks must exactly match the field name in the
database and is case sensitive.
As with a Query action, Submit actions can also use the field ID instead of the database field
name. The following syntax will return the same results if the Short Description field ID
equals 8:
*!8!: Printer not working
You can add a comment before the exclamation mark used with field names as in the
following example. The Email Engine will parse only the characters between the exclamation
marks, for example, the field ID (8) of the Short Description field:
Schema: HD Incident
Server: polycarp
Page 1621 of 4705
Home
Action: Submit
What is the problem!8!: Printer not working
Who is submitting!2!: Francie Frontline
If the value for the field is more than one line, then enclose it between [
HTMLUATarsadministering1030:$$ and $$]. For example, if you have a longer value for
the Short Description, it could be sent to the Email Engine as:
! Short Description!: [$$This is a longer description which spans multiple lines,

so use this syntax.$$]
The Email Engine will correctly parse the syntax when the email is submitted.
4. Send your email.
If you successfully submitted your email, the email returned will look something like this:
Instruction 1 has successfully created a new record with Request ID : 00000000000

0001
If the incoming mailbox is configured to Reply With Entry, then all the fields of the newly created
entry will be returned to the sender. (For more information about this configuration option, see
Configuring advanced incoming mailbox properties.)
If the entry cannot be created, the Email Engine will return an error message (as shown in the
following figure) that indicates missing parameters. Make sure your incoming email includes all
required fields, for example, Submitter.
An error message reply from the Email Engine
Page 1622 of 4705
Home
Tip
Another benefit of the Email Engine is that status from the Email Engine can be formatted,
like the status template shown in the following figure. For more information, see Incoming
and outgoing mail templates.
Supplying actual field values using keywords

You can use keywords such as $USER$ to supply the actual value for the field. Instead of
specifying a text value, you can use keywords, as the following example shows:
Schema: HD Incident
Server: polycarp
Action: Submit
!Submitter!: $USER$
!Short Description!: Printer not working
Specifying confirmation email field content using the Format label

Like the Query instruction, the Format label can specify whether a confirmation email from a
Submit instruction should include all fields from the form or only the fields in the results list.
To use the Format label, configure the incoming mailbox Reply With Entry parameter to Yes. If
Reply With Entry is set to No, then the Format label is ignored and the confirmation email will
contain only the Request ID number.
Page 1623 of 4705
Home
Note
Join forms do not send values of fields on Submit when the Reply with Entry parameter
is set to Yes for the incoming mailbox.
By default, the Format label is set to Full, which means all fields in the form are included in the
confirmation email. To include only fields from the results list in the confirmation message, set the
Format label to Short:
Schema: HD Incident
Server: polycarp
Action: Submit
Format: Short
!Short Description!: Create entry for new hire.
Including attachments with incoming email

Submit instructions can also include attachments.
Note
If you are using message/rfc822 attachments with a submit template, make sure the mail
client you use is sending the file name of the attached message properly. To test this,
send an incoming mail with a message attachment, then view the Attachment tab on the
Email Messages Form for the name of the attached file. If you use Outlook Express to
submit the message to the Email Engine and save the attachment by using the .msg
extension, the file name remains intact.
To include attachments
3. To include an attachment in an email, use the attachment field name or field ID:
Schema: HD Incident
Server: polycarp
Password: <password>
Action: Submit
!Short Description!: I am including the filter.log file.
Attachment field !536880912!: filter.log
Page 1624 of 4705
Home
Your label/value pair syntax should not see the attachment pool, but to specific attachment
fields.
4. Insert your attachment file anywhere in the email.
If the attachment name including the extension is not supplied, the email submission will not
pass the attachment to the attachment field.
Do not include two attachment files with the same name, as in the following example:
Attachment field 1 !536880912!: filter.log

Attachment field 2 !536880913!: filter.log
The Email Engine will accept the email submit instruction; however, the Email Engine cannot
recognize which of the two filter.log files to insert into the 536880912 attachment field.
Sending a Modify instruction to the Email Engine

Sending a Modify instruction to the Email Engine is more complicated than sending query or submit
instructions. To allow users to modify an entry, you must configure the Email Engine to accept
modification requests. Do not delete outgoing email notifications with modify instructions.
How modify instructions work with incoming email
Sending modify instructions in plain text
Sending modify instructions in HTML
Limitations to sending a Modify instruction
How modify instructions work with incoming email

The following figure presents a sample scenario that demonstrates how to send modify instructions
in an email message.
Using incoming email to modify requests
Page 1625 of 4705
Home
1. The BMC Remedy AR System administrator at XYZ completed the following tasks to enable
the Email Engine to modify entries in the AR System server:
Associated the incoming and outgoing mailboxes
Enabled the incoming mailbox to accept modify instructions
Created and sent security keys to trusted users of BMC Remedy AR System, for
example, the IT department. For more information, see Configuring BMC Remedy
Email Engine for modify actions.
Note
The incoming and outgoing mailboxes in the Email Engine can be one
physical mailbox, performing both the incoming and outgoing functions.
2. Joe User has a serious problem with his PC. He needs an IT engineer to install the latest
service patch and has submitted an entry on the HD Incident form (Request ID
000000000000055). Francie Frontline, who has BMC Remedy AR System administrator
privileges, is working on Joe's ticket. She needs Joe to verify his current PC configuration
and modify his ticket with updated information. She sends an email to Joe that includes the
following mandatory parameters:
Key
Action: Modify
Form name
Server name
Page 1626 of 4705
Home
Request ID
Her email to Joe must contain at least these items for modify instructions to work
properly. She also includes names of fields that Joe can modify. After she sends her
email, a copy of the email is stored in the Messages form and the email is sent to Joe.
3. Joe User replies to the email. He updates the work log label/value pair in the email, for
example, Worklog !536870922!: I'm running Service Patch 6 . Because he has
used email to submit and query BMC Remedy AR System entries, he knows how to include
additional fields to update information about the new department he was transferred to, for
example, !Department!: Product Marketing.
4. The Email Engine receives the reply from the mail server and verifies that Francie's original
email exists in the Email Engine (in the AR System Email Messages form) and that the
sender's email address is contained in the recipient field of the original email. It then parses
the modify instruction in Joe's email, and modifies the ticket in the HD Incident form.
5. The Email Engine returns the results to the sender, Joe User. If the email had failed (for
example, Joe modified the encryption value or he tried to use a different Request ID), the
Email Engine returns an error message that indicates faulty parameters or other problems.
For more information, see the following topics:

Executing a modify instruction is a two-step operation:
1. The BMC Remedy AR System administrator sends an outgoing message from the AR
System Email Messages form to the user who wants to modify an entry. The message can
be sent in plain text or HTML format. (To use HTML, see Sending modify instructions in
HTML.)
2. The user replies to the message with new values of the entry the user wants to modify (see
To reply to an email containing modify instructions ).
Sending modify instructions

Follow the procedure to send modify instructions to a user.
To send modify instructions to a user

1. Log in to the mid tier as a BMC Remedy AR System administrator user.
2. Open the AR System Email Messages form in New mode, and enter the following
information:
a. In the Mailbox Name field, select an outgoing mailbox.
b. In the To field, enter the name of the user you are sending the email to.
c.
Page 1627 of 4705
Home
c. In the Reply To field, enter the email address of the incoming mailbox that has been
configured to accept modify instructions.
d. Enter other information as needed, for example, an organization.
3. Click the Plain Text Body tab to create an outgoing message (plain text) with the following
information:
AR System Server Name
Label Key to specify the security, which the administrator can be supply in the
outgoing message or the user can supply in the reply
Action Label, which describes the type of action or instruction to be executed (In this
example, the Action Label is set to Modify.)
Form or Schema name on which to execute the instruction
Request ID of the entry the user can modify
Optionally, you can provide field IDs or database names of fields that have values that
can be modified. You must make sure the fields have permissions that allow users to
make modifications.
The content of an outgoing message that a BMC Remedy AR System administrator
sent through the outgoing mailbox of the Email Engine is as follows:
Server: polycarp
Login: Joe User
Password:
Key:
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!:
This message allows Joe User to modify Request ID 000000000000003 of the HD

Incident form. The Problem Summary field has been specified in the outgoing
message. Joe User can also modify additional fields in his email reply by adding more
field IDs. The following figure shows an outgoing message you might send to a user.
A sample outgoing message sent by the administrator to a user
Page 1628 of 4705
Home
You can substitute field IDs for database names. For example, if the Problem
Summary field is field ID 8, then you could replace the database name with its field
identifier !8! and produce the same results:
!8!:
Optionally, you can enter comments before the field ID, for example:
Enter problem summary!8!:
Note
Because there are no content template labels, you can use a result template
as its equivalent when performing a Modify action with incoming mail.
When you send the email, the Email Engine appends an internal label, ##Modify##.
The Email Engine generates an encrypted value for this label by using the Server
Name, Schema Name, and Request ID (as shown in the following figure).
If the ##Modify## label is found in the content of the email, the Email Engine
prepends the encrypted value to that label. If more than one ##Modify## label is
found, the encrypted value is prepended to all these labels.
Warning
The placement of the ##Modify## label and its encrypted value must be
such that the value is included in the reply email.
Page 1629 of 4705
Home
Replying to email containing modify instructions

Follow the procedure to reply to an email containing modify instructions.
To reply to an email containing modify instructions

1. Open your email client.
Joe User received an email that looks like the following figure.
The Modify instruction sent to a user
2. Open a reply window for the email that contains the modify instructions.
Note
You must reply to the same mailbox as the one from which the email was sent.
3. In the reply, modify parameters as needed.

For example, you could assign values for !8!, the Problem Summary field.
Warning
The user who is replying cannot add additional submit, query or modify instructions
to the email. Do not change the Request ID, Schema name, or Server label/value
pairs when replying to the administrator's email.
4.
Page 1630 of 4705
Home
4. Fill in any missing parameters as needed --- Login, Password (if there is a password), and
Key. (For information about creating security keys, see Testing your mailbox configuration.)
The following example shows the content of a sample reply from Joe User:
Server: polycarp
Login: Joe User
Password: yadayada
Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!: Bob Backline
Comments!8!: Modified last name from Frank Frontline to Bob Backline
##Modify##:\[$$ckI2UoIK4gNibZMvL7k7uI/
eDhsoIU5JBTYvh5DMXaQnhPhicyCT/g==$$\]*
In this example, Joe User also modified the contents of the Short Description field (field ID
8).
5. Send the email reply.
When the incoming mailbox of the Email Engine receives the reply from the user, it makes
sure that the original email sent by the administrator exists within the Email Engine and that
the sender's email address is contained in the recipient field of the original outgoing email.
The Email Engine then parses the email. If you successfully modified the entry, the Email
Engine returns the results to the email client. Otherwise, the Email Engine returns an error
message that indicates any missing parameters or other problems.

In addition to the plain text format, you can send modify messages from the AR System Email
Messages form in HTML format. Using HTML form controls gives administrators greater control
over the content that users can modify. By sending modify instructions in HTML, you are forcing
users to respond to the modify instructions exclusively with the HTML controls you have defined. As
a result, using the HTML format can help prevent user errors.
To send modify instructions using HTML

1. Using the AR System Email Messages form, create an outgoing message in New mode.
For sample contents of an outgoing message, see Sending modify instructions in plain text.
2. Click the HTML Body tab.
3. Enter contents like the following example:
Server: polycarp
<BR> Login: Joe User<BR>
Password <input type="password" name="Password" size="15" maxlength="14"> <BR>
Key:1234<BR>
Action: Modify<BR>
Form:HD Incident<BR>
Page 1631 of 4705
Home
Request ID: 00005<BR>

Assigned To <input type="text" name="!4!" size="20" value="Assignee"> <BR>
Short Description <input type="text" name="!8!" size="40" value="Enter a short
description"> <BR>
Status
<input type="radio" value="New" name="!7!"/> New
<input type="radio" value="Assigned" name="!7!" /> Assigned
<input type="radio" value="WIP" name="!7!"/> WIP
<input type="radio" value="Resolved" name="!7!"/> Resolved
<input type="radio" value="Closed" name="!7!"/> Closed
<BR>
This example of an HTML-formatted outgoing message allows Joe User to do the following
tasks with entry 00005:
Enter a password in an input type Password control field. When users enter their
password, stars appear instead of the typed symbols or letters.
Modify the contents of the Assigned To and Short Description fields.
Modify the status in an input type Radio control field. Users can select only one radio
button option.
With HTML format, you can also include system information (for example, server
name or form name) in hidden fields. The data is still within the message, but users
do not see it.
The following example is a Help Desk request message with Schema and Action as
hidden fields with default values supplied:
<h1>Help Desk Request</h1><hr>

<input type=hidden name="Schema" value="Help Desk"/>
<input type=hidden name="Action" value="Submit"/>
Name: <input type=text name="Login"/><br/>
Password: <input type=password name="Password"/><br/>
Problem Description: <input type=text name="Short Description"/>
Note
To learn how to define input type controls, see any standard HTML
reference book or reputable online source ( http://www.w3.org/ ).

The user receives an email that looks like the following figure.
A Modify instruction (HTML format) sent to the user
Page 1632 of 4705
Home
5. To execute the modification, reply to the email received with the modified values for the
HTML fields that you can see and have permission to change.
Responding to the Modify instruction (HTML format) sent to a user
Using the HTML controls you have defined, click in a field to modify its contents, for example, enter
Assigning this ticket to Bob Backline in the Short Description field. Also observe that Joe's
password is encrypted.
With HTML, users can modify only the fields you provide. As a result, creating outgoing HTML
email requires some planning by administrators. For example, if Joe User could not enter his
password, the Email Engine would reject the modify action due to permission problems. Email is no
different than any other AR System client. Like logging in to the mid tier, he could not use email to "
log in" to the Email Engine without entering a password.
Page 1633 of 4705
Home

Remember the following restrictions when using email to modify entries:
The Email Engine does not support the Modify All operation. Only one entry can be modified
with one modify instruction. However, you can include multiple modify instructions in one
email message if you include the full login information (server, login, and password) for each
entry that you want to modify, as in the following example:
Server: polycarp
Password: Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000003
!536870913!:
Server: polycarp
Password: Key:1234
Action: Modify
Schema: HD Incident
Request ID: 000000000000004
!536870913!:
You can combine the modify instruction with submit or query instructions in a single
message, provided multiple instructions (modify with submit or query) have been sent from
the administrator.
Users cannot add new instructions when replying to the message containing modify
instructions.
Creating workflow to modify requests

How to use workflow to modify requests
Creating a security key
Creating a sample form for your modify example
Creating filter workflow that triggers a Notify action
Exporting an email template
Creating a submit email
Replying to email notifications
The following example walks you through the procedure for creating workflow to modify requests.
In this example, make sure that the Demo user is still active and has an email address that works
with the Email Engine. Make sure your incoming and outgoing mailboxes work correctly. Finally, set
the polling intervals on your incoming and outgoing mailboxes to one minute so that you can quickly
Page 1634 of 4705
Home
verify your results.

The example is simple but complete, and you can easily add more functionality. For example, you
could create a Run If qualification in your filter to search for records that are marked Urgent and are
assigned to your Managers group.
How to use workflow to modify requests

The following figure presents a sample scenario that demonstrates how to use workflow to modify
requests.
Using workflow to modify requests
1. The BMC Remedy AR System administrator at XYZ has enabled the Email Engine to modify
entries in the AR System server. He has associated the incoming and outgoing mailboxes,
enabled the incoming mailbox to accept modify instructions, and created and sent security
keys to trusted users of BMC Remedy AR System. For more information, see Configuring
BMC Remedy Email Engine for modify actions .
Note
The incoming and outgoing mailboxes in the Email Engine can be one physical
mailbox, performing both the incoming and outgoing functions.
2.
Page 1635 of 4705
Home
2. BMC Remedy AR System receives a submit request. A filter uses email to send a
notification that a request has been received. This email is formatted by using a modify
template.
3. The user receives the message in her email client and then replies to it. She modifies the
request by entering the following information:
Login and password
Security key
Modifications to values of fields
She clicks the Send button to reply back to the AR System server.
4. The AR System server verifies the security key, the user's email address, and the request ID
. These security mechanisms make sure that only the entry sent for modification is being
modified and that it is being modified by the user who the original email was sent to.
Creating a security key

Use the following values to create an AR System Email Security record. You must provide a
security key for every user who sends modify instructions to the Email Engine, in this example,
Demo.
To create a security key

1. In a browser, open the AR System Email Security form in New mode.
2. Set the Status field to Enabled.
3. In the Key field, define your security key, for example, patience.
4. Enter Demo as the User Name.
5. Set the Force For Mailbox field to No.
6. Set the Force From Email Addresses to No.
7. Set the Expires field to No.
8. Leave the rest of the fields blank and save the record.
Creating a sample form for your modify example

You are creating a sample form used exclusively for the purposes of this exercise. Later you will
create and modify a record in this form to verify the workflow process.
To create a sample form

1. Create a new form and name it appropriately, for example, Modify Email Workflow.
2. Do not add any new fields.
3. Save the form.
Creating filter workflow that triggers a Notify action

Use the following information to create a filter that executes on the Submit condition of the Modify
Email Workflow form and triggers a Notify action.
Page 1636 of 4705
Home
To create filter workflow

1. Create a filter.
2. Enter a filter name, for example, Modify EmailFilter.
3. Select Modify Email Workflow as the Form Name.
4. Select Submit as the Execute On condition.
5. Leave the Run If condition blank. After you verify that you can use your filter workflow to
modify requests, you can add a Run If qualification later.
6. Click the If Action tab, and perform the following actions:
a. From the New Action list, select Notify.
b. In the User Name field, enter Demo.
c. From the Mechanism list, select Email.
d. In the Subject field, enter Modify Email Workflow.
e. In the Text field, enter the following information as the text of the message:
Login:
Password:
Key:
Action:
Modify Form: Modify Email Workflow
Request ID: $Request ID$
Submitter!2!: $Submitter$
Short Description:!8!: $Short Description$
The Modify action in the text of the outgoing message is the special instruction that
allows the Email Engine to modify an entry on the AR System server. The Modify
action is valid only in Reply with Result emails. For more information, see Modify
action.
7. Save your filter.
Exporting an email template

Export an email template from the Modify Email Workflow form. For more information, see
Exporting mail templates.
To export email templates

1. Log in BMC Remedy Developer Studio as a BMC Remedy AR System administrator.
2. In the BMC Remedy AR System Navigator, right-click serverName, and choose Export >
Mail Template.
3. In the Export Mail Template dialog box, click the ellipsis (...) button next to the Form field.
4. In the Form Selector dialog box, select Modify Email Workflow form, and click OK.
5. In the Export Mail Template dialog box, perform the following actions:
a. In the View Details table, select the views your want to use in the template.
b.
Page 1637 of 4705
5.
Home
b. Click the ellipsis (...) button next to the To File field to specify the file name and
location where you want the templates stored.
c. Click Finish.
6. Open the email template in a text editor.
Creating a submit email

Here you open a new email message and paste the contents of the exported mail template into the
new email. You use this email to submit a record to the Modify Email Workflow form.
To create a test email

1. Create a new email in your email client.
2. Address the email to the Email Engine inbox account.
3. Enter a subject line, for example, Modify Email Workflow.
4. Copy and paste the contents of the exported email template into the new email, and then
enter the required information for the template, for example:
#
# File exported Tue Sep 21 15:34:56 2004
#
Schema: Modify Email Workflow
Login: Demo
Password:
Action: Submit
Format: Short
Submitter !2!: Demo
Short Description !8!: Email Test*
Replying to email notifications

The email client sends your submit email to the incoming mailbox on the mail server. After receiving
the email from the mail server, the Email Engine parses the instructions in your email, and makes
the submit API calls to the AR System server. The server then creates a record in the Modify Email
Workflow form.
The incoming mailbox is configured to reply with results and generates an email response. Also,
when a record is submitted, filter workflow triggers a Notify action that includes instructions for
modifying the record.
The following procedure describes how you reply to email notifications generated by workflow.
Page 1638 of 4705
Home
To reply to email notifications

2. Confirm that the incoming mailbox has received your message, and then send the Reply
with Result email.
3. In the mid tier, open the Modify Email Workflow form in Search mode.
4. Make sure a new record was created in the Modify Email Workflow form.
5. Check for new mail in your mail client.
If you properly configured the Email Engine and all your permissions are working correctly,
you should receive an email notification (as shown in the following figure) from the filter that
you created previously.
A notification email (sent from filter) with the modify key
The following figure shows the modify key added to the notification:
##Modify##:\[$$ckI2UoIK4gNQ0qROehOucPFOokiXb/DfA07EiNObusaHtOquCV/ FSA==$$\]
Warning
You cannot modify a record through email without this ##Modify## key. Do not edit
this key in any way!
6. Reply to the returned email, and enter the following information into the body of the email:
Login: Demo
Password:
Key: patience
Action: Modify
Page 1639 of 4705
Home
Form: Modify Email Workflow

Request ID: 000000000000002
Submitter!2!: Demo
Short Description:!8!: Modifying requests with workflow is great!
##Modify##:\[$$ckI2UoIK4gOt6aqHF2QE9x5d1nqwf6FJLifugKurp68lQH9XRehn Ew==$$\]
Make sure you add the Login and security key. Update the Short Description so that you can
verify that modifications work on records in the Modify Email Workflow form.
7. Send the reply email.
8. In the AR System Email Messages form, confirm that the incoming mailbox has received the
email with the modify instruction.
9. In the mid tier, refresh the query results of the Modify Email Workflow form.
The modify action should have modified the Short Description in the record.
Searching for an entry to modify

This advanced solution builds on all the information you have learned up to now-for example,
sending query and modify instructions to the Email Engine, the use of templates, and so on. The
procedure assumes you have created a form named TestSecurityForm, which contains at least the
core fields.
To search for an entry to modify

1. Make sure you have an incoming mailbox and an outgoing mailbox configured and
associated with one another.
2. Set Enable Modify Actions to Yes in the AR System Email Mailbox Configuration form for
the incoming mailbox.
3. Make sure you have a valid security key.
4. Create a template (for example, TestModify) that includes a modify action.
You will use this template for the reply email; see the Result Template label in step 6.
Server: polycarp
Login:
Password:
Key:
Action:
Modify Form: TestSecurityForm
Request ID: [$$#$$Request ID$$#$$]
!2!:
!8!:
Because this template replaces the hard-coded label/value pair (Request ID:
000000000000026) with a variable value (Request ID: $$#$$Request ID$$#$$] ),
you can construct an email that gives you the flexibility to search for a specific parameter.
5. Add the TestModify template to the AR System Email Templates form.
6.
Page 1640 of 4705
Home
6. Use your mail client to create an incoming mail. Include a Query action in the body of your
email.
For example:
Server: polycarp
Login: Demo
Password:
Action: Query
Form: TestSecurityForm
Qualification: 'Request ID' = "000000000000026"
Result Template: TestModify
This email provides all the information required for the Email Engine to perform the query
action, and then to perform the modify action in the TestModify template.
Tip
If the Qualification was part of the TestModify template, you could have omitted the
Qualification line from the email.
7. Send your email to the incoming mailbox.

The Email Engine generates a reply (the following figure) to the Query action, by using the
template you created in step 4 and specified as the Result Template. You can see that the
Request ID value found from the query was substituted in the reply, by using the variable in
the template.
The Email Engine also creates a Modify Key based on the information in the Action, Form,
and Request ID and adds it to the email.
A reply email generated from the Email Engine
Page 1641 of 4705
Home
8. Open the reply email and modify the parameters as required. For example, add values in !2!
(a different name) and !8! (modifying the short description). Do not change the Action, Form,
and Request ID label/value pairs.
9. Fill in any essential missing parameters --- Login, Password (if there is a password), and Key
, and send the email reply with the modifications included.
A confirmation email that the modify action was successful
Note
You must reply to the same mailbox as the one from which the email was sent.
Page 1642 of 4705
Home
The Email Engine parses the email and the server modifies the entry. The Email Engine then
sends you a confirmation message, as shown in the following figure.
You can perform a search on the form to verify the result.
Displaying advanced options for incoming email

For incoming email, the most important use of the Advanced Options tab is to view message
information and errors of incoming email.
The Attachment Alternatives tab (the following figure) displays any attachments in the incoming
email. The tab displays the links to each message as it is rendered by the Email Engine in plain text
, HTML, and email client formats.
Attachment alternatives information for incoming email

2. Select an incoming email message.
3. Select Yes in the Display Advanced Options field of the AR System Email Message form.
4. Select one of the advanced option tabs: Advanced Options, Message Information, or Errors.
Note
For incoming email, you typically will not see information under the Templates and
Variable Replacement tabs.
Viewing status information about incoming email

The Message Information tab records status information about incoming email, such as its
Message ID, the date the email was received, and how the message was parsed.
Page 1643 of 4705
Home
Viewing error messages for incoming mail

The Errors tab enables users to view error messages if incoming email is not received correctly. If a
request fails to submit or query, the original message is returned, along with an error message that
indicates the reason for the failure.
The following figure illustrates an incoming query that did not return any results. Information
includes the severity of the error, error number, date created, and error message text.
Error information for incoming email
Syntax for incoming email

Email sent to the Email Engine to access the AR System server must follow a specific syntax. The
syntax is specified by a given set of labels that are recognized by the Email Engine. You can give
different values to the labels. Using label-value pairs in templates provides a table of labels that you
can use to send incoming email to the Email Engine.
Note
The examples of incoming email in this section make extensive use of label/value pairs,
aliases, variables, templates, and special keyword syntax as message content; the Email
Engine ignores any other text. For more information, see the detailed reference material
and examples of their use in Creating and using email templates.
Using incoming email, users can submit, query, or modify entries on the AR System server. Users
can send incoming emails through an external email client to a configured mailbox on the Email
Engine. If users send email through a third-party email client, they can enter the content into the
body of the email or specify a template.
Page 1644 of 4705
Home
The message content of incoming email must follow a particular syntax that is specified by a given
set of label/value pairs, for example:
Schema: HD Incident
Server: polycarp
Login: Joe User
Password: 12345
Action: Submit
The rules for label/value pairs and variables are exactly the same as those for templates.
Tip
Like the mid tier, incoming email can trigger workflow that fire on submit or modify. Email
functions like any other BMC Remedy AR System client to the AR System server. For
example, if the transaction meets the filter's Run If condition, the filter will fire, regardless
of whether the client is the mid tier or an email.
Syntax for variables in templates

With incoming email, you can use variables in templates. Variables are useful when you need to
substitute values for the fields to submit an entry.
Use the following syntax for variables:
#$$Variable Name$$#
If you expect the value of a variable to span multiple lines, then enclose the variable with brackets:
[$$
...
$$]
The following example of a template file ( .arm file) submits a new employee name into the
Employee Information form:
Schema: Employee Information

Server: server1
Action: Submit
Short Description !8!: $DATABASE$
Submitter !2!:$USER$
Employee Name !VEmployee Name!: [$$#$$VEmployee_Name$$#$$]
Page 1645 of 4705
Home
The characters between exclamation marks exactly match the field ID or database name of the field
on the form. The variable is called VEmployee_Name. Because the variable might span multiple
lines, it is enclosed by brackets [$$...$$].
When you send a submit instruction, you also can provide a value for variable $$
VEmployee_Name$$, as shown in the following example:
Schema: Employee Information

Server: server1
Action: Submit
Short Description !8!: $DATABASE$
Submitter !2!:$USER$
!VEmployee_Name!: [$$Joe Smith$$]
Character sets in incoming mail

The MimeToJavaMapping.properties file contains a list of character set conversions for your
outgoing mail. You can find this file in the Email Engine installation directory.
Setting up UNIX mailboxes

This topic explains how to establish a mailbox address for Email Engine on the UNIX operating
system. This procedure only provides generic guidelines. If you have questions about
implementation, consult your UNIX system administrator for details.
To set up the BMC Remedy AR System mailbox, you must have UNIX superuser (root user)
access on the UNIX server.
To set up UNIX mailboxes

1. Set up an ARSystem user account in the /etc/passwd file, as in the following example (new
entry in bold ):
root:x:0:1:0000-Admin(0000):/:/sbin/sh
daemon:x:1:1:0000-Admin(0000):/:
bin:x:2:2:0000-Admin(0000):/usr/bin:
sys:x:3:3:0000-Admin(0000):/:
adm:x:4:4:0000-Admin(0000):/var/adm:
lp:x:71:8:0000-lp(0000):/usr/spool/lp:
smtp:x:0:0:mail daemon user:/:
uucp:x:5:5:0000-uucp(0000):/usr/lib/uucp:
listen:x:37:4:Network Admin:/usr/net/nls:
nobody:x:60001:60001:uid no body:/:
noaccess:x:60002:60002:uid no access:/:
*ARSystem:x:50:10:AR System mail user:/home/ARSystem:/bin/sh*
2.
Page 1646 of 4705
Home
2. Edit the /etc/aliases file and add the alias ARSystem with the mailbox of /usr/spool/mail/
ARSystem, as follows:
/etc/aliases file
#######################
# Local aliases below #
#######################
# Email Alias for AR System mailbox
ARSystem:/usr/spool/mail/ARSystem
You can also choose a different name, as needed.

Verify this step for your UNIX operating system; it might be different for your platform. In
particular, the path to your mail folder might be different from /usr/spool/mail/.
Note
On some UNIX platforms, you need to run the newaliases command to have the
ARSystem aliases recognized. If you have questions or problems, see your UNIX
system administration documentation or UNIX system administrator. The email
directory /usr/spool/mail will vary between UNIX platforms.
3. Create the mailbox file you defined for this user in the /etc/aliases file or /usr/lib/aliases file
(HP-UX), by performing the following command:
# touch /usr/spool/mail/ARSystem
4. Change the group name to daemon, or to the owner of the mailbox alias name, as in the
following example:
# chgrp daemon /usr/spool/mail/ARSystem
Note
The group name varies between UNIX platforms. For most UNIX platforms, it is the
group daemon, while on HP-UX, it is mail. To verify the proper group name to use,
check the group name for the mail directory by using the command ls -ldg.
5. Change the mailbox permissions so they are readable and writable by all, as in the following
example:
Page 1647 of 4705
Home
# chmod 666 /usr/spool/mail/ARSystem

ls -laF /usr/spool/mail/ARSystem
-rw-rw-rw-- 1 daemon 0 May 30 16:55 /usr/spool/mail/ARSystem
Creating and using email templates

This section provides information and instructions about creating and using templates for outgoing
and incoming email.
Types of email templates
Creating templates
Exporting mail templates
Using label-value pairs in templates
Tips for using email templates
Storing templates in the AR System Email Templates form
Adding attachments to HTML templates
Sending incoming email with user instructions
Email template examples
Preparing email templates after an upgrade
This section describes the various types of templates, their use in incoming and outgoing mailboxes
, as well as label/value pairs. Labels are keywords unique in the Email Engine, and values are
their data. Label/value pairs can be included in templates and used to instruct the Email Engine to
interact with your AR System server.
Tip
The term "template" can be slightly misleading because email templates are more than
simply the pattern of label/value pairs you export by using Developer Studio. A variety of
email templates also function as the actual headers, footers, and content of your email
messages.
Email templates serve two main functions for incoming and outgoing messages:
For incoming messages (email that users send to an incoming mailbox), users can include
templates in their emails that contain specially formatted instructions. These instructions use
combinations of field labels and their values, usually referred to as label/value pairs. The
Email Engine parses (that is, translates) these instructions into commands to the AR System
server to perform a query, submit or modify an entry, or complete any other such action.
For outgoing messages (sent by the Email Engine by using an outgoing mailbox), templates
can provide formatting of content in messages that include the results of queries or various
other requests.
Page 1648 of 4705
Home
Templates used for incoming and outgoing messages can be formatted by using plain text, HTML,
or XML. Templates are defined and stored in forms on the AR System server and can be retrieved
for use by the Email Engine when called upon by incoming or outgoing mail.
Types of email templates

You can create specific templates for various functions. This topic presents an overview of the
different types of templates, which are all described in more detail later in this section.
In this topic:
Incoming and outgoing mail templates
User-defined instruction templates
Incoming and outgoing mail templates

You can create separate templates to specify different formats for incoming and outgoing mail.
Content templates Used for outgoing messages. These templates can be associated
with a specific form and contain the fields and their corresponding values relating to a
specific record. They can also contain plain text or reserved variables.
You can create these templates in a text editor (shown in the following figure), or export
them by using Developer Studio, selecting the form and fields that are to be contained in the
template.
The content template can also contain formatting instructions and label/value pairs to specify
a header, footer, result, or status template. A content template is attached by using the AR
System Email Messages form or by using workflow with filters and escalations.
A plain text content template
When using a content template with workflow, make sure that you include the fields specified
in the content template in the Fields tab of the Notify action. Content templates can also be
formatted in HTML, similar to the result template shown in the following figure.
Header and footer templates Used to place lines of text or a graphic at the beginning or
end of a message. They can be specified in the outgoing email using the AR System Email
Messages form. If they are specified in content templates or an email body as label/value
pairs, they will be applied to the email reply.
An HTML header and footer template
Page 1649 of 4705
Home
Result templates Defines the format to use when replying to an incoming instruction with
the results of an action. A label/value pair must be specified in the email containing the
action. Result templates can be either HTML or plain text.
Result template--HTML
Status templates Used when the execution of an incoming instruction results in an error.
A label/value pair must be specified to include specific status information in the email or
content template. Status templates can be either HTML or plain text. (For more information,
see Reserved variables.)
An HTML Status template
User-defined instruction templates

User-defined instruction templates enable administrators to associate a template with an incoming
email by way of an entry in the AR System Email User Instruction Templates form. When the user
sends an email with the appropriate entries, the Email Engine executes the relevant template.
Using this feature, the administrator can set up variable substitutions to be used in an email with
minimal input from the user. The associated template supplies the rest of the information. For
example, the template shown in the following figure logs the user Demo in to the server
reepicheep, queries the HD Incident form for all tickets with an urgent status, and returns the full
information about all fields that this user has access to. But all that the user needs to do is send an
incoming email with the Action label/value pair that identifies the user instruction, for example,
Action: Urgent.
A user-defined instruction template
Page 1650 of 4705
Home
User-defined templates look the same as other templates and are stored in the AR System Email
Templates form. For more information, see Action label and Sending incoming email with user
instructions.
Creating templates
In BMC Remedy Developer Studio, you can generate the email templates associated with a
particular form by choosing Tools > Export Mail Templates. The templates are generated as text
files.
You can modify the templates in a text editor so that they are in a different format and include all
necessary specifications.
You can also create your own custom template by using any text editor. These templates must
adhere to the rules outlined in this guide if they are to include fields, variables, and label/value pairs
.
Exporting mail templates

The mail template displays all of the fields that are visible in the selected view and that all users
have permission to update. Therefore, make sure that all fields that require a value are visible in the
selected view and that the Allow Any User To Submit check box is selected before performing the
following procedure. The Export operation generates fields in the same order as in the default
administrator view of the form.
Hidden fields are omitted from templates even though they might have public permissions and are
set to enable any user to submit. You can add any of the fields that are not exported to the template
. The user can gain access to these fields if their security key, supplied user information, or their
email address connects to the correct user name and depending on how the mailbox was
configured. If the user name used by the Email Engine has access to this field, then the field is
accessible.
To export mail templates

1. Log into BMC Remedy Developer Studio as a BMC Remedy AR System administrator.
2. In the BMC Remedy AR System Navigator, right-click serverName, and choose Export >
Mail Template.
The Export Mail Template dialog box
Page 1651 of 4705
Home
3. In the Export Mail Template dialog box, click the ellipsis (...) button next to the Form field.
4. In the Form Selector dialog box, select the form for which you want to generate mail
templates, and click OK.
5. In the Export Mail Template dialog box, perform the following actions:
a. In the View Details table, select the views your want to use in the template.
b. Click the ellipsis (...) button next to the To File field to specify the file name and
location where you want the templates stored.
If you specify an existing folder and file name, you have two choices:
Overwrite Overwrites the mail template of an existing file. This option is
useful when you are re-exporting a template that has changed.
Append Appends the contents to an existing file. If several templates are in
a single file, the mail processor will not be able to process the request.
The template is saved as a single text file with an * .arm extension. Using the
AR System Email Templates form, users can associate these files with their
mail messages.
The following example shows an email template exported by using Developer Studio.
#
#
File exported Fri Apr 30 09:54:36 2004
#
Schema: HD Email
Login:
Password:
Action: Submit
Format: Short
In general, lines beginning with a pound sign (#) are treated as comments, and can occur anywhere
in the message. Comments are optional and can be retained or deleted.
Page 1652 of 4705
Home
Using label-value pairs in templates

For the most part, email templates consist of a label/value pair surrounded by text or graphics,
depending on the format of the template. The label is a keyword such as Action. The value consists
of data or commands (for example, Submit). A value can be specified in the templates or obtained
from the configuration information. The Email Engine is not case sensitive when parsing the labels.
The following table lists valid labels; each label is discussed in more detail following the table.
Label/value pairs in templates
Label
Description
Incoming
Outgoing
Aliases
Page
Form
Name of a BMC Remedy AR System form.
Yes
No
Schema
Form label
Server
Server that will be affected by the instruction.
Yes
No
Login
User name used when executing the instruction

.
Yes
No
Password
Password used when executing the instruction.
Yes
No
TCP Port
TCP port used when logging in to the AR

System server.
Yes
No
TCP
Login, Password,
and TCP Port
labels
RPC Number
RPC number used when logging in to the AR

System server.
Yes
No
RPC
RPC Number and

Authentication
labels
Authentication
Authentication string used when logging in to

the AR System server.
Yes
No
RPC Number and

Authentication
labels
Language
Language used when logging in to the AR

System server.
Yes
No
Language label
Action
Denotes the instruction to be executed.
Yes
No
Format
Specifies the format of the information.
Yes
Yes
Qualification
Qualification for a query-based instruction.
Yes
No
Query Search
Qualification label
Result
Template
The name of the template to use in the reply.
Yes
No
Result
ResultTemplate
Result Template
label
Status
Template
The name of the template to use when Status

Information is returned.
Yes
No
Status
StatusTemplate
Status Template
label
Header
Template
The template to be used as the header in the

reply email.
No
Yes
Header
HeaderTemplate
Header Template
and Footer
Template labels
Footer
Template
The template to be used as the footer in the

reply email.
No
Yes
Footer
FooterTemplate
Header Template
and Footer
Template labels
Yes
Yes
!Name! or !ID!
Server label
User User
Name Name
Login
Login, Password,
and TCP Port
labels
Login, Password,
and TCP Port
labels
Instruction
Action label
Format label
Page 1653 of 4705
Home
Label
Description
Incoming
Outgoing
Aliases
The database name or ID of a AR System

Form Field.
Page
!Name! or !ID!
labels
Key
The key associated with a given sender or user

.
Yes
No
Encryption Key
Encryption
Key label
Request ID
The Request ID of the entry on which the
Yes
No
Entry ID EntryID
Request ID label
possible action must be executed.
RequestID

Form label
Server label
Login, Password, and TCP Port labels
RPC Number and Authentication labels
Language label
Action label
Format label
Qualification label
Result Template label
Status Template label
Header Template and Footer Template labels
!Name! or !ID! labels
Key label
Request ID label
Label-value pair formats
Global and local parameter declarations
Variables
Form label
The Form label identifies the form that the instruction will use. If no BMC Remedy AR System form
is specified or the specified form does not exist, the mail process verifies whether a default
Workflow form was defined in the AR System Email Mailbox Configuration form. If not, the item is
rejected because a form must be specified. The alias for this label is Schema. An example of a
Form label/value pair is Form:formName.
Server label
The Server label identifies the server that the instruction will affect. If no server is specified or the
specified server does not exist, the mail process defaults to the server information specified in the
EmailDaemon.properties file. An example of a Server label/value pair is Server:serverName. (For
more information, see EmailDaemon.properties file.)
Page 1654 of 4705
Home
Login, Password, and TCP Port labels

The Login and Password labels identify the user name and password used when executing the
instruction. You can configure exactly how the user name is to be determined for an incoming email
:
Set a security key in the AR System Email Security form. You must add Key:securityKey to
the email. If Key:securityKey matches an entry in the AR System Email Security form, then
the corresponding user name is used.
Use the supplied user information: user login name, password, possible authentication,
possible language, possible RPC, and possible TCP inside the email by using the
appropriate labels and values.
Use the sender's email address. The Email Engine searches through the User form for the
appropriate user name by searching for the email address. It uses the first user it finds
whose email address corresponds.
The passwords and security keys are encrypted in the AR System Email Messages form. The
aliases for Login are User, User Name, Name, and Login Name.
Note
If you try to send an email in an HTML template, do not use a colon in the Login, Name, or
Password labels. For example, do not use: Login: <input type="text" name="!
536870918" size=50/> Instead, use the format: Login <input type="text"
name="!536870918" size=50/> With this format, the Email Engine can parse
correctly that Login is a label for a field on the form and not an instruction.
The TCP Port label identifies the TCP/IP port of the AR System server, if your AR System server is
not using the BMC Remedy AR System portmapper. The alias for TCP Port is TCP.
RPC Number and Authentication labels

The RPC Number and Authentication labels define the RPC number for the destination server (
usually involved when the user is connecting to private queues) and the name of the external
authentication service that is used to authenticate the user. These values are the same as those
used when logging in to the AR System server. The alias for RPC Number is RPC.
Language label
The Language label defines the locale used when logging in to the BMC Remedy AR System
server. If no language is specified, the default values are used. The values are the same as they
are in the BMC Remedy Developer Studio and other BMC Remedy AR System clients. The format
of the Language label/value pair is Language: localeLanguage, for example, Language:en_US.
Page 1655 of 4705
Home
Action label
The Action label defines the operation to perform on a specific BMC Remedy AR System form. The
Action label/value pair is required in the incoming email so that the parser can generate valid
instructions. Valid actions are Submit, Query, Modify, and a user-defined value. If no value is given
for the label, the email is only logged and no actual execution takes place. An alias for Action is
Instruction.
Valid values for this label are in the following table, and explained in detail after the table.
Values applied to BMC Remedy AR System action labels

Value
Description
Submit
Submits a new entry on a specific BMC Remedy AR System form. This is valid within any incoming email. The
syntax is Action:Submit.
Query
Searches for entries on a specific BMC Remedy AR System form. The syntax is Action:Query.
Modify
Modifies a specific entry contained within a specific BMC Remedy AR System form. This is only valid in reply
emails (that is, emails that have been sent to the user from a BMC Remedy AR System server). The syntax is
Action:Modify.
User-Defined
An instruction that the administrator defines. The syntax is Action:adminDefinedText.
Submit action
By using the Submit action in an email, users can enter values for field labels, and submit a new
record. You can see an example of a template with a Submit action in Sending a submit instruction
to the Email Engine.
Query action
The Query action lets you search for existing entries. To increase server performance, you can
configure a limit to how many matches are returned in the message. If a request exceeds the
configured search match limit, an additional message is provided that indicates what the limit is. (
See the definition for "Limit Number of Items Returned" on the AR System User Preference form in
Setting the General tab.)
For sample templates with Search (Query) actions, see Using templates with outgoing email.
Modify action
The Modify action enables you to modify existing entries, but due to the nature of this command
and the security implications, the command can be executed only under the following conditions:
The message containing the modify action must be sent from an AR System administrator to
the user.
Page 1656 of 4705
Home
The user can only change field values and cannot add new actions or modify existing actions
when replying to the email that contains the modify action. The user must not modify the
modify key included in the email.
The sender or the user of the email must supply a valid Security Key.
Note
Do not modify the Password field (field ID 102).
The incoming mailbox must be configured to allow modifications. For more information, see
Configuring BMC Remedy Email Engine for modify actions .
In the outgoing mailbox, make sure the Delete Outgoing Notification Messages field is set
to No. You cannot modify a record by email if you delete outgoing email messages.
The Email Engine inserts the following special label and value into the email if the email contains a
Modify action:
##Modify##:[$$the encrypted information$$]
The encrypted value contains information, which the Email Engine uses to determine the following
items:
The Request ID of the email being sent
The AR System server to which the email was submitted
Form name
For more information, see Using workflow to modify requests and Sending a Modify instruction to
the Email Engine.
User-defined instruction
A user-defined instruction is a text string that the BMC Remedy AR System administrator
determines and that is used as a value for an Action label. A user-defined value can consist of any
text, as long as it is defined in the AR System Email User Instruction Templates form for
user-defined instructions. For more information, see Sending incoming email with user instructions .
Format label
For Query, Submit, and Modify actions, you can specify that requested information be formatted in
full or short form by entering Full or Short after this keyword. An example of a Format label/value
pair is Format:Full.
The Full format lists the information for all accessible fields, with each entry separated by a line of
hyphens.
Page 1657 of 4705
Home
The Short format returns only the fields defined in the results list. If no fields are defined for the
results list, it returns the Short Description field.
In Submit and Modify actions, use only the Format label if the advanced configuration setting
Reply with Entry is set to Yes for the incoming mailbox.
For Query, the default format is Full. All matching requests are listed in the body of the response,
one after another.
Qualification label
The Qualification label and its value are required only for a query-based instruction. The value can
be any properly formatted search. All of the restrictions that apply to the Advanced Search bar in
the mid tier apply when performed through email. A sample qualification string:
Qualification: 'Source' = "Phone" OR 'Source' = "email"
A null value will be treated as if it is a "return all records" query, such as 1 = 1. Aliases for this label
are Query and Search.
Result Template label

If the Email Engine is configured to send an email reply, you can specify a result template that
formats the reply for you. You include the Result Template label, and specify the template name as
the value. The Result Template label defines the template to use when replying to an incoming
email containing query instructions.
The Result template is usually associated with a particular form. This template consists of label/
value pairs and variables (described on Variables) that correspond to fields on the BMC Remedy
AR System form being queried. These variables are replaced by the data found on the form based
on the instruction being executed. For example, you can include variables in your template that let
users click a direct access URL to open a specific Request ID:
<TD width="17%"><a href="http://polycarp/arsys/servlet/

ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request
ID$$#">#$$Request ID$$#</a>
</TD>
Sample HTML result template illustrates how this variables is used in a result template. The value
given for this Result Template label is the name or Request ID of the template contained in the AR
System Email Template form. When the Email Engine receives this label and value, it retrieves the
Page 1658 of 4705
Home
template file and uses it as required. Aliases for this label are Result and ResultTemplate. An
example of a result template label/value pair is Result: resultTemplateName.
For more instructions, see Email reply using result templates in HTML format .
Status Template label

The Status Template label is the name of the template to use when status information is returned.
The template consists of label/value pairs and variables that are replaced with relevant data. These
variables correspond to the status information returned if any errors occurred while executing one
of the instructions; they make use of reserved words. (For more information, see Reserved
variables.)
This template does not have to be related to a particular form; the variables are specific to status
information and therefore can be used for any instruction on any form. The value given for the
Status Template label is the name or Request ID of the status template contained on the AR
System Email Template form. When the Email Engine receives this label/value pair, it retrieves the
template and use it as required. Aliases for this label are Status and StatusTemplate. An example
of a status template label/value pair is StatusTemplate:statusTemplateName.
Header Template and Footer Template labels

The Header Template and Footer Template labels define the templates used in the header and
footer of outgoing email. If the templates are used within a Query action block that is, after an
Action: Query label/value pair then the header or footer or both are inserted before or after (or
both before and after) each entry that is retrieved when the action is executed. In this way, entries
are clearly separated from each other.
The Header and Footer templates typically contain basic text, or they can be HTML documents with
logos, graphics, and decorative typefaces. The value given for this label is the name or Request ID
of a template contained on the AR System Email Template form. When the Email Engine receives
this label/value pair, it retrieves the template and uses it as required. The label/value pair method is
used when requesting results from a server by way of email.
Aliases for the Header Template are Header and HeaderTemplate; aliases for the Footer Template
are Footer and FooterTemplate. An example of a header template label/value pair is
HeaderTemplate:headerTemplateName.
!Name! or !ID! labels

The !Name! and !ID! labels indicate a BMC Remedy AR System field or the value of a variable. The
exclamation marks are required to surround the field name or the ID number. For example, field ID
8 is !8!. A colon (:) is placed after the second exclamation point as a delimiter, for example:
!8! : Short description information
Page 1659 of 4705
Home
Blanks are acceptable. If any characters other than digits and spaces are between the exclamation
points, the reference is not recognized as a field ID.
The argument to the ID/name label should be of the same data type as that of the field (data type
information need not be included explicitly as the parser will determine the appropriate data type of
the field by default). If this is a query action, and the argument is of a different data type than
defined for this field, an error will be generated.
Labels for fields need not be present in any specific order within an email message. You can
precede the field name/ID label with any text that you want to include. This text will not be parsed
by the Email Engine. It is common practice to include the actual field name in this way:
Submitter !2!: $USER$
In the previous example, the Email Engine treats the text Submitter as regular text. The field ID !2!
is parsed and the variable $USER$ is the value used for any submit or query action that might have
been specified.
Only fields that have values are used in the request. Fields that do not have values are ignored.
To specify the Request ID for join forms, use the Request IDs of the forms referenced by the join
form separated by a vertical bar. For example, a join form Request ID might appear as TT000567|
TT000890.
Key label
If your incoming mailbox is configured to require a security key, then the Key label/value pair must
be present in the incoming email message. A key is required to use the Modify action. The
passwords and security keys are encrypted in the AR System Email Messages form. Aliases for the
Key label are Encryption Key and Encryption. An example of a Key label/value pair is Key:testKey.
For more information, see Configuring incoming mailbox security.
Request ID label
The Request ID label is only valid for the Modify action and defines the Request ID or Entry ID of
an entry on the corresponding form against which the Modify action is to be executed. The Request
ID is required for a Modify action as it serves to identify the specific form entry you want to modify.
Aliases for the Request ID are Entry ID, EntryID, and RequestID. An example of a request ID label/
value pair is RequestID:0000012345.
Label-value pair formats

Your email must use specific syntax for label/value pairs so that the parser can extract the required
information. Each of the following formats can be used in plain text, HTML, or XML documents.
In this topic:
Page 1660 of 4705
Home
Basic format
XML format
HTML format
Text field
Radio buttons
Checkbox buttons
Menu field
Basic format
The basic format is the simplest. You can associate a label with a constant value or a variable
value. The labels and associated constant values are written as follows:
Label:[$$Value$$]
The opening and closing $$ enable the parser to extract the value from the email, including
situations where the value incorporates multiple lines. If the value does not incorporate multiple
lines, the label/value pair can be written as follows:
Label:Value
Tip
You should use the [$$ ... $$] variable syntax when the Email Engine needs to parse
multi-line values. Strictly speaking, you do not need to use this multi-line syntax for all
label/value pairs, but it is recommended to adopt if you think the values in a variable might
exceed a single line.
The label and value do not have to be left justified, and can be prefaced by text on the same line.
You do not have to surround the label with any special characters.
You can associate a label with a variable also. A variable is written as follows:
#$$variable_name$$#
When used in a label/value format:
Label:[$$#$$variable_name_Value$$#$$]
Page 1661 of 4705
Home
XML format
The XML format is as follows:
<Label>Value</Label>
BMC Remedy AR System fields are treated differently. The format is as follows:
<Field ID="!Field_ID!">Field Value</Field>
or:
<Field Name="!Field_Name!">Field Value</Field>
Variables are referenced as #$$variable_name$$# as in the Basic format. To view a template

using XML, see Creating result templates for outgoing email.
HTML format
The four major HTML field types are:
Text fields
Radio buttons
Checkbox buttons
Menu field
These types have a fixed format in HTML. In HTML, however, an editor automatically generates the
correct format when filling in any missing field values. You can still use the Basic format within the
HTML document. The corresponding fields can be used in situations where input is required from
the user. The email client must allow or support the ability to edit HTML fields directly; such an
example would be Microsoft Outlook when it is configured to edit emails with Microsoft Word. To
create a template by using HTML field types, see Sending outgoing email in HTML.
The name tag represents the label, and the value tag represents the value.
Text field
In HTML, a text field typically looks like this:
<input type="text" name="Label" size="20" value ="Value">
This represents a text field into which data can be typed so it easily represents a label/value pair.
The name tag contains a label, such as Action, and the value tag will contain a corresponding value
, such as Query.
Page 1662 of 4705
Home
Radio buttons
Radio buttons allow you to design a document where the user can select from a given range of
possibilities. Unlike a text field where only one set of tags between the <> markers represent a label
/value pair, radio buttons can contain several sets of tags that comprise one instruction label and
several values. An example follows:
<input type="radio" value ="Submit" checked name="Action" >
<input type="radio" value ="Query" name="Action">
This represents two radio buttons grouped together under the name Action. The values for the
radio buttons would be Submit and Query. The selected value would be determined by the word "
checked." The resulting label/value pair would be Action:Submit.
Checkbox buttons
Checkbox buttons allow you to design a document where there are several possibilities, but those
possibilities are not grouped together. An example follows:
<input type="checkbox" name="Label" value ="Value">
or
<input type="checkbox" name="Label" value ="Value" checked>
In the first example, the label and value is not used because the word "checked" is not included in
the definition. But in the second example, the label and value is used because the box was
checked.
This field can give the user the ability to select the parameters that are valid and those that are not.
Menu field
The menu field acts as a selection box where you will be able to create a label from which any
specific value can be selected from a range. In the following example, the Action label has possible
values of Modify, Submit, and Query.
<select size="1" name="Action">
<option value="Modify">Modify the entry</option>
<option selected value="Submit">Submit the entry</option>
<option value="Query">Query the entry</option>
</select>
Page 1663 of 4705
Home
The type is a select HTML field; the label is Action; and the values are Modify, Submit, and Query.
The tag containing the word "selected" determines the label/value paid to be used.
The menu field also allows the user to specify different visible text in the field with the correct field
values defined underneath.
Global and local parameter declarations

Any parameter defined in the email before an Action label is regarded as global and applies to all
the actions within the email. As a result, you do not have to repeat parameters, such as login
information or form names, for each instruction.
If the parameter is defined again after an action statement, then that parameter takes precedence
over the global parameter for that action only. For more information, see Email content template
with Submit and Query actions.
Variables
In this topic:
Variable examples
Using variables with notifications
Date formats supported in email templates
Reserved variables
Variables allow the administrator to create generic templates. Variables are used only with
templates that are to be used as one of the following types of templates:
User-defined instruction templates for incoming email.
Result templates for incoming email.
Content templates for new outgoing email.
Variables are placeholders that are replaced by specific values defined when:
The user instruction is executed and where the values are defined by a user sending the
email executing this user instruction.
The template for new outgoing emails is used as a content template. The variables are
defined by values of the fields in the entry that triggers the notification.
Variables can be used in place of values in the label/value pairs in templates. The variable is
replaced by a value at execution time.
The variable is defined as follows:
#$$variable_name$$#
Page 1664 of 4705
Home
When used in a label/value format, use the following syntax:
Label:[$$#$$Value$$#$$]
For more information about label/value formats, see Basic format.

The name of the variable can be the same as a AR System field, so there are no restrictions if used
in the context of a AR System form. This allows you to use existing AR System field values to
define the value of a variable. The variable value is retrieved from the same !Field ID! label as
that of AR System fields so the variable name might also be the name or ID of an existing AR
System field.
In content templates used for outgoing emails, variables for field values must use the field database
name, not the field ID. For specific examples, see Using variables with notifications.
For outgoing emails, the variable value is determined in the following order:
1. If you supply an attachment in the Values attachment field of the Attachment Alternatives tab
of the AR System Email Messages form, the attachment is used to determine the values for
variables contained in the template. For more information about how to do this, see Using
the Attachment Alternatives tab.
2. If you do not supply an attachment in the Values attachment field, but supply information in
Field Values, or obtain a value by using a qualification in the Qualification field of the
Variable Replacement tab of the AR System Email Messages form, the information is used
to determine values for variables contained in the template. For more information, see Using
the Variable Replacement tab.
3. If you do not supply field values, but your content template contains a query to obtain
information to substitute in the email, the query information is used to generate the message.
For query information to be used, a form, server, and qualification must be supplied. If any
one of these items is missing, the message creation will fail.
Variable examples
The following example shows a field value used as a variable in a query or qualification:
Query:[$$'Last Modified By' = "User" AND 'Modified Date' >

"#$$modified_date$$#"$$]
Inside the same template or defined in the user-defined instruction template received in email, this
variable could be associated with a value as follows:
!modified_date!:[$$21/01/2004$$]
Page 1665 of 4705
Home
After the parser has extracted all the required information, the variable is replaced with the
appropriate value, resulting in a query as follows:
Query:[$$'Last Modified By' = "User" AND 'Modified Date' > "21/01/2004"$$]
Note
Variables can be used only for form field values and qualifications. They do not work for
Login or Server labels. For example, the variable Login: #$$Joe User$$# would not be
correctly parsed by the Email Engine and would return an unknown user error. Only local
fields (fields after the Action label) can be substituted. Global fields (fields before the
Action label) cannot be substituted. Labels like Server, Schema, Login, Password, or Key
are considered to be global and cannot be substituted.
Using variables with notifications

When creating templates to be filled in using notifications, the template variables for field values
must use the field's database name (not the field ID) as the variable name. This is because the
server uses the field name (database name) to assign the values in the AR System Email
Messages form.
For example, if the user has a template to mail out the user information through a notification that
looks like the following, it will not work for notifications:
Login Name : #$$101$$#

Password : #$$102$$#
Group List : #$$104$$#
Full Name : #$$8$$#
Default Notify Mechanism : #$$108$$#
Email Address :#$$103$$#
To use this template in notifications, the user must change it so that it looks like the following
example:
Login Name : #$$Login Name$$#

Password : #$$Password$$#
Group List : #$$Group List$$#
Full Name : #$$Full Name$$#
Default Notify Mechanism : #$$Default Notify Mechanism$$#
Email Address :#$$Email Address$$#
Add the following core fields to the template:
Page 1666 of 4705
Home
Req Id:#$$Request ID$$#

Submitter:#$$Submitter$$#
Create Date:#$$Create Date$$#
Assigned To:#$$Assigned To$$#
Stat:#$$Status$$#
ShortDescr:#$$Short Description$$#
StatHist:#$$Status History.New.USER$$#
Note
Do not use the Request ID to return entries from display or vendor forms in a notification.
If you construct a content template by using the #$$Request ID$$# variable and use
the content template in the Templates tab of notifications on display or vendor forms, the
system will not generate errors, but it also will not return the Request IDs.
Date formats supported in email templates

Date and time formats supported by the email templates
Format
Description
SHORT
A numerical date that includes the numerical month, day, and year (for example, 06/18/04). The order of each
component is based on the Regional Options properties in the Control Panel.
MEDIUM
Longer numerical date description, for example, Jan 12, 1952.
LONG
An alphanumeric date that includes the day of the week, month, day, and year (for example, Friday, June 18, 2004).
The order of each component is based on the Regional Options properties in the Control Panel.
FULL
Completely specified numerical date description, for example, Tuesday, April 12, 1952 AD.
You cannot mix different locales for short and long formats. So, in the countries where the valid
value is mm/dd/yy, dd/mm/yy is not valid and will not work, especially when the dd part is greater
than 12. You can see examples of valid date format values when you open Regional Options on
your Control Panel for long and short dates.
As a result, depending on your locale, 31/01/04 will work as a short date if your locale is set to dd/
mm/yy, not mm/dd/yy. The format 31-Jan-04 will not work, but you can use Jan 31, 2004 or
January 31, 2004.
Reserved variables
The Email Engine uses reserved variables to place the results of executing an email. You can use
reserved variables in Result and Status templates, but not in Content templates. Reserved
variables fall under two main categories:
Page 1667 of 4705
Home
Action information Useful when creating a template that will contain the results of
executing the associated action. They can be defined in a Result template with variables that
define the fields of a specific form. The Email Engine will replace these variables with the
correct values before the results are returned to the sender of the email containing the
actions.
The following formats are valid:
#$$Action.Name$$# The action value, such as Submit or Query.
#$$Action.Number$$# The position of the action within the entire execution list.
#$$Action.Form$$# The name of the AR System form involved in this action.
#$$Action.Query$$# The qualification (if any) associated with the instruction. (
This reserved variable is valid only for User Defined Instruction templates.)
Status information Used to store the results of system-generated errors. The following
formats are valid:
#$$ActionStatus.Number$$# The error or warning number.
#$$ActionStatus.Type$$# The type of error, such as Severe, Error, Warning.
#$$ActionStatus.Text$$# The message text.
#$$ActionStatus.AppendedText$$# The associated appended text.
These are also values that you would define in a status template; they are common to
all forms. The following figure displays an email that includes these reserved variables
for status information. This particular email uses the HTML status template found in
Types of email templates.
Reserved variables for status information used in outgoing email
The following rules apply for specific Status History information in the templates:
You must use the fully qualified status history name, for example:
Status-History.New.USER Status-History.New.TIME
You can also use numeric values, for example:
15.0.USER Status-History.0.USER 15.New.USER
Page 1668 of 4705
Home
The USER and TIME identifiers are case sensitive.
Tips for using email templates

You might find the following tips helpful when using email templates:
Diary fields and character fields with a maximum length of over 50 characters can use
multiple lines of text.
Values can be entered anywhere after the delimiting character. Leading and trailing blanks
are ignored when the Email Engine reads a value.
Comments are optional. Because the Email Engine ignores any lines that do not contain a
valid label/value pair, you do not have to add a # symbol in front of comments.
If the user does not enter a value into a field that has a default value defined, then the
default value is loaded. If the user does not enter a value into a required field and there is no
default value defined for it, an error will result.
Storing templates in the AR System Email Templates form

When you create or export templates, they must be stored in the AR System Email Templates form
to be used recurrently in emails.
To add a template to the AR System Email Templates form

1. Create or export your template.
2. Open the AR System Email Templates form in new mode in the mid tier.
3. Click the Template Information tab, and select the template format (Text or HTML) from the
Template Format list.
4. Specify the Encoding so that the Email Engine can parse the templates. If you leave the
Encoding field empty, the default encoding of the local system is employed.
5. Right-click in the attachment pool, and choose Add from the menu that appears.
6. In the Add Attachment dialog box, navigate to the appropriate location and open the
template file that you want to add.
The file is added to the list of attachments in the Email Templates form. You can also click
and drag a template to the attachment pool if you are using a Windows system.
7. Select the item in the attachment pool, and click the edit button next to the Template Name
field.
The name of the attachment is displayed in the Template Name field. For example:
template_attachment1.htm.
You can edit the file name, for example, to template1.htm.

8. (Optional) Enter a description.
It is useful to enter a description indicative of the function of the template.
9.
Page 1669 of 4705
Home
9. Click Save.
The system assigns a Template ID number to the template. (The Template ID field is hidden.
)
If an HTML template contains a reference to a graphic file, you should add the graphic file as
an attachment. For more information, see Adding attachments to HTML templates.
Adding attachments to HTML templates

Managing HTML template attachments
Exporting templates with attachments to another server
Use the AR System Email Attachments form to make sure that a specific attachment is always
included with any message that makes use of a specific template. You can add graphics to HTML
templates by using this form. This is particularly useful for header templates if you want to add a
company logo to the header information in your email.
Warning
You can only use graphic type files as attachments.
Note
The Email Engine does not support linking your HTML template to a cascading style sheet
.
To add attachments to HTML templates

1. Open the AR System Email Templates form in new mode in the mid tier.
2. From the Template Format menu, choose HTML.
This activates the buttons on the Template Attachments tab to add attachments to your
template.
3. Add a template file as an attachment, and click Save.
4. Click the Template Attachments tab, and then the Add Attachment button.
5. In the AR System Email Attachments form, select Template from the Type menu.
The AR System Email Attachments form for templates
Page 1670 of 4705
Home
6. Right-click in the attachment pool, and choose Add from the menu that appears.
7. In the Add Attachment dialog box, navigate to the appropriate location and open the file.
The file is added to the list of attachments on the AR System Email Attachments form. If you
are using a Windows system, you can also click and drag an attachment to the attachment
pool.
Note
If you attach multiple images (such as .gif or .jpg files) with a template and use the
same name for each image, the Email Engine will use only the first attachment.
8. Select the item in the attachment pool, and click the edit button next to the Attachment
Name field.
The name of the template attachment is displayed. For example:
template_attachment1.htm
You can edit the file name.
Note
If you specify an attachment name that is different from the file name, the
attachment does not appear in the email messages based on this template. For
example, if you are attaching the banner1.jpg file and you specify newBanner1.
jpg in the Attachment Name field, the image is not visible in the corresponding
email messages.
9. Click Save to close the AR System Email Attachments form.

Your attachment will be added to the list in the AR System Email Templates form. You might
need to right-click and select Refresh to see the attachment listed.
10. Click Save in the AR System Email Templates form.
The Email Engine will give the template attachment an ID. (The Attachment ID field is
hidden.)
Page 1671 of 4705
Home
Managing HTML template attachments

This topic explains how to manage email attachments.
In this topic:
To delete an attachment
To modify an attachment
To add a previously saved attachment to your template
To delete an attachment
1. Click the Attachments tab in the AR System Email Templates form.
2. Select the attachment you want to delete.
3. Click Delete Attachment.
4. Click the Refresh Table button to refresh the table in the Attachments tab.
The attachment is deleted from the list.
To modify an attachment
1. Click the Templates Attachments tab in the AR System Email Templates form.
2. Select the attachment you want to modify.
3. Click the Modify Attachment button.
The AR System Email Attachments form opens (see The AR System Email Attachments
form for templates).
4. Click Search to locate the attachment.
The attachment appears on the attachment list.
5. Modify the attachment as required. You also can modify the Attachment Name.
6. Click Save.
To add a previously saved attachment to your template

1. In the Template Attachments tab of the AR System Email Templates form, click the arrow
next to the blank field at the bottom of the pane.
2. Select the attachment.
3. Click the Add Existing button.
Your attachment is added to the list in the attachment pool.
4. Click Save.
Exporting templates with attachments to another server

You can export an HTML template from one server and then import the template onto another
server.
To export templates with attachments to another server

1. Export the HTML template from the AR System Email Templates form on the source server.
2.
Page 1672 of 4705
Home
2. Import the template into the AR System Email Templates form on the target server.
3. Copy the attachments associated with the template from the source server.
4. Manually add the attachments to the template in the AR System Email Templates form on
the target server.
Sending incoming email with user instructions

Creating and storing a template for use with user instructions
Creating user instructions
Sending a user instruction in an incoming email
Results of the user instruction
Using variables with user instructions
A good analogy for understanding user instructions is that they are "macros" for email. You can
make Email Engine interaction easier for your users by creating custom actions that reduce the
need to learn the Email Engine syntax of label/value pairs, variables, and so on. These custom
actions are called user instructions. The following figure provides a sample scenario of how to
create user instructions for your user community.
User-defined instruction templates automate actions to make it easy to perform common user
actions. Like macros, you can create predefined submit and query actions with these instruction
templates.
Every user instruction must be associated with an email template. Templates provide generic layout
for similar emails that are sent from or into the Email Engine, simplifying Email Engine interactions
for users. User Instruction templates enable you to associate a template with an incoming email
through an entry in the AR System Email User Instruction Templates form.
Overview of using instruction templates
Page 1673 of 4705
Home
Creating user instructions involves the following tasks:

1. The administrator creates a template, and then adds the template to the AR System Email
Templates form. The user instruction template looks the same as any other template.
2. The administrator creates a user instruction in the AR System Email User Instruction
Templates form by entering an instruction name in the Instruction field.
3. The administrator associates the template created in step 1 with the user instruction name.
4. The user sends an incoming email that contains the user-defined instruction (Action label/
value pair) to the Email Engine. The email contains an Action label and a value
corresponding to the valid character string in the Instruction field of the Email User
Instruction Templates form. The value for the variable that appears after the Action label is
extracted from the email, and the associated template is then executed.
5. As a result, the Email Engine constructs a message according to the template instructions
and sends the message to the user.
Creating and storing a template for use with user instructions

As an administrator, you can use a text editor to define templates by creating a text file with an
extension of .arm, and then attaching the .arm file to an entry in the AR System Email Templates
form.
To create templates for use with user instructions

1. Use a text editor to define a template, and name the file with an .arm extension.
The following example is a template file ( IN_Install_AllUrgent.arm) that queries all urgent
records in the TestSecurityForm form.
Schema: TestSecurityForm
Server: polycarp
Login: Demo
Page 1674 of 4705
Home
Password:
Action: Query
Format: Full
Header Template: Header_Urgent.html
Result Template: Default Content
Qualification: 'Status' <= 2 AND 'Impact' = 3
A template can contain one or more instructions. For more information, see Creating
templates.
Tip
Test the template by sending email to the incoming mailbox and see if it returns the
expected results.
2. In the mid tier, open the AR System Email Templates form in New mode.
Storing a template
3. Attach your IN_Install_AllUrgent.arm file to an entry in the AR System Email Templates

form.
4. Click the Template Attachments tab to add any header, footer, and result templates that are
used with your template.
Your UrgentRequests template was created and now stored.
Creating user instructions

After storing your templates, you must associate a name with the User Instruction by creating an
entry in the AR System User Instruction Templates form. The User Instruction name will be used as
a value for the Action Label in the email the user sends to the incoming mailbox.
Page 1675 of 4705
Home
Note
You can associate more than one user instruction with a template containing one or more
instructions.
To create a user instruction

In the mid tier, open the AR System User Instruction Templates form in New mode, and complete
the form as follows:
1. Do not enter a template ID. The system will create the unique ID in the Instruction Template
ID field when you save the entry.
2. From the Template Name menu, select the template that contains that actions you want to
associate with the user instruction. You can use only templates that are stored in the AR
System Email Templates form, for example, UrgentRequests. (See Creating and storing a
template for use with user instructions.)
3. To restrict the user instruction to one incoming mailbox, select a mailbox from the Mailbox
Name menu.
4. Enter a character string value for the Instruction field. This value is used to identify this
template when used in an incoming email, for example, Urgent.
Creating an entry using the User Instruction Template form
Sending a user instruction in an incoming email

All authorized users can send an email to the incoming mailbox of the Email Engine with the name
of the User Instruction as the value of the Action Label.
To send a user instruction

3. Enter the user instruction in the email.
The user instruction consists of an Action label and value equal to the string defined in the
Instruction field in the AR System Email User Instruction Templates form ( Urgent ). The
power of customized user instructions is that your email could simply consist of the following
text:
Page 1676 of 4705
Home
Action: Urgent
The email should include any values for the variables if any variables exist in the template
associated with the user instruction.
4. Send the email.
Results of the user instruction

The Email Engine will then retrieve all records of urgent requests from the AR System server and
list them in the email, as shown in the following figure.
The email response to a user instruction
After receiving an incoming email, the Email Engine processes a user instruction as follows:
1. Retrieves the associated user instruction entry from the AR System Email User Instruction
Templates form and determines which template is associated with the instruction.
2. Retrieves the associated template from the AR System Email Templates form.
3. Replaces the variables in the template with the values defined by the information in the email
.
4. Executes the template with substituted values in the incoming email.
Templates and user instructions can make it easier for your users to interact with the Email Engine,
reducing the need for them to learn the Email Engine syntax. Instead, all they need to do is use the
user instruction name as the value of the Action Label.
Using variables with user instructions

You can also use variables with user instructions. Variables are useful when you need to send
different values for the fields to submit an entry. For example, you can create a user instruction that
submits information into the User Instruction form.
The user might send a user instruction in the following email:
Page 1677 of 4705
Home
Login:Frank Frontline
Password:mypassword
Action: Submit
!Employee_Name!: [$$Joe Smith$$]
The characters between the exclamation marks match the variable name in the template that is
associated with the user instruction (Submit). The Email Engine will then:
1. Match the string between exclamation marks in the email with the variable name in the
template.
2. Retrieve the database name or field ID between the exclamation marks in the template.
3. Substitute the field with that database name with the value sent in the email.
Email template examples

The following examples in this section demonstrate how you can use templates to execute a
specific set of instructions on a BMC Remedy AR System form.
Creating email templates to search for Request ID
Creating email templates to search for fields
Creating email templates to perform searches using qualifications
Creating email templates that include attachments
Email content template with Submit and Query actions
Email reply using result templates in HTML format
Sample HTML result template
Email status template in HTML format
Header and footer templates
You can copy and paste these examples into the body of an email message, or you can use the
examples to create your own templates. For more information, see Creating and using email
templates.
Creating email templates to search for Request ID

You must use the Query Action label (or its alias) to perform a search action. The following
examples use templates that have been exported using BMC Remedy Developer Studio and show
how to modify them. You can, however, create the template using a text editor.
To create an email template to search for a request ID

1. Export the email template for the form that you want to make available for searching.
A sample of an exported mail template appears as follows:
# File exported Tue May 21 21:38:47 2004

Schema: vacation
Server: polycarp
Login:
Page 1678 of 4705
Home
Password:
Action: Submit
Values: Submit, Query
Format: Short
Values: Short, Full
Submitter !2!:
Short-Description !8!:
2. Edit the exported file.

a. Change the Action:Submit to Action:Query.
b. In the fields section of the email template, define only the Request ID. It must have a
field ID value of 1.
c. Enter the Request ID of the entry to be retrieved.
d. Remove all other fields from the mail template. (The only field in the body should be !
1! requestIDNumber.)
The following example shows an exported template that was modified to search for a
request ID:
Schema: vacation
Server: polycarp
Login:
Password:
Action: Query
Format: Short
Values: Short, Full
!1!:TT00000000119
Creating email templates to search for fields

This section contains a sample email template to search for fields.
To create an email template to search for a field

An example of a mail template for a form follows.

Schema: AR-HD Calls
Server: polycarp
Login:
Password:
Action: Submit
#Values Submit, Query
Format: Short
#Values Short, Full
Source !5368737933!: Phone
#Values: Phone, AR System, email,
NMP, ACD
Page 1679 of 4705
Home
Caller Impact !5368783455!: Low

Values: High, Medium, Low
Last Name !5386753452!:
Phone Number !5386748345!:

b. To use a format other than the default ( Short), set the Format option.
c. Edit the fields portion of the email template to include the fields you are searching, but
remove all other information.
The following example shows an exported template that was modified to search for
multiple fields.
Schema: AR-HD Calls

Server: polycarp
Login:
Password:
Action: Query
Format: Full
Creating email templates to perform searches using qualifications

This section contains a sample email template to perform a search using qualifications.
To create an email template to search using a qualification

The following example shows a mail template for a form:

Schema: AR-HD Calls
Server: polycarp
Login:
Password:
Action: Submit
Values: Submit, Query
Format: Short
Values: Short, Full
Values: Phone, AR System, email
Values: High, Medium, Low
Last Name !5386753452!:
Phone Number !5386748345!:

a.
Page 1680 of 4705
Home
2.

b. Remove all fields in the message and include a Qualification label.
The following example shows an exported file that was modified to search using the
Qualification label.
Schema: AR-HD Calls

Server: polycarp
Login:
Password:
Action: Query
Format: Short
Creating email templates that include attachments

This section contains a sample email template that includes an attachment field.
To create an email template that includes attachments

1. Export the email template for the form that you want to make available for submitting.
Make sure that the form contains an attachment pool and a valid attachment field.
2. Edit the template to include the label and value for an attachment field (for example, Attach!
536880912!:), as shown here:
# File exported Fri Mar 07 10:30:40 2004

Schema: Email Submit
Server: polycarp
Login:
Password:
Action: Submit
Format: Short
Submitter ! 2!:
Short Description ! 8!:
Attach!536880912!: <====== (Manually add this line based upon the
attachment field name and database ID)
Note
Make sure that you use the ID of the attachment field, not the attachment pool.
3. In a third-party client tool such as Microsoft Outlook Express, create a new email, and copy
and paste the template into the body of the email
4.
Page 1681 of 4705
Home
4. Add all the required values, for example, Login name, password, and so on.
5. Supply the attachment file name including the extension after the attachment field parameter
.
A user email template filled out with a filter.log file attached appears as follows:
Schema: Email Submit

Server: polycapr
Login: Demo
Password:
Action: Submit
Format: Short
Submitter ! 2!: Demo
Short Description ! 8!: Submitting email with attachment file.
Attach!536880912!: filter.log
6. Insert your filter.log attachment file anywhere in the email. If the attachment name including
the extension is not supplied in the email template, the email submission will fail.
Email content template with Submit and Query actions

The following example submits an entry into a form, then queries that same form.
When creating or modifying templates, any values that are defined before the Action label are
global and apply to all the actions specified. Any value declared after the Action statement takes
precedence over the global definition for that action only.
In the following example, the Schema and Server label/value pairs are global, and therefore apply
to both the Submit and Query actions.
Schema: HD Incident
Server: polycarp
Login: Demo
Password:
Action: Submit
Format: Full
Submitter ! 2!: $USER$
Short Description ! 8!: Need to create new post office box.
!Last Name!: Stampovich
!First Name!: Ivan
!Email!: stampovic@bmc.com
!Location!: Sunnyvale
!Phone!: 222-3333
!Status!: Assigned
Page 1682 of 4705
Home
!Impact!: Medium
!Item!: Email
!Category!: Applications
!Type!: Office
!Problem Summary!: Need to create new post office box.
!536870920!:
!536870920!:
boot.ini
boot.ini
Action: Query
Qualification: 1=1
If you did not specify a template for the email reply, the Email Engine would reply with the results
shown in the following figure:
Reply to an action template using the default format
The Query action returns the Submit entry to the user, along with any other entries that meet the
qualification. Because no template was defined as a Results Template, the Email Engine uses the
default internal text format.
Email reply using result templates in HTML format

For the Email Engine to include a Result Template in the reply email, enter the Result Template
label/value pair as a global declaration in the body of your email, as in the following extract:
Schema: HD Incident
Server: polycarp
Result: HDIN Content
Login: Demo
Password:
....
Page 1683 of 4705
Home
When the Email Engine sends the reply email, it will use the result template shown in the following
figure.
Reply to an action email using a result template
For a detailed example, see Creating a result template for reply email.
The Result Template must be stored in the AR System Email Templates form before it can be used
in the email. For more information, see Storing templates in the AR System Email Templates form .
If graphics are included, and these are not contained in the HTML file, the graphics must also be
added using the Template Attachments tab of the AR System Email Templates form. For more
information, see Adding attachments to HTML templates.
In this template, variables correspond to a field on the HD Incident form on which the template is
based (for example, #$$Last Name$$# ). The administrator only specifies the fields that are of
interest. For more information, see Variables.
When you send your email, the Email Engine parses and executes the instructions in the Results
template. It formats the reply and substitutes values for the variables. For more information about
results templates, see Result Template label.
Sample HTML result template

If you create your result templates with HTML, you can professionally format the reply results that
users see.
An HTML result template
Page 1684 of 4705
Home
The following HTML code was used to create the result template shown in the following figure.
Copy, paste, and then adapt what you need for your own result template.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<HTML><HEAD><TITLE>HDIN_Content</TITLE>
<META http-equiv=Content-Type content="text/html; charset=iso8859-1">
<META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD>
<BODY>
<TABLE cellSpacing=0 cellPadding=0 width=772 border=0><!-DWLayoutTable-->
<TBODY>
<TR>
<TD vAlign=top width=772 height=234>
<TABLE borderColor=#cccccc cellSpacing=1 cellPadding=1
width="100%"
border=0>
<TBODY>
<TR borderColor=#cccccc>
<TD colSpan=5>
<HR>
</TD></TR>
<TD width="11%"><B><I>Incident #</I></B></TD>
<TD width="17%"><a href="http://polycarp/arsys/servlet/
ViewFormServlet?server=polycarp&form=HD+Incident&eid=#$$Request
ID$$#">#$$Request ID$$#</a> </TD>
<TD width="21%"> </TD>
<TD width="14%"> </TD>
<TD width="37%"> </TD></TR>
<TD colSpan=5><B><FONT color=#008000 size=3><U>Requester
Information_______________________________________________________
_____________________</U></FONT></B></TD></TR>
<TD width="11%" height=56>
<DIV align=center><IMG height=40 src="people.gif"
width=38></DIV></TD>
<TD width="17%" height=56><B><FONT size=3>Last Name</FONT></B></TD>
<TD width="21%" height=56><FONT size=3>#$$Last Name$$#</FONT></TD>
<TD width="14%" height=56><B><FONT size=3>Email</FONT></B></TD>
<TD width="37%" height=56><FONT size=3>#$$Email
Address$$#</FONT></TD></TR>
Page 1685 of 4705
Home
<TD colSpan=5><FONT size=3><B><FONT
color=#008000><U>Incident
Information_______________________________________________________
_______________________</U></FONT></B></FONT></TD></TR>
<TR borderColor=#333333>
<TD borderColor=#cccccc width="11%" rowSpan=3>
<DIV align=center><FONT size=3></FONT><FONT size=3><B><IMG height=43
src="tools.gif" width=46></B></FONT></DIV></TD>
<TD borderColor=#cccccc width="17%"><B><FONT
size=3>Impact</FONT></B></TD>
<TD borderColor=#cccccc width="21%"><FONT
size=3>#$$Impact$$#</FONT></TD>
<TD borderColor=#cccccc width="14%"><B><FONT
size=3>Status</FONT></B></TD>
<TD borderColor=#cccccc width="37%"><FONT
size=3>#$$Status$$#</FONT></TD></TR>
<TR>
<TD width="17%"><B><FONT size=3>Category</FONT></B></TD>
<TD width="21%"><FONT size=3>#$$Category$$#</FONT></TD>
<TD width="14%"><B><FONT size=3>Type</FONT></B></TD>
<TD width="37%"><FONT size=3>#$$Type$$#</FONT></TD></TR>
<TR>
<TD width="17%"><B><FONT size=3>Item</FONT></B></TD>
<TD width="21%"><FONT size=3>#$$Item$$#</FONT></TD>
<TD width="14%"><B><FONT size=3>Assigned To</FONT></B></TD>
<TD width="37%"><FONT size=3>#$$Assigned To$$#</FONT></TD></TR>
<TR>
<TD borderColor=#cccccc colSpan=5>
<HR>
<FONT size=3></FONT></TD></TR></TBODY></TABLE></TD></
TR></TBODY></TABLE><B><FONT
color=#008000 size=3></FONT></B></BODY></HTML>
Email status template in HTML format

For the Email Engine to include a Status Template in the reply email (for example, to format the
reply if there is an error), enter the Status Template label/value pair as a global declaration in the
body of your email, as in the following extract:
Schema: HD Incident
Server: polycarp
Status Template: Status Default
Login: Demo
Password:
....
Similarly, the Status Template must be stored in the AR System Email Template form. For more
information about status templates, see Status Template label.
Page 1686 of 4705
Home
When you send your email, the Email Engine parses and executes the instructions in the content
template. If there is an error, the resulting status email will be formatted like the following figure.
The Email Engine substitutes values for the variables.
A reply with the status template
Header and footer templates

To cause the Email Engine to include a Header Template (or Footer Template) in the reply email,
enter the Header Template label/value pair as a global declaration in the body of your email, as in
the following extract:
Schema: HD Incident
Server: polycarp
Result Template: Result Template
Header Template: Default Header
Footer Template: Default Footer
...
A reply with the header template

Page 1687 of 4705
Home
You can also add a header or footer template to an email by selecting it in the relevant field of the
Templates tab of the AR System Email Messages form. Use the template fields on the AR System
Email Messages form to determine the templates used when creating an outgoing message. The
label/value pair method is used when requesting results from a server by email.
In each case, the templates must be stored in the AR System Email Templates form before they
can be used in the email. For more information, see Storing templates in the AR System Email
Templates form. If graphics are included, and these are not contained in the HTML file, you must
also add the graphics using the Template Attachments tab of the AR System Email Templates form
. For more information, see Adding attachments to HTML templates.
For more information, see Header Template and Footer Template labels.
Preparing email templates after an upgrade

If you have upgraded from BMC Remedy Mail Server (release 5.1 or earlier), you might have to
modify your existing templates to use the features in release 7.0.00 or later, for example, the ability
to use HTML in your templates. However, there is a configuration setting that allows you to
continue using email templates from release 5.1 or earlier "as is" with release 7.0.00 and later. For
more information, see the "Use Original Template Format" feature in Configuring advanced
incoming mailbox properties.
To use your old email templates after an upgrade to Email Engine 7.0.00 or later, use the following
procedure.
To prepare email templates after an upgrade

1. Verify the following settings in the AR System Email Mailbox Configuration form:
Incoming mailbox is Enabled.
Email Action for your incoming mailbox is set to Parse.
Use Original Template Format is set to Yes, if you want to use your original
templates for your incoming mailbox "as is" without using the 7.0.00 and later email
template features.
Use Supplied User Information field is set to Yes.
2. If only one form is used for email submissions, set the Default Workflow Form to that form
name.
3. To guarantee that no other form is used for email submissions, set Force Default Workflow
Form to Yes.
4. If the original templates do not include a user name, user password, or form name, perform
one of the following tasks:
Modify the template to include these parameters and values.
Create a template that includes one or more of these values with a user instruction.
For more information, see Sending incoming email with user instructions .
Page 1688 of 4705
Home
Email Engine forms

The Email Engine provides a set of administration, user, and workflow forms for configuring and
processing email from your mail server.
Email Engine administration forms
Email Engine user forms
Email Engine workflow forms
These forms are generated when you install the Email Engine.
Note
If any of the email forms are deleted after you install the Email Engine, you must import
those forms manually. They are not imported when you restart the AR System server.
Warning
BMC recommends that you do not archive or audit the forms containing core fields.
Email Engine administration forms

This section contains information about the following administration forms that are available with
the Email Engine:
AR System Email Failover Mail Server Configuration form
AR System Email Mailbox Configuration form
AR System Email Templates form
AR System Email User Instruction Templates form
AR System Email Security form
AR System Email Failover Mail Server Configuration form

Each mail server can have only one failover server. However, you can also specify a failover server
for each failover server. For more information, see Multiple mail server support.
BMC Remedy AR System Email Failover Mail Server Configuration form
Field
Description
Mail Server Name/IP
The name or IP address of the mail server that the Email Engine can use to send or receive emails.
Page 1689 of 4705
Home
Field
Description
Failover Mail Server

Name/IP
The name or IP address of the mail server that acts as a failover system for the other mail server
mentioned on this form.
Important
The Email Engine does not resolve the mail server if either Mail Server Name/IP or
Failover Mail Server Name/IP contains a new line character. You should use either the
server name or the IP address in both fields. If you use the server name in one field and
the IP address in the other, an error message is displayed and you are not allowed to
save the form. You should use similar naming conventions for both the AR System Email
Configuration form and the AR System Email Failover Mail Server form. You should not
provide the IP address in one form and the server name in the other. If you use different
naming conventions in these forms, no error is displayed, but the failover mail server is
not used successfully if the primary mail server stops working.
AR System Email Mailbox Configuration form

In this topic:
Incoming mailbox--Basic and Advanced Configuration tabs
Outgoing mailbox--Basic and Advanced Configuration tabs
Use the AR System Email Mailbox Configuration form to create mailboxes and specify their use.
For each mailbox, the form provides a name and email address for the mailbox administrator,
actions associated with the mailbox, connection and security provisions, and defaults.
For more information, see Configuring outgoing mailboxes and Configuring incoming mailboxes.
Incoming mailbox--Basic and Advanced Configuration tabs

The following table describes the fields on the basic and advanced tabs:
AR System Email Mailbox Configuration--Basic and Advanced
Field name
Description
Mailbox
Name
Enter the name of the incoming mailbox.
Mailbox
Function
Select whether mailbox is Incoming or Outgoing.
Status
Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Email
Server
Type
Select the email protocol. Incoming mailboxes include following protocols:

For 32-bit JVM:
POP3
Page 1690 of 4705
Home
IMAP4
MBOX
MAPI
For 64-bit JVM:
POP3
IMAP4
MBOX
Polling
Interval (
Minutes)
Enter the number of minutes after which the Email Engine will check for incoming mail from the mail server for this
mailbox.
Email
Enables the secure socket layer. Used only with POP3 and IMAP4.
Server
Requires
SSL
Inbox Path
Enter the full path file name to the mbox file corresponding to the user email account that will be used. Used only
with MBOX.
Email
Server
Name/IP
Enter the name or IP address of the mail server used in your organization. Used only with POP3 and IMAP4.
Email
Server Port
Enter the port used for connecting to the mail server. The default port number is determined by the protocol
selected and whether Secure Sockets Layer (SSL) is selected. Used only with POP3 and IMAP4. If you do not
enter a port number, the following default values will be used:
POP3: 110
POP3 with SSL: 995
IMAP4: 143
IMAP4 with SSL: 993
Email
Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
Server
User
Email
Server
Password
Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
Profile
Name
Enter the name of the Microsoft Exchange profile to be used for incoming mailbox. Used only with MAPI.
Associated
Mailbox
Enter the name of an outgoing mailbox used to reply to incoming emails that require a response.
Name
Email
Action
Select Parse to enable the Email Engine to detect and process instructions included in an incoming email message
Use
Original
Template
Format
Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (BMC
Remedy Mail Server release 5.1 or earlier) and thus ignore special HTML fields and XML formats.
Reply With
Result
Select Yes to enable the results of an Action to be included with an email reply, or select No if results should not be
included.
, or accept the default value of None for no action.
Page 1691 of 4705
Home
Reply With
Entry
Select Yes to return the complete entry of a submit or modify action. Select No to use the default single-line entry.
Enable
Modify
Select Yes to enable modify actions, or No to prevent modify actions from being performed.
Actions
Default
Workflow
Form
Enter the name of the form upon which the Email Engine will execute instructions found within the incoming email
message if no specific form is specified in the email message.
Force
Default
Select Yes if the Default Workflow Form should be used regardless of what was specified in an incoming email.
This action will confine all instructions received by this mailbox to the specified form.
Workflow
Form
Use
Security
Select Yes to force a security key to be used for incoming mail to this mailbox.
Key
Use
Select Yes to use AR System server login information that might be included within the incoming email message.
Supplied
User
Information
Use Email
From
Address
Select Yes to use the email address of the sender as a form of authentication.
Note
If the database is case sensitive, make sure that the character case of the email address from the user
form and email address of the sender is the same.
Outgoing mailbox--Basic and Advanced Configuration tabs

The following table describes the fields on the basic and advanced tabs:
Basic and advanced configuration for outgoing mailboxes
Field name
Description
Mailbox Name
Enter the name of the outgoing mailbox.
Mailbox
Function
Status
Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Basic Configuration tab

Email Server
Type
Select the email protocol. Outgoing mailboxes include the following protocols:
For 32-bit JVM:
SMTP
MAPI
For 64-bit JVM:
SMTP
Page 1692 of 4705
Home
Polling
Interval (
Minutes)
Enter the number of minutes after which the Email Engine will check for new outgoing mail waiting to be sent
from this mailbox.
Email Server
Requires SSL
Enables the secure socket layer. Used only with SMTP.
Email Server
Name/IP
Enter the name or IP address of the mail server used in your organization. Used only with SMTP.
Email Server
Port
Enter the port used for connecting to the mail server. The default port number is determined by the protocol
selected and whether Secure Sockets Layer (SSL) is selected. Used only with SMTP. If you do not enter a port
number, the following default values will be used:
SMTP: 25
SMTP with SSL: 465
Email Server
Enter the user name of the administrator or user for this email account. Used only with SMTP.
User
Email Server
Password
Enter the user name of the administrator or user for this email account. Used only with SMTP.
Advanced Configuration tab

Profile Name
Enter the name of the Microsoft Exchange profile to be used for the outgoing mailbox. Used only with MAPI.
Associated
Mailbox Name
Enter the name of the incoming mailbox that will be used to receive instructions or notifications.
Default
Outgoing
Mailbox
Select Yes so that all outgoing messages for which an outgoing mailbox is not specified will be sent using
information in this entry.
Display Name
Enter the name you want displayed in the From line of the outgoing email.
Email
Address
Enter the full email address of the administrator or owner of this mailbox.
Reply To
Address
Enter the Reply-to email address for the mailbox owner or administrator, if you plan to enable users to reply to
notification messages sent from this mailbox.
Organization
For email clients that display an organization name, enter the name of the mailbox owner, or administrator's
organization.
Delete
Select Yes to have outgoing notification messages deleted from the AR System Email Messages form after they
Outgoing
Notification
have been sent from this mailbox.
Messages
Default
Addressing
Enter the email addresses to send to if addresses have not been specified in the Messages tab for a notify filter
or escalation.
Default To
Enter the default email addresses for those who should receive outgoing messages from this mailbox.
Default CC
Enter the default email addresses for those who should receive copies of outgoing messages from this mailbox.
Default BCC
Enter the default email addresses for those who should receive blind copies of outgoing messages from this
mailbox.
Page 1693 of 4705
Home
Default
Templates
If a user creates a message without specifying a template in the Templates tab for either Notify filter or
escalation actions, then this template will be used by default.
Header
Template
Enter the template to be used as the default header template.
Footer
Template
Enter the template to be used as the default footer template.
Status
Template
Enter the template to be used as the default status template.
Result
Template
Enter the template to be used as the default result template.
AR System Email Templates form

Use the AR System Email Templates form to create, display, and modify templates applied to email
messages. You can use this form to create standard templates that users can access for creating
specific types of messages. For each template, this form provides: the unique template ID; the
format used and a name and description for the template; the language encoding used; and
information about attachments associated with this template.
To include graphic elements in your email, you can add these as attachments to the template in the
AR System Email Templates form. You must store templates in the AR System Email Templates
form before you can use them.
For more information, see Storing templates in the AR System Email Templates form .
Fields on the AR System Email Templates form
Field name
Description
Template
Format
Choose the format of template, either Text or HTML.
Encoding
Choose the language setting used to read and parse the contents of templates. If no setting is specified, the default
encoding of the local system is employed.
Template
Name
Enter the name of the email template. The contents of the Template Name field are automatically populated if you
attach a new file, then click inside the field. You can edit the name as needed. After saving your template, the AR
System Email Templates form uses data-driven workflow to populate menus in the Email Engine forms that use
templates, for example, when you add an email template to a Notify action.
Description
(Optional )
File Name
Select the template files from the Attachment field. Includes size and label information.
Add
Attachment
button (
HTML
templates
only)
Click to open the AR System Email Attachments form in New mode. Lets you select and add an attachment (for
example, HTML file or bitmap) that is always used with a specific template.
Page 1694 of 4705
Home
Field name
Description
Modify
Attachment
button (
HTML
templates
only)
Click to open the AR System Email Attachments form in Search mode so you can modify an attachment. The
template will not be available for use until the Email Engine cache is updated.
Delete
Attachment
Click to delete the attachment from AR System Email Attachments form.
button (
HTML
templates
only)
Refresh
Table
button (
HTML
Click to refresh the table after you have added, modified, or deleted an attachment.
templates
only)
Add
Existing
menu (
HTML
templates
only)
Adds an existing attachment to the template.
AR System Email User Instruction Templates form

Use the AR System Email User Instruction Templates form to store administrator-defined
instructions for specific actions, and to associate those instructions with a template defined in the
AR System Email Templates form. These instructions can include variables whose values are
provided when the instructions are executed. For each instruction template, the form provides the
template name, name of the mailbox with which the instructions are associated, and the
instructions themselves.
For more information, see Sending incoming email with user instructions .
Fields on the AR System Email User Instruction Templates form
Field name
Description
Instruction Template
ID
System-generated unique ID. The contents of this field are read-only.
Template Name
Menu lets you select template that is executed as the content of user instruction and used in the email.
Mailbox Name
Menu lets you associate incoming mailbox used with user instruction.
Instruction
Valid character string consisting of Action label and value used to access user instruction field.
Page 1695 of 4705
Home

Use the AR System Email Error Logs form to store logs of errors that have occurred during email
transmissions, as well as all incoming and outgoing mail messages, log connection status
information for email servers and the AR System server, start and stop times for the Email Engine,
and configuration changes. Each log entry includes the ID for the mailbox and the message, the
message type, message number, how the error message was generated, and the text of the error
message.
For more information, see Email error and system status logs.
Fields on the AR System Email Error Logs form
Field name
Description
Log Message ID and
Message ID and date on which error was created.
Create Date
Mailbox ID Number
Number of the message to which the log applies.
Message Type
Either an error log or a status log and the severity level of the message. Severity levels are as follows:
Severe: Errors that prevent successful execution of a specific task and might require administrator
intervention. This is the default value.
Warning: Errors that can cause problems when executing a task.
Info: Status information.
Config: Information related to mailbox configuration. For configuration information, see
Configuring outgoing mailboxes and Configuring incoming mailboxes.
Fine: Internal exceptions, which are handled by the application but logged for tracing purposes.
Finer: Trace logs that record specific tasks as they are executed within the application.
Message Number
Error number associated with the message.
Generated By
Error generated either by the Email Engine or by the AR System server.
Message Text
Description of the error.
AR System Email Security form

Use the AR System Email Security form to either create and enable or disable security keys for
incoming mail. A security key can be assigned to an individual incoming mailbox, or to all incoming
mailboxes.
For more information, see Configuring incoming mailbox security.
Fields on the AR System Email Security form
Field name
Description
Security ID
System-generated unique ID. The contents of this field are read-only.
Status
Menu that lets you activate the key. Select Disabled to keep the key disabled.
Page 1696 of 4705
Home
Field name
Description
Key
Name of key consisting of a set of alphanumeric characters. You can use almost any combination of
letters and numbers for a security key.
User Name
Name of a valid BMC Remedy AR System user to whom the security key should apply.
Force for Mailbox
Enables the security key for this mailbox only. Select No to enable the key for all mailboxes in your email
environment.
Mailbox Name
Name of the Incoming Mailbox to which you want this security key applied.
Force from Email

Addresses
Key required for mail received from specific email accounts. If you select Yes, the Email Address field
becomes enabled.
Email Addresses
Option that verifies incoming messages from a set of specific email accounts using a security key.
Note
To configure multiple email address for a single security key, you must separate the email
addresses with a semicolon (;).
Expiration Date
Expiration date for this security key. After the key expires, you can either modify the expiration date in this
form, or set the Expires field to No.
Description
Description for the key, such as why it was created or instructions for modifying or deleting it.
Email Engine user forms

This section contains information about the user forms available with the Email Engine:
AR System Email Attachments form
AR System Email Attachment Join form

In this topic:
Message tab
Attachments tab
Errors tab
Use the AR System Email Messages form to store information for outgoing and incoming email
messages. Each message is stored as an entry in the AR System Email Messages form.
For each message, this form provides the name of the mailbox from which the message was
generated, the message type, name and organization of the mailbox owner; names of recipients
sent to and copied; the text of the message (in HTML, plain text format, or a combination of both);
Page 1697 of 4705
Home
and (under a separate tab) a list of any attachments included with the message.
For information about using the Email Messages form to troubleshoot traffic between incoming and
outgoing email, see Setting up outgoing email.
Fields on the AR System Email Messages form
Field name
Description
Mailbox Name
Name of configured mailbox.
Mailbox Type
Display Advanced Options
Select Yes to display the advanced options available for viewing email information and errors.
Message tab
Fields on the AR System Email Messages form Messages tab
Field name
Description
From
Name of the mailbox the email is sent from.
Reply To
Reply-to email address for the mailbox owner or administrator, if you plan to enable users to reply to notification
messages sent from this mailbox.
Organization
For email clients that display an organization name, the name of the mailbox owner, or administrator's
organization.
To
Email addresses for those who should receive outgoing messages from this mailbox.
CC
Email addresses for those who should receive copies of outgoing messages from this mailbox.
BCC
Email addresses for those who should receive blind copies of outgoing messages from this mailbox.
Subject
Subject line for your email.
Priority
Value to use in the email message to get the desired Microsoft Outlook priority. Numbers from 1 to 100 are
acceptable.
Attachments tab
Fields on the AR System Email Messages form Attachments tab
Field name
Description
Add Attachment
Includes attachment with outgoing email.
Modify Attachment
Lets you modify attachment or attachment name.
Delete Attachment
Removes attachment from outgoing email.
Refresh Table
Refreshes table after you have added, modified, or deleted an attachment.
Add Existing
Includes previously saved attachment with outgoing email.
Page 1698 of 4705
Home

Fields on the AR System Email Messages form Advanced Options tab
Field name
Description
Templates tab
Header Template
Template to be used as the header template.
Content Template
Template to be used as the content template.
Footer Template
Template to be used as the footer template.
Variable Replacement tab

Field Values
Value for a variable in the template.
AR System Server
With qualification variables, name of the server on which the form resides.
AR System Server TCP

Port
With qualification variables, any access information necessary.
AR System Server RPC

Number
AR System Form
With qualification variables, name of the AR System form to which these values apply.
Qualification
Query used to retrieve data and substitute it in the email.
Attachment Alternatives tab

Attachment Alternatives
(attachment pool)
Attachment pool enables you to add the content of your email as a plain text, HTML, or RTF
attachment, instead of typing it into the Body field in the Message tab.
Plain Text Content

Attachment Encoding
Language encoding used.
HTML Content
Attachment Encoding
RTF Content
Attachment Encoding
Values Attachment
Encoding

Fields on the AR System Email Messages form Message Information tab
Field name
Description
Message ID
The unique value that identifies the message.
Date
Received
The date on which the message was sent; this value is retrieved from the Date header of the incoming message.
Date Sent
The date on which the message was sent; applicable to outgoing messages only.
Page 1699 of 4705
Home
Field name
Description
Execute/
Send At
The timestamp of when the incoming message was executed, or when the outgoing message was sent.
Parse
Message
The parsing status of the message; applicable to incoming messages only. The options and their meanings are:
No The message has not yet been parsed.
Yes The message is still in the incoming queue.
Error An error occurred when parsing the message.
Parsed & Executed The message was successfully parsed and executed.
Send
Message
The sending status of the message; applicable to outgoing messages only. The options and their meanings are:
No The message has not yet been sent.
Yes The message is still in the outgoing queue.
Error An error occurred when sending the message.
Sent The message was successfully sent.
Error Sending-Retrying The Email Engine is trying to send the message again, because an error
occurred at the previous attempt.
Errors tab
Enables users to view error messages if their email is not sent correctly.
Fields on the AR System Email Messages form--Errors tab
Field name
Description
Log Message Type
If a request fails to submit, the original message is returned as an attachment.
Log Message Number
The error message number.
Create Date
The creation date of the error message.
Log Message Text
If a request fails to submit, the error message that indicates the reason for the failure is returned.

In this topic:
Copying incoming messages to the AR System Email Messages form
To copy the rectified incoming messages to the AR System Email Messages form
Enabling the Clean AR System Email Error Messages escalation
Message tab
Attachments tab
Errors tab
The AR System Email Error Messages form stores any incoming email message that has not been
processed correctly due to any runtime error, along with the error details.
Page 1700 of 4705
Home
Note
This form stores information only for incoming email messages.
Warning
(For incoming mails that have not been processed correctly due to any runtime error) The
Email Engine considers the HTML format, by default. If the incoming message is in a plain
text format, Email Engine first checks for the HTML format and when not found, considers
the plain text format. But, if the incoming mail is in a plain text as well as HTML format, the
Email Engine only considers the HTML format. For the Email Engine to consider the plain
text format, change the HTML format to a plain text format (without any spaces) or clear
the HTML format.
Copying incoming messages to the AR System Email Messages form

After manually rectifying the errors, you can copy these incoming messages to the AR System
Email Messages form.
Note
BMC recommends that you perform the rectification process individually on every error
out email message. Do not perform the rectification process on more than one email
message at the same time using the 'Modify All' option.
To copy the rectified incoming messages to the AR System Email Messages form
1. From the Message Information tab, change the status of the message to Yes.
2. Click on the Copy to AR System Email Messages Form button. After the rectified
messages are copied to the AR System Email Messages form, the Email Engine processes
the incoming actions at the next polling interval. However, if there are messages in the
incoming queue, the rectified messages are parsed at the next polling interval. Increase the
time of the polling interval, if you want to parse the rectified messages in spite of the
messages in the incoming queue.
The messages stored on the AR System Email Error Messages form, are not deleted even
after they are moved to the AR System Email Messages form. The administrator can
configure the period and the conditions for deleting these mails using the "Clean AR System
Email Error Messages" escalation.
Note
Page 1701 of 4705
Home
This escalation is disabled by default.
Enabling the Clean AR System Email Error Messages escalation

Follow the steps given below to enable the Clean AR System Email Error Messages escalation.
1. Go to Escalation > Execution Options.
2. Change the value of the State field to Enabled.
3. (Optional) Change the Escalation period in accordance with your requirements from the
default value of 15 days.
Note
Additional conditions can be set using the Run Process field.
4. To clean up the system logs, restart the BMC Remedy Email Engine.
All the messages in the AR System Email Error Messages form will be deleted depending
upon the conditions set in the escalation. For each message, this form provides the name of
the mailbox from which the message was generated, the message type, name and
organization of the mailbox owner; names of recipients sent to and copied; the text of the
message (in HTML, plain text format, or a combination of both); and (under a separate tab) a
list of any attachments included with the message.
Fields on the AR System Email Error Messages form
Field name
Description
Mailbox Name
Name of configured mailbox.
Mailbox Type
Message tab
Fields on the AR System Email Error Messages form--Messages tab
Field name
Description
From
Name of the mailbox the email is sent from.
Reply To
Reply-to email address for the mailbox owner or administrator, if you plan to enable users to reply to notification
messages sent from this mailbox.
Organization
For email clients that display an organization name, the name of the mailbox owner, or administrator's
organization.
To
Email addresses for those who should receive outgoing messages from this mailbox.
CC
Email addresses for those who should receive copies of outgoing messages from this mailbox.
Page 1702 of 4705
Home
Field name
Description
BCC
Email addresses for those who should receive blind copies of outgoing messages from this mailbox.
Subject
Subject line for your email.
Priority
Value to use in the email message to get the desired Microsoft Outlook priority. Numbers from 1 to 100 are
acceptable.
Attachments tab
Fields on the AR System Error Messages form--Attachments tab
Field name
Description
Add Attachment
Includes attachment with outgoing email.
Modify Attachment
Lets you modify attachment or attachment name.
Delete Attachment
Removes attachment from outgoing email.
Refresh Table
Refreshes table after you have added, modified, or deleted an attachment.
Add Existing
Includes previously saved attachment with outgoing email.

Fields on the AR System Email Error Messages form--Advanced Options tab
Field name
Description
Templates tab
Header Template
Template to be used as the header template.
Content Template
Template to be used as the content template.
Footer Template
Template to be used as the footer template.
Variable Replacement tab

Field Values
Value for a variable in the template.
AR System Server
With qualification variables, name of the server on which the form resides.
AR System Server TCP

Port
AR System Server RPC
Number
AR System Form
With qualification variables, name of the AR System form to which these values apply.
Qualification
Query used to retrieve data and substitute it in the email.
Attachment Alternatives tab

Attachment Alternatives
(attachment pool)
Attachment pool enables you to add the content of your email as a plain text, HTML, or RTF
attachment, instead of typing it into the Body field in the Message tab.
Page 1703 of 4705
Home
Plain Text Content

Attachment Encoding
HTML Content
Attachment Encoding
RTF Content
Attachment Encoding
Values Attachment
Encoding

Fields on the AR System Email Error Messages form--Message Information tab
Field name
Description
Message ID
The unique value that identifies the message.
Date Received
The date on which the message was sent; this value is retrieved from the Date header of the incoming
message.
Date Sent
The date on which the message was sent; applicable to outgoing messages only.
Execute/Send At
The timestamp of when the incoming message was executed, or when the outgoing message was sent.
Parse Message
The parsing status of the message; applicable to incoming messages only. The options and their meanings
are:
No--The message has not yet been parsed.
Yes--The message is still in the incoming queue.
Error--An error occurred when parsing the message.
Parsed & Executed--The message was successfully parsed and executed.
Errors tab
Enables users to view error messages if their email is not sent correctly.
Fields on the AR System Email Error Messages form--Errors tab
Field name
Description
Log Message Type
If a request fails to submit, the original message is returned as an attachment.
Log Message Number
The error message number.
Create Date
The creation date of the error message.
Log Message Text
If a request fails to submit, the error message that indicates the reason for the failure is returned.
AR System Email Attachments form

Use the AR System Email Attachments form to create, display, and modify information about
attachments used with emails and templates, including incoming email. For each attachment, the
form provides a unique ID, the type of attachment (for example, a text file), the name of the
attachment, whether the attachment is an email attachment or a template attachment, the file name
Page 1704 of 4705
Home
, size, and label.

Administrators can access this form from the Template form if an attachment is needed for a new
template. Users can access attachments from this form when they compose an email message.
Fields on the AR System Email Attachments form
Field name
Description
Type
Email or Template attachment. Used for storing attachments for both incoming and outgoing emails. It also
stores attachments for templates, such as a graphic for an HTML template.
Attachment
Name of attachment.
Name
File Name (
attachment pool)
Enables users to view error messages if their email was not sent correctly.
AR System Email Attachment Join form

The Email Engine uses the AR System Email Attachment Join form for mapping attachments to
email messages.
Warning
Because this information is used internally by the Email Engine, you should not create or
modify entries in this form.
Email Engine workflow forms

This section contains information about the workflow forms available with the Email Engine.
AR System Email Instructions form
AR System Email Instruction Parameters form
AR System Email Association form
AR System Email Instructions form

The Email Engine uses the AR System Email Instructions form to store instructions obtained when
incoming email is parsed.
Warning
Page 1705 of 4705
Home
AR System Email Instruction Parameters form

The Email Engine uses the AR System Email Instruction Parameters form to store parameters
specified for administrator-defined instructions.
Warning
Because the information in this form is used internally by the Email Engine to store
instructions, you should not create or modify entries in this form.
AR System Email Association form

The Email Engine uses the AR System Email Association form to store associations between an
email message and one or more attachments, or between a template and one or more attachments
.
For incoming messages, this information includes the association between the message and
any attachments included with the message.
For outgoing messages, this information includes associations for attachments that should
be included when the message is sent.
For each association, the form provides:
Unique ID.
Source type (email or template). If the source type is template, the form reflects the
association between a template and any attachments that should be included when that
template is used. An example is an HTML template with graphics that must be included to
make sure that the message is displayed correctly.
Source ID (the ID of the email or template).
Destination type (email attachment).
Destination ID (the ID of the attachment).
This association enables multiple emails to be associated with one attachment, or one email to be
associated with multiple attachments.
Warning
Page 1706 of 4705
Home

The following topics provide information about how to set up an approval process:
Approval Server concepts
Using the Lunch Scheduler sample application
Worksheets for setting up processes and rules
Approval forms
Running the approval utilities
Approval Server concepts

An approval requires a process for people to acknowledge, approve, or reject an approval request.
This section contains information about the concepts that process administrators must understand
to configure and maintain approval processes for BMC Remedy Approval Server.
In this topic:
Approval processes
Approval roles
Approval processes
An approval process is a set of rules and procedures, based on data, that enforce processes and
workflow to require the appropriate people to review, approve, and reject requests.
A process must have rules to make sure all required approvals occur, no erroneous
approvals occur, and sufficient authority is present to enable approval.
A process must have procedures to route an approved request to the next approver, to stop
routing a rejected request, and to notify a person when a response is required.
Every approval requires a process to obtain appropriate signatures. Business processes often
require the signatures of several people in one or more operational groups. Business processes
also need to allow for alternate approvers to cover days when the regular approvers are
unavailable.
A given request might require one simple approval process, or several processes that work with
each other. Often the appearance of a single operation involves multiple approvals. Some requests
must follow a process, but can be approved automatically based on certain criteria.
In Approval Server, an approval process is the set of rules and forms that generate data to
authorize specific BMC Remedy AR System workflow. An approval process consists of definitions
for the operation itself, rules that define what happens at each specific stage in the process, and a
Page 1707 of 4705
Home
place to store signatures. While process administrators need to understand these rules, they are
transparent to approvers. The types of rules and how they interact are described under Approval
rules.
The data generated by an approval process, such as the type of approval, approver signatures,
requests for more information, and time stamps for audit trails, is stored in the detail record and
other supporting forms. This enables you to track the approval process for auditing or
troubleshooting purposes. For more information about data, see Approval data and audit.
Approval roles
Three roles are involved in the approval process: those requesting approval (requesters), those
approving requests (approvers and alternate approvers), and process administrators who set up
and modify the BMC Remedy Approval Server configuration.
Most approval processes are transparent to requesters, who therefore do not need a thorough
understanding of Approval Server. This document is primarily written for approvers and process
administrators.
Requesters
Requesters are people who want something to be approved. Requesters work with an application
that starts an approval process by entering an approval request. Approval requests are routed to all
required approvers according to the rules of the approval process.
Approval Server allows requesters to enter approval requests, check the status of their requests,
and responds to More Information requests.
Approvers
Approvers are people who have the authority to approve, reject, reassign, hold, or provide
questions and comments for a request in a approval process.
The process administrator configures approvers for each process, so that each request has a
specified approver list. Different requesters can have different approver lists for the same process.
An approver list specifies the exact list of signatures required for a request. A signature can come
from an individual or from a business role containing multiple individuals, such as department
managers. Approval Server allows you to work with any combination of individuals and roles to
create the approver list for each process.
Approvers review outstanding requests that are assigned to them, and to take action on those
requests. Approver actions are performed using Approval Central, which is the Approval Server
console. (For more information, see Approval Central.) The actions approvers can take include:
Approving
Rejecting
Page 1708 of 4705
Home
Reassigning
Holding
Requesting and responding to More Information Requests
Checking status
Approvers have access to the details of the request being processed as well as to the request
history. The history includes a list of all approvers who have responded to the request, and the
actions they took. Also, any comments that have been entered by other approvers are available for
review.
If approvers need to obtain more information before approving a request, they can send a More
Information request to any BMC Remedy AR System user. A More Information request is separate
from the approval request, but remains associated with it.
Alternate approvers
When an approver will not be available, such as during a business trip or vacation, the approver
can define an alternate approver who has the same authority within an approval process. An
alternate is someone who substitutes for the approver and acts with the approver's authority and
privileges for a duration of their choice.
Approvers can to set up any number of alternates. Each alternate can be set up to substitute within
one or more approval processes.
Process administrators
The process administrator is a user who has permission to carry out design and administration
tasks in Approval Server. Process administrators perform the following tasks:
Defining Approval Server processes and rules
Overriding the normal flow of a process when an emergency situation requires it
Granting limited authority to specified users, allowing them to configure a process to override
a process, or both
Designating alternates for any approver
Process administrator actions are performed by using the AP:Administration form.
Note
Approval Server process administrator is not the same as the BMC Remedy AR System
administrator. See Approval data and forms for an explanation of the process
administrator's responsibilities.
The following topics provide information about approval forms, processes, rules, and fields:
Page 1709 of 4705
Home
Approval data and forms

Approval processes
Approval rules
Approver fields
Approval data and forms

BMC Remedy Approval Server uses data created by the process administrator and data generated
during the approval process to carry out each approval tasks.
The following topics provide information about the types of approval server data:
Approval data and audit
Approval server supporting forms
Approval data and audit

As an approval request is routed through the approval process workflow, the approval server
collects data about the request in the request form and the other supporting forms. Some of this
data is temporary, for use only during the process, while other data, such as signatures, is saved
for audit purposes.
Because approval server processes are designed to implement business processes and rules, you
can use the following data as an audit trail for any process that uses the approval server:
The original request
Electronic signatures of every person who approves or rejects a request
More information requests and their responses
Dates and times for each approval activity
You can also use approval server logging to record data about all requests and responses, as well
as to track the configuration changes made by the process administrator or AR System
administrator. For information about how to activate approval server logging, see Working with the
AP-Administration form.
Approval server supporting forms

In this topic:
Approval Central
Detail form
Signature form
Detail-Signature form
Approval request form
Three-way join form
More Information form
Signature authority form
Page 1710 of 4705
Home
A set of standard forms and related workflow objects are installed along with approval server. Most
objects are named with the prefix "AP,". Sample application objects are named with either "
AP-Sample" or "AP-Sample2." The standard forms are described in more detail in Adding
approvals to an application and Administration forms. This section introduces some of the basic
forms for ease of reference.
Approval Central
See Overview of Approval Central.
Detail form
All data about an approval request are stored in the AP:Detail form. You can use this form to
determine the status of a request, and to see a history of activity on the request for any approval
process.
Signature form
All data about signatures associated with an approval request is stored in the AP:Signature form.
Administrators can use this form to review the responses to a request.
Note
Modify signatures only through Approval Central.
Detail-Signature form
The AP:Detail-Signature join form joins data from the AP:Detail and AP:Signature forms. You link
this form to your application's approval request form to create a three-way join form when you add
approvals to your application.
Approval request form

Any application that uses approval server must have an approval request form that users open to
enter their approval requests.
For example, in the sample applications, the application request forms are AP-Sample2:Get
Agreement and AP-Sample:Lunch Scheduler.
Three-way join form

When you link your application to approval server, you must create an inner join form by linking
your application request form to the AP:Detail-Signature form. Because the AP:Detail-Signature
form is also a join form, this join is referred to as a three-way join.
Page 1711 of 4705
Home
For example, in the Get Agreement sample application the three-way join form is AP-Sample2:
Issue Detail Signat. It joins AP-Sample2:Get Agreement with AP:Detail-Signature.
See Creating the join forms. For general information about join forms, see Join forms.
Note
If you change the status of a request from an application's three-way join form, the change
is not reflected immediately on Approval Central. Users must click on a link on Approval
Central or refresh the page to see the change. To make such a change visible
automatically, application developers must provide workflow that sends the refresh event
to the Approval Central form on the Modify or Close event of the three-way join form.
Without such workflow, the Approval Central form cannot know about changes to a
request, because the status change activity does not occur on the form.
More Information form

The AP:More Information form stores and displays More Information requests and responses that
pertain to the related approval request form.
Signature authority form

For Parent-Child and Level process types, you create a signature authority form to define the
relationships between approvers or levels.
For example, the Lunch Scheduler sample application uses the AP-Sample:Signature Authority
form.

The Application Pending form stores commands from any Application-Command process.
Whenever an Application-Command process runs, BMC Remedy AR System creates a request in
this form that contains details about the command. The Application Dispatcher retrieves commands
from this form and passes them to the approval server for processing. If the Application Dispatcher
is not in use, the approval server retrieves commands directly from this form.
Approval processes
An approval process is the routing of an approval request through a defined series of steps until the
process is done. The approval process requires signatures and is governed by approval server
rules and behavior. You can use approval server to automate any business process, and you can
customize the process to implement the operational guidelines of your organization. By using
approval server, you can make sure that any process follows well-defined rules, that the right
people are notified and the correct signatures are obtained, and that you can provide an audit trail
of requests and the decisions made by approvers.
Page 1712 of 4705
Home
The following topics provide information about approval processes:

Difference between processes and rules
Approval process stages
Approval process types
Summary of process types
Creating signatures for multiple approvers
Associating an action date for a process or signature
Difference between processes and rules

Understanding the difference between an approval process and the rules it uses is critical to
implementing a business process with approval server.
An approval process defines the routing of any item that requires signatures. An approval
process can consist of many operations, transitions, and decision points, each contributing
toward a defined destination. The approval process ensures that all the necessary steps
take place to implement a business operation that requires signatures or approvals, such as
approving new hires or signing purchase orders. In each case, the overall process is the
same each time it is performed.
For more information about approval processes, see Approval process types.
Approval rules augment the standard behavior of the approval server, and govern how an
approval request is handled at various stages of the approval process. You use rules to
retrieve and save approval data and to make decisions during the process, such as who the
next approver is, whether more signatures are needed, and whether the routing process is
complete.
For more information about approval rules, see Approval rules.

The approval process ensures that all the necessary steps take place to complete any approval,
while rules govern how the request is handled at various stages of the process.
The following figure illustrates the five stages of any approval process. The approval server checks
for rules belonging to each stage during the approval process. Any given approval process does
not require rules in all five stages, but most approval processes include rules in at least the
approver response and Process Done stages.
Depending on the process design and the rules used, the approval cycle can include several
iterations of the next approver, approver response, and Completion Check stages.
Page 1713 of 4705
Home
An approval process starts when someone submits an approval request.

Stage 1, Self Check If the process includes either Auto Approval or Self Approval rules,
the approval server immediately applies them to determine whether the requester has
sufficient authority to approve his or her own request. If so, the approval process is done and
the approved request is returned to the requester.
Stage 2, Next Approver (routing) If no Auto Approval or Self Approval rules are included
in the process, or if the Self Check stage determines that the request must be routed to an
approver, the Next Approver stage begins. For most process types, the approval server
applies one or more next approver rules to start a cycle of identifying people who need to
approve the request. (The exception to this is the Ad Hoc process type, as explained in
Approval process types.) The Next Approver stage is repeated until all approvers have
received the request.
Stage 3, Approver Response In this stage of the process, approvers either approve or
reject an approval request. This action completes the signature line for that approver. If an
approver approves the request, the approval process continues. If an approver rejects the
request, the approval process is usually done. (You can override this behavior with Signature
Accumulator and Statistical Override rules).
The Approver Response stage is repeated as necessary, and is closely integrated with the
Completion Check stage.
Stage 4, Completion Check The Completion Check stage accepts the results of the
Approver Response stage, and checks to see if the routing of a request is complete. Routing
is complete if all required approvers have received the request, whether they have
responded. If all required approvers have not received the request, the process returns to
the Next Approver stage.
The Completion Check stage is repeated as necessary until the Completion Check passes.
Stage 5, Process Done The approval process is done when the request is approved by
all (or enough) required approvers, or when it is rejected. This stage is also done if an error
state is recorded or if the request is cancelled. During this stage, the approval server
determines whether the approval was successful, and takes appropriate action, such as
delivering a notification of the completed request to the requester.
Note
Page 1714 of 4705
Home
The difference between "complete" and "done" is important. When a request is complete,
it has been routed to all approvers. Even when routing is complete, all required approvers
have not necessarily responded. The request is done when all required approvers have
approved or rejected the request.
Approval process types

The Approval Server provides process types that you can choose from when designing an approval
process. The following process types differ in how the approval server identifies the next approver:
Parent-Child process
Level process
Ad Hoc process
Rule-Based process
For an example of each process type, examine the sample applications installed with approval
server. For information about how to create, modify, and delete processes, see Defining an
approval process. For information about rules and how they are used with each process type, see
Approval rules. For information about creating rules, see Defining approval rules.
Parent-Child process
The Parent-Child process type uses the relationships between requesters and approvers, and
between approvers and other approvers, in conjunction with a Get Next Approver rule, to determine
the routing of an approval request. You define these relationships in a signature authority form.
The Management Cost Authorization process in the Lunch Scheduler sample application is an
example of a Parent-Child rule. It uses the Manager Login Name field on the AP-Sample:Signature
Authority form to define the "parent" login name of each sample user.
In a process where each approver has a defined relationship to the next approver, such as
employee to manager and manager to director, the most appropriate process type is usually
Parent-Child. In this type of process, the approval request is routed up an approval hierarchy from
the "child" (requester or previous approver with lower authority) to the "parent" (approver with
higher authority). A manager-employee relationship is often the hierarchy represented with a
Parent-Child approval process.
The following figure illustrates an example Parent-Child process, in which an engineering change
must be approved by a hierarchy of approvers.
Parent-Child hierarchy
Page 1715 of 4705
Home
In a Parent-Child process, the approval server automatically routes the request to the next approver
according to the defined relationship. Persons represented by "X" in the diagram do not receive the
approval request because they do not have parent relationships with the requester or any
approvers.
A rejection from any approver rejects the request for everyone in the hierarchy. This is also true if
the process uses two or more separate approval hierarchies. Process administrators can configure
notifications to inform all approvers when any other approver has rejected a request.
The following considerations apply to a Parent-Child process:
A Parent-Child process requires a Get Next Approver rule that defines how to find the next
approver. This rule must include the name of the field containing the identity of the parent
and must return the Approver List, which is a string of individuals or roles. See Defining Get
Next Approver rules.
When an approver marks an approval request as approved, the approval server
automatically checks for the parent of that approver and, if one is found, routes the request
to that person.
When it generates the first Approver List for a Parent-Child process, the approval server
assumes that the "previous" approver is the originator of the approval request (the requester)
. This means that the parent of the requester becomes the first approver.
Level process
The Level process type uses a hierarchical set of organizational levels, in conjunction with a Get
Next Approver rule, to determine the routing of an approval request. The process administrator
defines the organizational levels and their members in a signature authority form.
Page 1716 of 4705
Home
The Major Account Level Approval process in the Lunch Scheduler sample application is an
example of a Level process. It uses the Account Approval Level field of the AP-Sample:Signature
Authority form to define organizational levels and the sample users who belong to them.
If anyone in a certain organizational position, such as a job level, can approve a request, the Level
process type is often the best fit. In a Level process, the approval server delivers the request to all
approvers in the next level. When the defined number of approvers in any level have approved the
request, the approval server routes the request to the next level.
The following figure illustrates a request for a soft drink machine to be placed in a company
courtyard. The request must be approved by the refreshment, landscape, and maintenance
committees. The Level process defines the order in which the committees see the request.
Level process with three levels
In a Level process, a request must be approved by at least one approver in each level before it
passes to the next level. The approvers for a given level can consist of individuals or roles. A Level
process does not dictate the number of approvers on each level. You can set up routing to the next
level to require signatures from any number of individuals in each level. For information about
configuring roles, see Defining roles.
A Level process uses a level value to indicate the position of individuals or roles. The approval
server uses the value in the level field to determine an approval sequence, starting with level 0. The
highest level is 1000. The approval server skips over unused levels.
The following considerations apply to a Level process:
A Level process requires a Get Next Approver rule that defines how to find the next approver
. This rule must identify the name of the field containing the level identifier, and must return
two values: a level indicator, and a string of individuals or roles. See Defining Get Next
Approver rules.
The process rules must be configured to determine whether a request should be routed to
more than one person in each level.
Page 1717 of 4705
Home
Ad Hoc process
In an Ad Hoc process, no Get Next Approver rule is used, and the process administrator does not
define approver or organizational relationships. Instead, the requester and the approvers designate
the next approver or a set of approvers while working with the request. The requester enters at
least one approver when creating the request. Approvers can add additional approvers when they
respond to the request.
The Issue Approval process in the Get Agreement sample application is an example of an Ad Hoc
process.
Routing two requests in the same Ad Hoc process
Note
An Ad Hoc process is not the same as an ad hoc override. Ad hoc overrides allow specific
approvers to alter a predetermined routing. An Ad Hoc process includes no predetermined
routing. See Get next approver manually.
When entering approvers, users must enter the exact AR System login ID of the next approver. To
prevent typographical errors and allow users to select from a list, the AR System administrator must
construct field menus that contain the appropriate approvers for an Ad Hoc process. See Working
with menus.
Rule-Based process
The Parent-Child, Level, and Ad Hoc process types are partially preconfigured and, therefore, are
relatively simple to implement. A Rule-Based process is similar to a Parent-Child process, except
that a Rule-Based process relies on rules that you create to define the relationships between
approvers. This option enables you to define a routing method that allows more complexity than
predefined relationships. However, a Rule-Based process requires more thought and work to
Page 1718 of 4705
Home
implement.
The Special Overdue Approval process in the Lunch Scheduler sample application is an example of
a Rule-Based process.

Processes and their rules are configured by a process administrator. Approval server handles
approval requests with one of the following process types:
Process
type
Routing method
Determining next approver
Parent-Child
Hierarchy of individuals. The process

administrator defines the relationships
between individuals.
Get Next Approver and Parameterized Get Next Approver rules

determine the relationship of the next approver to the current
owner.
Level
Hierarchy of organizations. The process

administrator defines the levels and their
Get Next Approver and Parameterized Get Next Approver rules

determine the next level and approvers.
members.
Ad Hoc
Routing is based on the approvers entered by

the requester or approvers.
Determined manually by users.
Rule-Based
Custom, as determined by the process

administrator.
Determined by the Process Administrator. Parameterized Get

Next Approver rules can add approvers.
Creating signatures for multiple approvers

An approval request can be assigned to multiple approvers. Administrators can specify how to
manage responses to such a request at the process, rule, or role level. Administrators use the If
Multiple Approvers setting for this purpose.
The options are:
One Must Sign Creates a single signature entry for all the relevant approvers. Only one
of the approvers needs to take action.
All Must Sign Creates a separate signature entry for each approver. All approvers must
take action for the request to proceed further.
(Process-level only ) Allow Only One Approver Creates a single signature entry for an
approver. If a requester specifies multiple approvers for a request, the approval server
returns an error.
Associating an action date for a process or signature

In this topic:
How the action date for a Parent-Child or Level process is calculated
How the action date for an Ad Hoc process is calculated
Page 1719 of 4705
Home
Each approval server process and signature can be associated with an action date . The action
date enables approvers to know in advance the duration within which to take action on requests
assigned to them. Process administrators can use this value to determine whether a process is on
track or needs intervention (automatic or manual). This helps in addressing requests and driving
them to completion in a timely manner. The action date is based on the Automatic Action interval
defined for a process. For more information, see Approval Central.
The action date is calculated by using the following fields on the tabs of AP:Process Definition:
Configuration Process Due, Signature Due, Buffer Period, and Enable Preview
Signature Escalations Automatic Action and Notification (First) intervals
Applications can override the Process Due interval by directly passing the desired Process Due
Date as a parameter of the New-Details command. For more information, see BMC Remedy
Approval Server application commands.
The action dates for processes and signatures are stored in the following fields:
Process Due Date (ID 11000) on AP:Detail
Signature Due Date (ID 12000) on AP:Signature
Note
Using Enable Preview to determine the action date might increase the processing time for
a new request due to the steps required to retrieve the list of future approvers.
When working with notifications and escalations, make sure that the appropriate notification and
escalation types on AP:Admin-ServerSettings are enabled.
How the action date for a Parent-Child or Level process is calculated

When the first signature is created for a request, the Process Due Date is either derived from the
Process Due period defined on AP:Process Definition, or set to the value sent by the application
through New-Details. If the application specifies the Process Due Date value, the value in Process
Due field is ignored.
If Enable Preview is set to Yes, the total number of approvals in the process is calculated by
fetching the future approvers with the help of the Preview feature. The effective Signature Due
period is calculated as follows:
signatureDue = (Process Due /
<totalNumberOfApprovals>)
This value is then compared with the one specified in the Signature Due field, and the minimum of
the two is considered.
Page 1720 of 4705
Home
effectiveSigntaureDue = MIN (Signature Due, signatureDue)
If no value is entered in the Signature Due field, the derived signatureDue is used for further
computation.
The action date for a signature is calculated as follows:
Action Date = MIN (effectiveSignatureDue,

Automatic Action interval-Buffer Period,
Escalation interval-Buffer Period)
For more information, see Creating signature escalations.
How the action date for an Ad Hoc process is calculated

When the first signature is created for a request, the Process Due Date is either derived from the
Process Due period defined on AP:Process Definition, or set to the value sent by the application
through New-Details. If the application specifies the Process Due Date value, the value in Process
Due field is ignored.
The value of Enable Preview is ignored, because the ad hoc nature of the process makes it
impossible to identify the future approvers.
The action date for a signature is calculated as follows:
Action Date = MIN (Signature Due,

Process Due date-Buffer Period,
Automatic Action interval-Buffer Period,
Escalation interval-Buffer Period)
For more information, see Creating signature escalations.
Approval rules
The Approval Server includes the rule types that are used in various stages of an approval process.
A given process does not usually include all types of rules, and some do not include all process
stages.
This section introduces the rule types included with the approval server, and describes how they
function in the approval process. The following figure illustrates how each rule type fits into the
overall approval process.
Rule types in the approval process
Page 1721 of 4705
Home

Self Check stage
Next Approver stage
Approver Response stage
Completion Check stage
Process Done stage
Chained processes
Self Check stage

In this topic:
Auto Approval rules
Self Approval rule
The Approval Server uses the Self Check stage of an approval process to prevent unnecessary
routing. Rule types that you can use in the Self Check stage include:
Auto Approval
Get Authority or Get Authority Self
Self Approval
The Auto Approval and Self Approval rule types use different methods to determine whether the
requester has sufficient authority to approve his or her own request. The Get Authority and Get
Authority Self rules gather data to be used by the Self Approval rule.
Details of Self Check stage rules
Page 1722 of 4705
Home
Auto Approval rules

The approval server first tests for an Auto Approval rule. Automatic approval occurs when any user
has authority to approve a given request, independent of the user's role in the organization or within
the BMC Remedy AR System. When an Auto Approval rule condition is met, the request is done,
and moves directly to the Process Done stage. In Auto Approval rule, the rule condition contains
the authority criteria, which applies to all users.
For example, if an Auto Approval rule says that everyone in the company can be reimbursed for a
business lunch up to $40, and Frank requests approval for a $25 lunch, the Auto Approval condition
is met and the approval server uses the Auto Approval rule to automatically approve Frank's
request.
The Management Cost Authorization process of the Lunch Scheduler sample application contains
an example of an Auto Approval rule. To create an Auto Approval rule, see Defining Auto Approval
rules.
Self Approval rule

When a request fails the Auto Approval rule or no Auto Approval rule is present, the approval
server tests for a self approval condition. A Self Approval rule executes only when the current user
is the owner of the approval request. Its test uses Get Authority or Get Authority Self rules together
with Self Approval rules.
Get Authority and Get Authority Self rules

These two rule types collect data, such as a monetary amount, that determines the limits of the
current approver's authority. The information collected by either the Get Authority or Get Authority
Self rule is used by any Self Approval rules that exist in the process.
The difference between Get Authority and Get Authority Self rules is in when they run during the
approval process. The approval server runs Get Authority rules during both the Self Check stage
and the Completion Check stage of the approval process. It runs Get Authority Self rules only in the
Self Check stage. You determine which rule type to use based on the data you need to gather in
each stage of the approval process.
You can use a combination of get authority rule types in a process that requires more than one type
of get authority check. For example, a company's business rules might require one set of self
approval levels for expenses (such as $100 for regular employees, $200 for managers and above),
but another set of approval limits for major purchases (such as up to $5000 for managers and
Page 1723 of 4705
Home
higher expenses requiring three approvers including a Vice President). A process to support these
business rules would include two different signature authority forms. A Get Authority Self rule would
support the Self Approval rule, and a Get Authority rule would support the Get Next Approver rules.
The Cost Get Approval Authority rule in the Lunch Scheduler sample application is an example of a
Get Authority rule. To create Get Authority rules, see Defining all Get Authority rules.
Note
A third type of get authority rule, called Get Authority Regular, is performed only during
completion processing. See Get Authority rules and Get Authority Regular rules.
Self Approval rules

Self Approval rules test data collected by the Get Authority or Get Authority Self rules to determine
whether the requester has sufficient authority to approve the request. When a Self Approval rule's
conditions are met, the request is done.
The following is an example of a self approval rule: If Frank requests approval for a $50 business
lunch, the condition of the $40 Auto Approval rule is not met. In this case, the Self Check stage
continues with a Get Authority or Get Authority Self rule to collect Frank's employee status. The
data gathered shows that Frank has authority to approve lunches up to $100. The Self Approval
rule uses this data to test whether Frank has authority to approve his own $50 lunch.
The Cost Approve for Myself rule in the Lunch Scheduler sample application is an example of a
Self Approval rule. To create a Self Approval rule, see Defining Self Approval rules.
Next Approver stage

In this topic:
Get next approver automatically
Get next approver manually
In the Next Approver stage, the approval server determines to whom the request must be routed
next and creates the appropriate electronic signature lines. Depending on the process type and the
rules it contains, the approval server can automatically determine the next approver, or allow the
current approver to select the next approver. If the next approver is a role, more than one individual
can be eligible to sign one signature line. In this case, the first role member who responds
determines the outcome for that signature line. See Defining roles.
Rule types used in the Next Approver stage include:
Prep Get Next Approver
Get Next Approver
Page 1724 of 4705
Home
Parameterized Get Next Approver

Validate Approver
Get next approver automatically

To cause the approval server to determine the next approver, you use Prep Get Next Approver and
Get Next Approver rules.
Prep Get Next Approver rules

A Prep Get Next Approver rule gathers information to be used by Get Next Approver rules. (In the
rule name, "prep" is an abbreviation for "prepare.") In BMC Remedy AR System workflow terms,
Prep Get Next Approver rules use a Set Field action to place values in certain fields. The Overdue
Prep Get Next rule in the Lunch Scheduler sample application is an example of a Prep Get Next
Approver rule. To create a Prep Get Next Approver rule, see Defining Prep Get Next Approver rules
.
Get Next Approver rules
Get Next Approver rules are the heart of approval processing. They route requests to the next valid
approver and create a signature line for each required approver. When configuring an approval
process, the process administrator defines a list of valid approvers. Get Next Approver rules use
this approver data to determine who is next in the approver list and to create signature lines for
each approver.
The sample applications contain the following examples of Get Next Approver rules, in each type of
process where these rules are used:
Cost Get Next Approver, in the Management Cost Authorization process (a Parent-Child
process)
Level Get Next Level, in the Major Account Level Approval process (a Level process)
Overdue Assign Approvers, in the Special Overdue Approval process (a Rule-Based process
)
To create a Get Next Approver rule, see Defining Get Next Approver rules.
Get next approver manually

For some approval processes, it is appropriate to allow requesters or approvers to specify the next
approver, or to add an approver at another level. In this case, the approval server identifies the next
approver based on what the user enters.
Several situations allow approvers to designate additional approvers. These are:
An Ad Hoc process, which requires all approvers to be added by the users, as described in
Ad Hoc process.
An ad hoc override, in which you configure the process to allow approvers to alter the
predetermined routing. This is controlled by the Allow Ad Hoc Next Approver? field on the
Basic tab of the Process Definition form. See Creating a process.
Page 1725 of 4705
Home
A Parameterized Get Next Approver rule, which works together with the preview feature and
an application command to pass run-time variables to the approval server.
When the process allows users to add approvers, use a Validate Approver rule to verify the added
approver against a list of valid approvers.
Parameterized Get Next Approver rules

A Parameterized Get Next Approver rule enables approvers to add another approver anywhere in
the approval hierarchy (not necessarily the next approver) at runtime. This rule type works together
with the preview feature, and uses the Add-PGNA-Values application command to provide
variables to the approval server. See Setting user preferences.
The Parameterized Get Next Approver rule works exactly like a Get Next Approver rule, with the
following exceptions:
Run-time variables can be part of the qualification and Set Fields operations.
Approvers can be added to any level, not just the next level.
After any Get Next Approver rules are executed, the server executes all Parameterized Get Next
Approver rules. If a Parameterized Get Next Approver rule exists, but the current record does not
have any parameters, the rule is skipped.
To create a Parameterized Get Next Approver rule, see Defining Parameterized Get Next Approver
rules.
Validate Approver rules

The approval server uses Validate Approver rules to protect against inappropriate ad hoc
assignments. If the test to validate the approver fails, the user assigning the invalid approver
receives an error and must correct it before the request can proceed.
The Issue Validate Approvers rule in the Get Agreement sample application is an example of
Validate Approver rules. To create a Validate Approver rule, see Defining Validate Approver rules.
The following figure illustrates how rules and ad hoc approver entries are used in the Next Approver
stage of an approval process.
Page 1726 of 4705
Home
Note
Process administrators should set up notifications to indicate when an erroneous ad hoc
selection is waiting for correction.
Approver Response stage

In this topic:
Signature Accumulator and Statistical Override rules
Signature Accumulator rules
Statistical Override rules
When a request enters the Approver Response stage of the approval process, the Approval Status
for the next approver's signature is "Pending." The approver can approve or reject the request,
request more information, or place a request on hold. When an approver responds in one of these
ways, the signature line for that approver is changed to Approved, Rejected, Hold, or More
Information.
The Approval Server sets the signature value automatically, depending on the approver's response.
You do not have to define a rule to implement this behavior. By default, the approver's response
determines whether the request passes into the Completion Check stage, or remains in the
Approver Response stage.
Approved When an approver approves a request, the request passes to the Completion
Check stage, where the approval server determines whether more signatures are required.
See Completion Check stage.
Page 1727 of 4705
Home
Rejected If an approver rejects a request, the request moves to the Process Done stage.
No more routing occurs, and the request is withdrawn from approvers who have placed the
request on hold or requested more information.
Hold When an approver places a request on hold, the approval server changes the
signature line to Hold, but no other action occurs. Process administrators should establish
escalations to prevent requests in Hold status from being neglected indefinitely.
More information If an approver requests more information, the approval server changes
the approval status to More Information, but no other action occurs within the approval
processing for that approver. The approval server allows an approver to hold, approve, or
reject a request without waiting for the More Information response. When this occurs, the
More Information request is terminated.
You can override the default behavior of the approval server in this stage. To do so, you use the
following rule types:
Signature Accumulator
Statistical Override
Signature Accumulator and Statistical Override rules

Signature Accumulator and Statistical Override rules can use ratios between approved and rejected
signatures to determine the outcome of a process. These rules preempt the usual routing to bring
the approval process to a conclusion based on statistics that you define. These two rule types are
also known collectively as "statistical decision-making rules."
An example of a statistical decision making rule is: "If more than 50% of the approvers approve the
request, then approve the process." With this rule in place, if the approval request has a list of five
approvers, and the first two approvers reject the request, the remaining approvers are still given a
chance to approve it. If the last three approvers approve the request, the request is approved
overall.
Signature Accumulator and Statistical Override rules run during the Approver Response stage (
whenever an approver responds to a request). If any Statistical Override rules are defined, then the
statistical decision-making approval process begins. If no Statistical Override rules exist, the
approval server follows its default logic, and the request moves to the Completion Check or
Process Done stage.

A Signature Accumulator rule collects statistical information about the signature records associated
with an approval process, for use in a Statistical Override rule. You define the criteria for counting
signatures.
In a Level process, only signatures associated with the current level are included in the set. These
are referred to as "current signature records." In all other process types, all signatures associated
with the detail record are included in the set.
Page 1728 of 4705
Home
For each signature record, the approval server applies each existing Signature Accumulator rule,
provided the Run If qualification passes. For example, if the approval server finds four signatures to
check, the server runs all the Signature Accumulator rules on the first signature, then on the second
signature, and so on until all the signatures are finished.
Examples of Signature Accumulator rules are included in the sample applications. They are Issue
Increment Signature Limit and Issue Retrieve Signature Limit, in the Get Agreement Sample
application. For information about using these examples, see Example of decision-making rules in
a sample application. To create a Signature Accumulator rule, see Defining Signature Accumulator
rules.

A Statistical Override rule preempts the default behavior of the approval process and causes the
process to be approved or rejected before all pending signatures have been completed. To do so,
the rules check whether the statistical conditions required for making a decision have been satisfied
.
Statistical Override rules can perform one of three actions: approve, reject, or do nothing. If a
Statistical Override rule approves or rejects a request, the request is done and moves to the
Process Done stage. If the conditions for approving or rejecting are not met, the process continues
the default behavior of checking for more signatures to gather.
When the Statistical Override rule approves or rejects a request, the normal approval process is
preempted by performing the following actions:
Process and signature considerations in the Statistical Override rule
Process
Signatures
type
considered
Approving requests
Rejecting requests
Level
Only signatures for

the current level
Preempts the approval server to proceed

to the next level.
Preempts the approval server to reject the

request and stop the processing.
Parent-Child
All signatures, at all

times

to proceed to next parent.

Ad Hoc

times
Preempts the approval server to approve

the request.

Rule-Based
times
to the next set of approvers.
Warning
Page 1729 of 4705
Home
If you define Statistical Override rules, you must also define a rule to approve or reject the
process if no pending signatures exist. If a rule is not defined to handle this condition, the
approval server considers this as an error condition.
The following figure illustrates how the approval server uses both types of statistical
decision-making rules in the Approver Response stage.
Statistical decision-making rules in Approver Response stage
Statistical Override rules evaluate the data gathered for the active signature record by a Signature
Accumulator rule or by the approval server. If the Statistical Override rules can be based solely on
the statistical data that the approval server gathers by default, you do not need to define a
Signature Accumulator rule.
The following statistical data is available by default:
Total Signatures
Total Approved
Total Rejected
Total Pending
Total Hold
Total More Information
Total Canceled
Total Closed
Total Error
Page 1730 of 4705
Home
Examples of Statistical Override rules are included in the sample applications. They are Issue
Statistical Approval and Issue Statistical Boundary Condition in the Get Agreement Sample
application.
For information about using these examples, see Example of decision-making rules in a sample
application.
To create Statistical Override rules, see Defining Statistical Override rules.
Completion Check stage

In this topic:
Example of Completion rules
Get Authority and Get Authority Regular rules
Completion rules
Examples of the routing completion check
The Completion Check stage of an approval process determines whether conditions exist to stop
routing a request to additional approvers. If a completion check is successful, routing stops and no
additional approvers will see the request.
Example of Completion rules

For example, when Jack approves a business expense for $100, a rule determines whether Jack
has sufficient authority to approve a request for that amount. If so, the process passes the
Completion Check stage. If not, the completion check fails and the routing of this request continues
to another approver.
Rule types used in the Completion Check stage include:
Get Authority
Get Authority Regular
Completion rule
Get Authority and Get Authority Regular rules

In the Completion Check stage, the approval server runs Get Authority or Get Authority Regular
rules to collect information. Get Authority rules are described in Get Authority rules and Get
Authority Self rules.
Like Get Authority rules, Get Authority Regular rules collect data that is used by the Completion rule
. The approval server runs Get Authority Regular rules only during the Completion Check stage of
an approval process.
Page 1731 of 4705
Home
Completion rules
Completion rules test whether sufficient authorization exists to stop routing an approval request. A
process is complete when the approval server has routed the request to all required approvers
even if they have not yet all responded.
No Completion If the Completion rule condition is not met, the Get Next Approver rules
are performed and the request is routed to the next approver. If no new approvers are found
by the Get Next Approver rules, the approval server checks the Approval Success field of
the Process Definition form.
If this field is set to No More Approvers, the process is done with a status of Approved
.
If the Approval Success field is set to Completion Rule, the process is done with an
error state, because no more approvers exist and no Completion rule has succeeded.
Successful Completion If the Completion rule condition is met, the request is not routed
to any further approvers. If outstanding signatures exist when the routing Completion rules
are fulfilled, the request remains active until either all approvers approve or one rejects the
request.
A process that requires a fixed number of signatures will complete successfully when the process
exhausts the Approver List. For example, you can create a process that completes routing when
any five approvers respond, instead of completing with one approver of a specific authority.
Examples of the routing completion check

The rules governing approval of a business lunch might be determined by the amount of the
request. If Frank requests approval of a $150 business lunch, and Jack has authority to approve
requests for $150 or less, the process passes the completion check when Jack approves the
request. If Jack does not have authority to approve requests of $150, the approval process does
not pass the completion check when Jack approves it, and the process returns to the Get Next
Approver stage. In this example, the Completion rule uses data gathered by a Get Authority rule to
test for completion against a specific dollar amount.
Alternatively, the same request might require signatures from two steps up the management
hierarchy. When Frank's manager and his manager's manager have approved the request, no
more approvers are required, and the process is complete. In this case, the Completion rule uses
data gathered by a Get Authority rule to test the approver relationships.
The Cost Completion and Level Completion rules in the Lunch Scheduler sample application are
further examples of Completion rules. For information about creating a Completion rule, see
Defining Completion rules. The following figure illustrates how the approval server uses the
Completion, Get Authority, and Get Authority Regular rule types during the Completion Check
stage.
Page 1732 of 4705
Home
Completion Check stage of an approval process

Process Done stage

A process is done when a request has generated a final result, such as Approved, Rejected, Error,
or Cancelled. Approval Process Done rules allow a process to take action on the original request
when the approval server is done handling the request. For example, when a process is done, you
use an Approval Process Done rule to change the approval status on the approval request form.
The only rule type used to implement the Process Done stage is the Approval Process Done rule.
The sample applications contain many examples of Approval Process Done rules, including, for
example, Cost Approved, Cost Rejected, Issue Approved, and Issue Rejected. To create an
Approval Process Done rule, see Defining Approval Process Done rules.
Chained processes
You can initiate a new approval process automatically when the first process is done.
For example, if a manager approves a new computer purchase, the IT department can start
another chained approval process that determines the exact model of computer to buy.
For a description of chained processes in the Lunch Scheduler application, see Chaining approval
processes.
Approver fields
This topic contains information about how the Approval Server manages the sizes of approver
fields and a utility that is used for this purpose.
Lengths of approver fields
Approval Change Schema utility
Lengths of approver fields

By default, approver names are limited to 255 characters and the list of members in an approval
server role is limited to 512 characters. The approval server checks the lengths of the fields listed in
the following table at startup, and enforces this length as the maximum limit.
Page 1733 of 4705
Home
Approver fields checked for maximum length at startup

Field ID
Field name
12401
Member List
Form name
AP:Role
13203
Original Approvers
AP:Signature
AP:PreviewSignatures
13205
Next Approvers
AP:Signature
13207
Approvers
AP:Signature
AP:PreviewInfo
14511
GNA Approvers
AP:Signature
14512
PGNA Approvers
AP:Signature
You can increase the length of these fields to the maximum limit permitted by the database (
VARCHAR limit) by manually executing a approval server utility. See Approval Change Schema.
Note
In release 7.5.00, the approval server only checks the size of the Approvers field at
startup, and enforces this length as the maximum limit for approver names. If the default
limits are insufficient, you need to increase the field lengths manually.
VARCHAR limits for special fields on supported databases

Database
VARCHAR limit
IBM DB2
4000
Microsoft
SQL Server
8000
Note: Even though the VARCHAR limit on SQL Server is 8000 characters, the Approval Change Schema utility
sets the field length to 4000 characters to support Unicode.
Oracle
4000
Sybase
255
Page 1734 of 4705
Home
To use longer approver names with previews, make the following changes:
For regular previews, increase the length of the Approvers and Original Approvers fields on
AP:PreviewSignatures.
For real-time previews, increase the length of the Approvers field on AP:PreviewInfo.
Approval Change Schema utility

Administrators can run the Approval Change Schema ( chgschema) utility to set the length of
approver fields on certain forms to the maximum limit allowed by the database. Approver fields
checked for maximum length at startup lists the forms and their approver fields that are affected. To
run the chgschema utility manually, see Running the approval utilities.
The syntax for chgschema is as follows:
chgschema
-x Server
-u User
[-p Password] [-t TCP Port]
[-r RPC Port] [-a Authentication String]
The following table describes the parameters that administrators need to supply when running the
chgschema utility:
Parameters for the chgschema utility

Parameter
Description
-x
(mandatory) Name or IP address of the BMC Remedy AR System server to log into (or localhost, if applicable).
-u
(mandatory) Specify the BMC Remedy AR System user name. This user must belong to an administrator group,
otherwise the utility can not be run successfully, and the following error is displayed at the command prompt and
written to approval-utils.log:
Admin verification failed: <userName>
-p
(optional) Specify the password for the aforementioned user. Omit this parameter if the user account does not have
a password.
-t
(optional) TCP port number of the server being logged into. This parameter is required if the BMC Remedy AR
System server is configured to listen on a particular TCP port.
-r
(optional) RPC port number of the server being logged into. This parameter is required if the BMC Remedy AR
System server is configured to listen on a particular RPC port.
-a
(optional) Specify the authentication string.
Note
Page 1735 of 4705
Home
The chgschema utility increases the lengths of the approver fields provided that
the current lengths are not already set to the maximum VARCHAR limit, or to
unrestricted or 0 (zero). In case of the Member List field, if the maximum length
supported by the database is less than 512 characters, the current field length is
not modified. This ensures that the corresponding data remains intact.
After running the utility, you must restart the approval server for the changes to
take effect.

The following topics provide information about creating and modifying processes in BMC Remedy
Approval Server:
Using the Process tab on AP-Administration
Creating a process
Working with existing processes
Defining roles
Using the Process tab on AP-Administration

To create and manage processes, use the Process tab on the AP:Administration form. When you
select the Process tab, a table field appears. To populate the table with all existing processes, click
Refresh. You can sort this list on any column, including the process name, the linked approval
request form, the process type, the process status (active or inactive), or the process ID. If you
installed the sample applications, all the sample application processes appear on this list.
The buttons on the Process tab take the following actions:
View Opens the AP:Process Definition form for the selected rule in Modify mode. You
must select a process from the list to use this button. Use this option to view and modify
existing processes.
Search Opens a blank AP:Process Definition form in Search mode. Use this option to
search for a process using a field that does not appear in the processes list.
Create Opens the AP:Process Definition form in New mode. Use this option to create a
new process.
Delete Deletes the selected process. You must select a process from the list to use this
button.
Refresh Refreshes the current list of processes. Use this button to refresh the list, for
example, after adding a new process.
Creating a process
Creating More Information escalations
Page 1736 of 4705
Home
Creating signature escalations

Defining process basics
Setting process intervals
To create a new process, click Create on the Process tab of the AP:Administration form. This
opens the AP:Process Definition form in New mode.
For more information, see AP-Process Definition form.
AP:Process Definition contains the following tabs:
Basic Use this tab to define basic information about the process, including the process
name and type, the associated form, and approval success criteria.
Configuration Use this tab to specify:
Process intervals to calculate the Action Date for a request
Menus to generate lists of users that appear when creating a More Information
request (by adding a question or comment), reassigning a request, and assigning a
request to an ad hoc approver
The mandate for rejection justification and the application form's field on which to
push an approver's input
Signature Escalations (Normal, Urgent, and Low)--Use these tabs to schedule
notifications and automatic actions for pending requests.
More Info Escalations Use this tab to schedule notifications for requests in the More
Information state.
Administrative Info The fields on this tab contain the change history and help text (if any
) for the process. Use the Help Text field to document the process.
In most cases, you need only one process for your approval request, but it is possible to create
multiple processes. For an example of an application that uses three separate approval processes,
see the Sample Lunch Scheduler form that is described in Sample process descriptions.
Note
Before you can create a process, the approval request form that you link your process to
must exist on the AR System server, and must appear in the list of forms on the Form tab
of AP:Administration. To link the approval request form for your application to the approval
server, see Adding the approval request form to the approval server .
Creating More Information escalations

Use the More Info Escalations tab to configure settings that control notifications when a More
Information request has been waiting too long without response. For example, you can set up a
notification to be sent when a More Information request has been outstanding for two days.
Page 1737 of 4705
Home
To enter More Information escalations

1. Open the Process Definition form if it is not already open. See Creating a process.
2. On the More Info Escalations tab, select or enter the names of the business calendar and
the holiday calendar you want to use for More Information Escalation notifications.
These names must match existing schedule names from the Business Time Workdays or
Business Time Holidays forms. For information about setting up business times, see the
Defining business schedules using Business Time .
3. If you want to send notifications when a signature line has been outstanding (in any state) for
too long, specify the Notifications: Still Outstanding parameters:
a. Enter a number in the First Interval field to indicate when you want the first
notification sent, and select the item that this number represents for the Unit list.
For example, if you want the first notification sent two days after the approval request
enters the More Information state, enter a 2 in the First Interval field and select Days
from the Unit list.
b. If you want a second notification, enter a number in the Repeat Interval field and
select the item that this number represents from the Unit list.
4. Click Save.
Creating signature escalations

Use the Signature Escalations tabs to configure settings for notifications and actions when a
signature line has been waiting too long without a response. For example, you can set up a
notification to be sent when a request has been outstanding for two days.
This procedure applies to all the priority levels that are associated with a request: Normal, Urgent,
or Low.
To enter signature escalations

1. Open the Process Definition form if it is not already open. See Creating a process.
2. On the Basic tab, select a process from the list and click View.
3. Open the tab for the appropriate priority level:
Signature Escalations (Normal)
Signature Escalations (Urgent)
Signature Escalations (Low)
Note
Enter the appropriate parameters for Normal, Urgent, or Low priority
signature escalations. The settings on these tabs are applicable only to
requests with the same priority. For example, if a low priority request is
being processed and no values are defined on the Signature Escalations (
Low) tab, no action is taken on the request.
Page 1738 of 4705
Home
4. Select or enter the names of the business calendar and the holiday calendar you want to use
for signature escalation notifications.
These names must match existing schedule names from the Business Time Workdays or
Business Time Holidays forms. For information about configuring business times, see
Defining business schedules using Business Time .
5. To change the state of an approval request automatically if no signature action occurs after a
specified interval, enter the Automatic Action parameters:
a. Enter a number in the After Interval field to indicate when you want the state
changed, and select the item that this number represents from the Unit list.
For example, if you want the state to change two days after the approval request
enters a certain state, enter 2 in the After Interval field, and select Days from the
Unit list.
b. In the Change State field, use the drop-down list to select the state that you want to
apply to the approval request.
The options are Pending, Approved, or Rejected.
If you set these parameters, approvers can see the resulting date and time after
which the state of the approval request changes automatically. This is shown on AP:
Show-Detail > Action Date field and Approval Central > Action Date column. For
more information, see AP-Show-Detail form and Approval Central.
6. To send notifications when a signature line has been outstanding (in any state) for too long,
specify the Notification: Still <OutstandingState> parameters. For example, If a signature
line has been outstanding in Pending state for too long then specify the Notification: Still
Pending parameters.
a. Enter a number in the First Interval field to indicate when you want the first
notification sent, and select the item that this number represents from the Unit list.
b. If you want a second notification sent, enter a number in the Repeat Interval field and
select the item that this number represents from the Unit list.
This is shown on the Approval Central > Past Due requests > Action Date column.
For more information, see Approval Central.
7. If you want to send notifications when the approval request remains in a certain state (
Pending, Error, Hold, or More Information) too long, specify the Notification: Still <in State
> parameters. For example, if a signature line has been outstanding in Hold state for too
long then specify the Notification: Still Hold parameters.
a. Enter a number in the First Interval field to choose the state that indicates when you
want the first notification sent, and select the item that this number represents from
the Unit list.
b. If you want a second notification sent, enter a number in the appropriate Repeat
Interval field and select the item that this number represents from the Unit list.
Defining process basics

Use the Basic tab on AP:Process Definition to define basic information such as the process name
and type, the associated form, and approval success criteria.
Page 1739 of 4705
Home
To create a process
1. Open the AP:Administration form.
See Working with the AP-Administration form.
2. On the Process tab, click Create to open the AP:Process Definition form in New mode.
3. On the Basic tab, specify appropriate values in the various fields.
See AP-Process Definition form.
4. Click Save.
The following figure depicts the basic process definition for the sample Management Cost
Authorization process.
Process Definition form Basic tab
Setting process intervals

Use the Configuration tab of the Process Definition form to configure process intervals.
To set process intervals

1. Open the AP:Administration form, select a process, and click View.
For more information, see Creating a process and AP-Process Definition form.
The selected process opens in Modify mode.
2. On the Configuration tab, enter a number in the Process Due field, and select the item that
this number represents from the Unit list.
For example, if you want the process to be due five days after the first signature is created,
enter 5 in the Interval field, and select Days from the Unit list.
Note
Page 1740 of 4705
Home
The Process Due interval is required for the action date feature. If this field is left
blank, no action date is associated with the process or its corresponding requests.
3. Enter a number in the Signature Due field, and select the item that this number represents
from the Unit list.
For example, if you want every signature to be due in two days, enter 2 in the Interval field,
and select Days from the Unit list.
4. Enter a number in the Buffer Period field, and select the item that this number represents
from the Unit list.
This value is used as a delta to be deducted from all other intervals, except Signature Due,
to derive the minimum of all the required process intervals.
5. In the Enable Preview field, select Yes if you want to consider future approvers when
calculating the Signature Due date. Select No if you want if you want to use the value in the
Signature Due field only.
6. Click Save.
Besides these process intervals, you also need to specify certain values in the Signature
Escalation tabs and on the AP:Notification and AP:Admin-ServerSettings forms.
Working with existing processes

The following sections describe how to modify, delete, or rename an existing process.
To view and modify a process
To delete a process
To rename an approval process or form
To view and modify a process

1. Open the AP:Administration form. See Working with the AP-Administration form.
2. On the Process tab, click Refresh.
3. Select the process from the list and click View.
The Process Definition form opens in Modify mode, displaying the entry for the selected
process.
4. Modify the appropriate process fields as needed. See Creating a process for information
about field values.
5. Click Save.
To delete a process
Note
The delete operation is permanent and cannot be undone. When you delete a process, all
of its associated rules are deactivated.
Page 1741 of 4705
Home

2. On the Process tab, click Refresh to populate the list of processes.
3. Select the process you want to delete.
4. Click Delete.
5. Click Yes when prompted to confirm the deletion.
The process is deleted and no longer appears in the list of processes.
To rename an approval process or form
Note
If you want to rename an approval process or an approval form, you can apply the new
process or form name to all existing requests in the process, or only to active requests.
If you want to rename a process or approval form, you must also edit any related workflow
, such as the filter that starts the process, to correct the process name.

See Working with the AP-Administration form.
2. Click Rename in the navigation pane.
The Approval Server Rename dialog box (AP:Admin-Rename form) appears as shown in the
following figure.
Renaming a process
3. Select Process to rename a process, or select Form to rename a form.

4. In the Select GUID of the process to be rename d field, click the drop-down menu.
Page 1742 of 4705
Home
4.
If you are renaming an approval process, a list of the existing processes appears by
name. Select the process name. BMC Remedy AR System supplies the process
GUID. Click the GUID to select the process.
If you are renaming a form, a list of all forms on the AR System server appears.
Select the approval form to be renamed.
5. In the Enter new process name or the Enter new form name field, type the new process
or form name.
6. In the Scope of Update field, select whether you want the new name to apply to all requests
, or only to active requests.
All Requests This option updates both currently active and completed detail and
signature records. This option takes more time but will make sure that all detail
records reference the new name.
Only Active Requests This option updates only the currently active detail and
signature records.
Note
If you leave the Scope of Update field blank, approval server considers All
Requests to be the default value.
7. To change the name of the process or object as well as the related requests, the Including
Object Itself check box must be selected.
If you have already manually changed the process or form name, clear this check box. In
this case, BMC Remedy AR System renames only the related requests, you must enter the
current process or form name in the field labeled "Enter new process name" or "Enter new
form name."
8. Click Rename to complete the action.
Defining roles
The approval server can route a request to a role instead of to an individual. When you route to a
role, the request is routed to all members of the role. You specify whether one member of the role
can approve a request or whether all members must approve it.
The Overdue Oversight role is an example of the use of roles in the Lunch Scheduler sample
application. This rule works with the Rule-Based process to route approvals for an overdue account
to the members of the Overdue Oversight role.
To define a role
1. Open the AP:Administration form. See Working with the AP-Administration form.
2.
Page 1743 of 4705
Home
2. On the Role tab, click Create.

Defining an approver role
3. In the AP:Role form, enter a Role Name in the Role Name field.
The name should be descriptive of a job or a responsibility, for example, MIS Management.
4. Select an option from the If Multiple Approvers list.
This determines how many signature line records the approval server creates for the role
when building an Approver List.
The options are:
One Must Sign This option creates a single signature line record for the role. The
signature line is complete when one of the members of the role acts upon the
approval request.
All Must Sign (default) This option creates a separate signature line for each
member of the role.
This option is overridden when the If Multiple Approver setting for the process is
defined as One Must Sign. When this is the case, the role follows the One Must Sign
process setting. See Creating a process.
Note
If you include a role in the member list of another role, the If Multiple
Approvers option of the parent role will take precedence. For example,
suppose that Role A is defined with If Multiple Approvers set to All must sign
and you include Role A in the member list of Role B. Role B is defined with If
Multiple Approvers set to One must sign. In this example, the approval
server uses the settings for Role B.
5. In the Status field, select Active (default) or Inactive.
6.
Page 1744 of 4705
Home
6. In the Member List field, type the names of the role members.
You must enter valid user names or role names, and separate the entries with semicolons or
hard returns.
To open an expanded text box, click the Text Box button. This field has a maximum length
of 255 characters.
7. Click Save.

The following topics provide information about how to create and modify rules in BMC Remedy
Approval Server:
Using the Rule tab on AP-Administration
Creating a rule
Approval rule definitions and examples
Working with existing rules
Using the Rule tab on AP-Administration

To create and manage rules, use the Rule tab on the AP:Administration form. See Working with the
AP-Administration form.
When you open the Rule tab, a table field appears listing all existing rules. You can sort this list on
any column, including rule name, process name, rule type, order, status, and process instance ID.
If you installed the sample applications, all the sample application rules appear on this list.
Below the list of rules, a diagram illustrates the stages of an approval process and contains links
that filter the list for each rule type. For example, to see a list of all existing Get Next Approver rules
, click the Next Approver link on the diagram.
To see only the rules for a specific process, select the process from the menu in the Show for
Process field.
The buttons on the Rule tab take the following actions:
View Opens the AP:Rule Definition form for the selected rule in Modify mode. You must
select a rule from the list to use this option to view and modify existing rules.
Search Opens a blank AP:Rule Definition form in Search mode. Use this option if you
want to search for a rule using a field that does not appear in the rules list.
Create Opens the AP:Rule Definition form in New mode. Use this option to create a new
rule.
Delete Deletes the selected rule. You must select a rule from the list to use this option.
Refresh Refreshes the current list of rules. Use this option to refresh the list, for example,
after adding a new rule.
Show all Refreshes the list of rules with all existing rules. Use this option to refresh the
list after narrowing it to show only one type of rule.
Page 1745 of 4705
Home
Creating a rule
Using the Basic tab on the Rule Definition form
Using the Set Fields tab on the Rule Definition form
To create a new rule, click Create on the Rule tab of the AP:Administration form. This opens the AP
:Rule Definition form in New mode.
Note
To create a rule, you must first create the process that the rule will support. See Defining
an approval process.
AP:Rule Definition consists of three tabbed views (depending on the type of rule):
Basic The fields on this tab store identification and execution information about the rule,
as well as a Run If qualification statement, if any.
Set Fields For rules that include a Set Fields action, the fields on this tab specify the
action to be executed by the rule when a transaction passes the qualification statement.
Administrative Information The fields on this tab contain change history and help text (if
any) for the rule. Use the help text field to describe the purpose of the rule, or any other
information helpful to process administrators.
Defining a new rule
Using the Basic tab on the Rule Definition form

Use the Basic tab on the Rule Definition form to enter descriptive information about the rule, such
as the rule name, the associated process name, and the rule type. Depending on the rule type, you
might use the Run If or Rule field in the Qualification area to enter a condition statement. This
Page 1746 of 4705
Home
section describes the steps that are common to creating all rule types by using the Basic tab. For
information about the If Multiple Results, If Multiple Approvers, and Next Approver Rule Is fields,
see Defining Get Next Approver rules and Defining Parameterized Get Next Approver rules .
To complete the fields on the Basic tab that are common to all rules
1. Open the AP:Administration form, and click the Rule tab.
2. In the Rule Name field, enter a name for the rule.
Rule names must be unique and can be as long as 30 characters. For ease of administration
, use a rule name that reflects the application or process, the rule type, the rule function, or
some combination.
3. In the For Process field, select the process name that this rule will support from the list.
The processes that appear on this menu are those you have defined in the Process tab.
When you select the process name, BMC Remedy AR System automatically populates the
Process Instance ID field.
4. In the Rule Type field, select the appropriate rule type from the list. For example, if you are
creating a Get Next Approver rule, select Get Next Approver.
When you select a rule type, the Rule Definition form changes to display the fields
appropriate for the rule type. Fields that apply to the rule type have a white field box. Fields
that do not apply are gray.
5. In the Order field, enter an execution order number. The default value is "0."
This number determines the rule sequence when two or more of the same rule type exist for
a specific process.
6. In the Status field, select either Active or Inactive. The default value is Active.
Inactive rules do not run when the process runs. While you are developing a set of rules for
a process, it might be helpful to use the Inactive status. When you are ready to test your
rules, change the Status field to Active.
Note
If you save a rule with the Status field empty, the rule is saved as Active.
7. In the Assignee Group Permissions field, the Public group appears by default. If you use
this field for multi-tenancy support, create workflow to populate this field with the correct
assignee group name. You do not need to change this setting when creating the rule.
The approval server supports multi-tenancy for use by application service providers. The
Assignee Group Permissions field is field 112, and appears on all the approval server
forms. The field 112 value from records created in the AP:Details form is used automatically
in all the other approval server forms, for example, AP:Signature, AP:More Information, and
so on.
8.
Page 1747 of 4705
Home
8. If the rule requires a qualifying condition to control execution, enter the condition in the
Qualification area of the Basic tab. This field is labeled "Rule" or "Run If," depending on the
rule type. Process Done rules use a radio button field to set the execution condition.
You can type the condition statement or you can build it by using the qualification bar and list
. When the qualification is met, the rule actions execute. You can use currency, date, and
time fields in Run If and Rule qualification statements.
For more information, see the Security administration. For specific examples pertaining to
various rule types, see the discussion of each rule type in this section.
9. Click Save.
Using the Set Fields tab on the Rule Definition form

The Set Fields tab applies to all rule types except Auto Approval, Self Approval, and Completion
rules. You use the Set Fields tab to define the actions for the rule. For example, for a Get Authority
rule, you can define a query to retrieve a signature authority amount from the AP-Sample:Signature
Authority form and set that amount into a temporary field on the AP:Signature form.
When you construct assignments using the Set Fields tab, you can also use currency, date, and
time fields, currency functions such as CURRCONVERT, CURRSETDATE, CURRSETTYPE, or
CURRESETVAL, and date functions such as DATEDIFF, DATENAME, DATENUM, or DATEADD.
Depending on the rule type, the Set Fields tab provides the following action options in the Set
Fields Type field:
Value Use this action to assign a value to a particular field.
Query Use this action to specify a form (from the current server or another server) and a
qualification for a query to that form. You can assign the value of any field from the queried
form. If no match is found for the qualification, a NULL value is assigned. If multiple matches
are found, the value assigned depends on the If Multiple Rows setting on the Basic tab.
SQL Use this action to specify an SQL command to be run on either the AR System
server or another database. You can assign the value from any returned column. If the
command finds no entries, a NULL value is assigned. If it finds multiple entries, the value
assigned depends on the If Multiple Rows setting on the Basic tab.
Process Use this action to specify a process to be run on the AR System server. If the
command returns an empty string or an error, a NULL value is assigned.
Other This setting enables you to specify an action by using an AR System filter. See
Filters.
When you select the type of action, the buttons and fields in the qualification area change
according to the action type.
Page 1748 of 4705
Home
Example of the Set Fields tab for a Value

The following figure illustrates a rule that uses Value as the Set Fields Type.
In this example, the rule uses the Value Set Fields Type to assign a value to a particular field. This
value can be a hard-coded value, a keyword, or a value from a field of a schema.
Set Fields tab for a value
Example of the Set Fields tab for a Query

The following figure illustrates a Get Authority rule from the sample applications that makes a query
to the AP-Sample:Signature Authority form.
In this example, the rule uses a query to the AP-Sample:Signature Authority form to retrieve the
signature dollar limit for the current approver.
Set Fields tab for the Get Authority rule with a query
Page 1749 of 4705
Home
Example of the Set Fields tab for an SQL command

The following figure illustrates a Get Authority rule from the sample applications that specifies an
SQL command to be executed on the AP-Sample:Signature Authority form. This form has a T274
table in the AR database.
Note
To successfully run an SQL query, you must provide the T-Table name.
In this example, the rule specifies an SQL command that will retrieve the signature dollar limit for
the current approver from the AP-Sample: Signature Authority form.
Set Fields tab for the Get Authority rule with an SQL command
Page 1750 of 4705
Home
In this SQL command (SELECT C536870914 FROM T274 WHERE C8 = '$Approver$'):

C536870914 is the column ID of Signature Dollar Limit
T274 is the T-table of AP-Sample: Signature Authority
C8 is the column ID of Field Login Name
The resulting entries will have $Signature Dollar Limit$ as the first column. $1$ represents the
value of $Signature Dollar Limit$.
Note
$1$ represents the value of the first column of the resultant row.
Example of the Set Fields tab for a Process

The following figure illustrates a rule that uses process as the Set Fields Type.
In this example, the rule specifies a process that will run on the AR System server. You can specify
any executable process, such as a batch file (only for Windows), a shell or Perl script, or any other
application.
Note
The process must not contain any pauses, sleep delays, or white spaces. The output of
the process must be in the form of strings.
Page 1751 of 4705
Home
The output must be separated by the string defined in the Separator String field. After being
separated by the separator, each resultant string will be represented by $1$, $2$, and so on.
Note
You must ensure that the separator string in the Set Fields tabs and the separator string in
the application are the same.
Set Fields tab for a process
Approval rule definitions and examples

This section contains information about defining the various types of approval rules and an provides
an example of each.
Defining Auto Approval rules
Defining all Get Authority rules
Defining Self Approval rules
Defining Prep Get Next Approver rules
Defining Get Next Approver rules
Process type and Get Next Approver rules
Creating a Get Next Approver rule
Defining Parameterized Get Next Approver rules
Defining Validate Approver rules
Defining Signature Accumulator rules
Defining Statistical Override rules
Defining Completion rules
Page 1752 of 4705
Home
Defining Approval Process Done rules
Defining Auto Approval rules

An Auto Approval rule determines if the request can be automatically approved at the time it is
submitted, without action from any approver, and regardless of the submitter's signature authority.
Automatic approval occurs when an approval request transaction passes any Auto Approval rule
included in the process.
Creating Auto Approval rules is optional. If you do not define an Auto Approval rule, no automatic
approval occurs.
Note
Auto Approval rules cannot use values retrieved from forms other than the current request
. To retrieve values from another form, use a Self Approval rule. See Defining Self
Approval rules.
If an Auto Approval rule's condition is met, the request moves directly to the Process Done stage.
When an approval request meets the criteria in an Auto Approval rule, the approval server sets the
rule state to Approved in the Detail record. This action activates an Approval Process Done rule.
This topic explains how to define an Auto Approval rule with a example.
To define an Auto Approval rule
Example of an Auto Approval rule
To define an Auto Approval rule

1. Follow the procedure in Using the Basic tab on the Rule Definition form to complete the basic
information about the rule.
Select Auto Approval in the Rule Type field.
Write a rule condition to test for a specific field value from the approval request form,
for example, checking whether the value for an Estimated Total field is less than
$15.00.
2. (optional) Enter an Audit Text message.
This message is written to the audit log when the condition for this rule passes. The audit
text can include embedded field references that are filled when the rule condition passes. If
you do not enter an audit message, a default message is written to the audit log.
Page 1753 of 4705
Home

The following figure illustrates an Auto Approval rule. In this example from the Lunch Scheduler
sample application, the value in the Estimated Total field of the approval request form is tested to
see if it is less than $15. If this rule passes, the customized audit trail message in the Audit Text
box is written to the audit log.
Defining all Get Authority rules

The approval server provides the following types of get authority rules:
Get Authority Runs in both the Self Check and Completion Check stages of the approval
process
Get Authority Self Runs only in the Self Check stage of the approval process
Get Authority Regular Runs only in the Completion Check stage of the approval process
.
You use the same procedure to define these types of get authority rules.
All get authority rules gather information about the current approver or environment that is used by
subsequent Self Approval or Completion rules.
This topic provides you the procedure to define an authority rule:
To define any type of get authority rule
Example of a Get Authority rule
Page 1754 of 4705
Home
To define any type of get authority rule

In the Rule Type field, select Get Authority, Get Authority Self, or Get Authority
Regular.
Create a condition statement in the Run If field if necessary. The condition statement
controls whether the rule actions execute. This field is optional for this rule type; if no
qualification exists, the rule always runs.
2. Click the Set Fields tab.
3. In the Set Field Type field, select an action from the menu.
The Set Field Type indicates the type of assignment to be used for the rule action. See
Using the Set Fields tab on the Rule Definition form .
4. In the From Form field, select a form name from the menu.
This value defines the form that the rule will search for the requested data; for example, the
AP-Sample:Signature Authority form.
5. In the On Server field, select the server where the form is located.
Current The form exists on the current server.
Alternate The form exists on another server. In this case, type the remote server
name in the Server field.
6. In the Qualification area, enter a qualification statement to define the parameters for
retrieving the authority data.
For example, to retrieve the current approver's signature authority limit from the AP-Sample:
Signature Authority form, define a qualification statement that sets $Approver$ (current
approver) to equal the Login Name field in the Signature Authority form.
Click Fields from the Set Fields Form to select the Login Name field from the form
named in the From Form field.
Click Fields from Application Form to select the $Approver$ field from the current
record of the AP:Signature form.
7. In the Fields Data area, enter the names of the field or fields to receive the data in the Field
Name column, and a value statement or the name of each source form field in the Value
column.
Use the field list button to the right of each field to select the field names. The fields in the
Field Name column are located in the AP:Signature form. The fields in the Value column are
located in the form named in the From Form field (such as AP-Sample:Signature Authority).
8. Click Save.

The following figure illustrates an example of a Get Authority rule from the Lunch Scheduler sample
application. This rule retrieves data about the person currently acting on the request (Login Name =
$Approver$) from the AP-Sample:Signature Authority form.
Page 1755 of 4705
Home
The value in this approver's Signature Dollar Limit field on the AP-Sample:Signature Authority form
is written to a temporary field named Temp Decimal 1 in the Details form. The value in the
temporary field is then available for use by any Self Approval or Completion rule.
Defining Self Approval rules

A Self Approval rule determines whether an approval request can be approved based on an
attribute of the requester, such as signature authority. Self approval is immediate and simply tests
whether the approval request meets the defined criteria.
A Self Approval rule differs from an Auto Approval rule in that Self Approval rules can use values
retrieved from another form. Self Approval rules usually depend on a Get Authority Self or Get
Authority rule to retrieve a value from another form. For example, a Get Authority Self rule can
retrieve the signature authority value for the requester and write the value to a temporary field on
the AP:Signature form. This makes the signature authority value available for use by a Self
Approval rule.
When an approval request meets the criteria in a Self Approval rule, the request moves directly to
the Process Done stage. The approval server sets the rule state to Approved in the Detail record,
which activates an Approval Process Done rule.
To define a Self Approval rule

1. Follow the procedure in Using the Basic tab on the Rule Definition form to complete the
basic information about the rule.
In the Rule Type field, select Self Approval from the list.
Page 1756 of 4705
Home
Build a condition statement that tests for a specific field value to determine if the rule
passes. The condition can reference any value of the current approval request or any
values retrieved by a Get Authority or Get Authority Self rule.
For example, test to see if a signature authority field value is $100.00 and the total
approval request amount is less than or equal to $100.00.
2. (optional) Enter an Audit Text message.
This message is written to the audit log when the condition for this rule passes. The audit
text can include embedded field references that are filled when the rule condition passes. If
you leave the Audit Text field blank, a default message is written to the audit log.
3. Click Save.
Example of a Self Approval rule

The following figure shows an example of a Self Approval rule from the Lunch Scheduler sample
application. In this example, the rule condition is a statement comparing the value in the Estimated
Total field of the approval request with the value in a temporary field (Temp Decimal 1) on the AP:
Signature form, and the value 200.
For this Self Approval rule to work, a Get Authority Self or a Get Authority rule must also be
included in the process to retrieve the value for the temporary field. In this example, the temporary
field value is a signature authority value pulled from the AP-Sample:Signature Authority form by a
Get Authority rule. The Estimated Total field is located on the approval request form (AP-Sample:
Lunch Scheduler).
In addition to the rule condition, this sample rule includes a customized audit trail message to be
written to the audit log when the rule passes.
Example of a Self Approval rule
Page 1757 of 4705
Home
Defining Prep Get Next Approver rules

The Prep Get Next Approver rule type gathers information to be used by Get Next Approver rules. (
In the rule name, "prep" is an abbreviation for "prepare.") These rules use a Set Fields action to
place values in certain fields.
To define a Prep Get Next Approver rule

Select Prep Get Next Approver from the Rule Type list.
The rule condition in the Run If text box is optional. Use this field to define a
conditional statement that controls whether the rule executes. If you do not define a
condition, the rule always passes.
2. Open the Set Fields tab and perform the following steps:
a. In the Set Fields Type field, select the action type from the menu. See Using the Set
Fields tab on the Rule Definition form .
b. If the action type is Query, select a form name from the From Form list. This value
indicates which form to search for the data being retrieved by the query.
c. In the On Server field, select Current if the form exists on the current server, or select
Alternate if the form exists on another server, and enter the server name where the
form is located in the Server field.
d. Depending on the action type, enter the qualification statement or command line in
the Qualification area.
e. In the Fields Data area, enter the name of the field or fields to receive the data in the
Field Name column, and a value statement or the name of each source form field in
the Value column.
f. Click Save.
Page 1758 of 4705
Home
Example of a Prep Get Next Approver rule

The Overdue Prep Get Next rule in the Lunch Scheduler sample application, illustrated in the
following figure, is an example of a Prep Get Next Approver rule. It gathers information that will be
used by the Rule-Based process Special Overdue Approval. The Basic tab in this example does
not contain a Run If statement. This means that the rule always runs. On the Set Fields tab, a
Value action increments the level field with the value $Level$+1.
Example of a Prep Get Next Approver rule
Defining Get Next Approver rules

Get Next Approver rules obtain a list of approvers for an approval request. The number of
signature-line records created for the approver list depends on the definition of the Get Next
Approver rule:
When If Multiple Approvers is set to One Must Sign, the approval server creates a single
signature record for the entire approver list. To complete the signature record, only one of
the approvers in the list must act on the approval request.
When If Multiple Approvers is set to All Must Sign, the approval server creates a separate
signature record for each approver in the approver list. If a role is in the approver list, the
approval server creates a separate signature record for each member of the role. In this
case, each approver must act on the approval request to complete his or her signature line.
A signature record is considered complete when any approver on the signature record approves,
rejects, or cancels the approval request.
Page 1759 of 4705
Home
Process type and Get Next Approver rules

The Parent-Child, Level, and Rule-Based process types use Get Next Approver rules, and each
process has different requirements. This topic includes this information:
Get Next Approver rules in a Parent-Child process
Get Next Approver rules in a Level process
Get Next Approver rules in a Rule-Based process
Ad Hoc processes
Get Next Approver rules in a Parent-Child process

In a Parent-Child process, you must create a form to define individuals or roles, and the form must
include a field that identifies the parent record. When an approver marks a request Approved, the
approval server automatically routes the approval request to the parent of the approver (usually the
approver's manager). See Parent-Child process for more information about this process type.
For a Get Next Approver rule in a Parent-Child process, the following considerations apply:
The approval server assumes that the current approver is the key component of the
qualification.
To build the first approver list when the request is submitted, the approval server considers
the originator of the approval request to be the previous approver.
Get Next Approver rules in a Level process

In a Level process, you must define individuals and roles in a field that identifies the organizational
level of the individual or role. For example, level 1 might be project leaders and level 2 might be
section managers. Levels are always numeric values, with 0 (zero) being the lowest level. See
Level process for more information about this process type.
When the approval server creates the first approver list when the request is submitted, it assumes
that the previous level was -1. Therefore, the first level is the level with the lowest number. The
approval server keeps track of the current approver level during the approval cycle.
For a Get Next Approver rule in a Level process, the following considerations apply:
You must identify the field containing the level identifier.
If you define a qualification that includes a clause to retrieve only entries with a level greater
than the current level, you save processing time by allowing the approval server to skip over
individuals or roles in the previous levels. This type of clause is not required, as previous
level entries are simply ignored if they are retrieved.
Get Next Approver rules in a Rule-Based process

In a Rule-Based process, rules define the relationships between individuals or roles and the
approval process. The approval server makes no assumptions regarding these relationships. You
must design the appropriate rules to determine how to construct the first approver list and how to
Page 1760 of 4705
Home
move from one phase of the approval process to the next.

Use the Next Approver Rule Is field on the Rule Definition form to define a set of rules that evaluate
the conditions necessary to add an approver to the current approver list. See Rule-Based process.
Ad Hoc processes
Ad Hoc processes do not use the Get Next Approver rule type, because an Ad Hoc process
expects that users will add the next approver. See Ad Hoc process.
Creating a Get Next Approver rule

To create a Get Next Approver rule, use the following procedure.
To define a Get Next Approver rule
Example of a Get Next Approver rule
To define a Get Next Approver rule

Select Get Next Approver from the Rule Type list.
The rule condition in the Run If text box is optional. Use this field to define a
conditional statement that controls whether the rule executes.
2. In the If Multiple Results field, select a value from the menu.
This field determines what occurs when more than one row of data is returned by the Get
Next Approver rule. The following choices are available:
Value from First Uses the value from the first record retrieved.
Values from All Uses all of the values retrieved.
Return Error Returns an error message if more than one record is retrieved.
Clear Leaves this field blank.
3. In the If Multiple Approvers field, select a value from the menu.
This field value determines the signature requirements when more than one approver is
returned by the Get Next Approver rule.
One Must Sign A single signature record is created and only one of the approvers
listed in the record is required to act upon the approval request to consider the record
complete.
All Must Sign A separate signature record is created for each individual in the
approver list, including individuals within a role. In this case, all of the approvers
retrieved by the Get Next Approver rule must act upon the approval request.
4. In the Next Approver Rule Is field, select a value from the menu.
This field value determines how the approver list is constructed when multiple Get Next
Approver rules exist in the process. It is often used in a Rule-Based process that uses set of
Get Next Approver rules to build an approver list.
Page 1761 of 4705
Home
Additive Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, and further rules are to be processed.
Ending Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, but no further rules are to be processed.
Exclusive Indicates that this rule assigns the entire approver list, and no further
rules are processed. In addition, if a previous rule created an approver list, that list is
ignored.
5. (optional ) Enter the rule condition in the Run If text box.
If used, this field defines a conditional statement that controls whether the rule runs. You can
type the conditional statement or you can build it by using the qualification bar and list. See
Building qualifications and expressions.
7. In the Set Fields Type field, select the appropriate action type. See Using the Set Fields tab
on the Rule Definition form.
8. For a query, select a form name from the From Form menu.
This value indicates in which form to search for the query.
10. Depending on the action type, enter the qualification statement or command line in the
Qualification area.
11. In the Fields Data area, enter the name of the field or fields to receive the data in the Field
column.
12. Click Save.
Example of a Get Next Approver rule

The following figure illustrates an example of a Get Next Approver rule for the Parent-Child process
in the Lunch Scheduler sample application.
The Basic tab in this example does not contain a Run If statement, so the rule always runs. The If
Multiple Approvers setting causes the approval server to create a single signature record for the
approver list (One Must Sign). Therefore, only one approver action is required for the approval
request to be complete. The Next Approver Rule Is field is set to Ending, so no other Get Next
Approver rules will be processed after this one.
On the Set Fields tab, the Qualification statement causes the approval server to match the current
approver ($Approver$) to the Login Name field in the AP-Sample:Signature Authority form during
the query. The current approver could be the approval request submitter or an approver.
The rule retrieves the "parent" of the current approver by getting the value from the $Manager
Page 1762 of 4705
Home
Login Name$ field on the matching record in the AP-Sample:Signature Authority form and setting
the value in the Next Approver field of the approval request.
Example of a Get Next Approver rule in a Parent-Child process
Defining Parameterized Get Next Approver rules

The Parameterized Get Next Approver rule enables requesters and approvers working with a
Parent-Child, Level, or Rule-Based process to add an approver anywhere in the approval hierarchy
at run time. This rule type works with the preview feature to make this functionality available. See
Adding previews to your approval application .
For example, an approver using the preview feature in a Parent-Child process might see the
following hierarchy of approvers:
1. Allan
2. Lin
3. Akon
4. Penni A Parameterized Get Next Approver rule would allow approver Lin to enter an
additional approver, Michel, at the same level as Penni, for example.
You use the Parameterized Get Next Approver rule in combination with the
Add-PGNA-Values application command. The Add-PGNA-Values command populates the
detail record with the run-time variables to be used by the rule. See BMC Remedy Approval
Server application commands.
A Parameterized Get Next Approver rule works exactly like a Get Next Approver rule, with
the following exceptions:
You can use run-time variables in the qualification and Set Fields operations.
Approvers can be added to any level, not only the next level.
Page 1763 of 4705
Home
After the Get Next Approver rules are run, the server runs all Parameterized Get Next
Approver rules. If Parameterized Get Next Approver rules exist, but the current record does
not supply any parameters, the approval server the approval server skips the parameterized
rules.
Use this topic to define a Parameterized Get Next Approver rule and to see an example.
To define a Parameterized Get Next Approver rule
Example of Parameterized Get Next Approver rule
To define a Parameterized Get Next Approver rule

Select Parameterized Get Next Approver from the Rule Type list.
The Run If condition is optional. Use this field to define a conditional statement to
control whether the rule runs.
2. In the If Multiple Results field, select a value from the menu.
This field determines what occurs when more than one row of data is returned by the Get
Next Approver rule. The following choices are available:
Value from First Uses the value from the first record retrieved.
Values from All Uses all of the values retrieved.
Return Error Returns an error message if more than one record is retrieved.
3. In the If Multiple Approvers field, select a value from the menu.
This field value determines the signature requirements when more than one approver is
returned by the Get Next Approver rule.
One Must Sign A single signature record is created and only one of the approvers
listed in the record is required to act upon the approval request to consider the record
complete.
All Must Sign A separate signature record is created for each individual in the
approver list, including individuals within a role. In this case, all of the approvers
retrieved by the Get Next Approver rule must act upon the approval request.
4. In the Next Approver Rule Is field, select a value from the menu.
This field value determines how the approver list is constructed when multiple Get Next
Approver rules are included in the process.
Additive Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, and further rules are to be processed.
Ending Indicates that any name or role this rule assigns to the approver list is
added to the existing approver list, but no further rules are to be processed.
Exclusive Indicates that this rule assigns the entire approver list, and no further
rules are processed. In addition, if a previous rule created an approver list, that list is
ignored.
Page 1764 of 4705
Home

5. Select Yes or No from the Guaranteed Add list.
Yes The parameterized rule runs even when a Completion rule would otherwise
determine that the process is done, thus guaranteeing that the user will be added as
an approver.
No If a Completion rule determines that the conditions exist for the process to be
done, the process does not return to the Get Next Approver stage to run this rule.
8. For a query, select a form name from the From Form menu. This value indicates in which
form to search for the query.
Alternate The form exists on another server. In this case, type the server name
where the form is located in the Server field.
Qualification area.
column.
12. Click Save.
Example of Parameterized Get Next Approver rule

The following figure illustrates an how an example Parameterized Get Next Approver rule operates.
The example rule includes the following settings:
Run If qualification: $Level$ = "%1"
Guaranteed Add: Yes
Set Fields: $Next Approver$ = "%2"
Example of a Parameterized Get Next Approver rule
Page 1765 of 4705
Home
The following actions occur:

1. A user enters an approval request in a process that includes an approval hierarchy, such as
a Parent-Child or Level process.
2. When working with the approval request, the first approver uses the preview feature to view
the existing approvers for the request, for example, by clicking a button on the approval form
. The approver decides to add Michel LeTourneau as an approver at a future level, for
example, level 4.
3. The approver uses functionality added to the approval request form, such as a button that
opens an "Add Approvers" form, to enter the level and the approver name. When the
approver saves his or her changes, a filter runs that captures these values and sends an
Add-PGNA-Values application command using the values to the approval server.
For example:
*Application-Command Approval Add-PGNA-Values -o "My Param Rule" -l "4/Michel

LeTourneau"*
4. The approval server receives the command, and stores the data in the Param Data field on
the AP:Detail record.
5. After the approval server runs the Get Next Approver rules, it runs Parameterized Get Next
Approver rules. While running the parameterized rules, it retrieves the values from the
Param Data field in the detail record. In this case, it retrieves 4/Michel LeTourneau and
parses this into %1="4" and %2="Michel LeTourneau"
6. The approval server replaces the variables in the Parameterized rule with these values:
Run If qualification $Level$ = 4
Set Fields $Next Approver$ = "Michel LeTourneau"
7. If the condition matches, the Set Fields action is executed. If the condition never matches
and the regular Get Next Approver rules do not return any approvers, the approval server
checks for the Guaranteed Add flag. If this is set to yes, the parameterized rule executes,
even though the Run If condition is not satisfied.
Parameterized Get Next Approver rules are executed when a preview is generated, so the added
approver is visible when future approvers preview the request.
Defining Validate Approver rules

A Validate Approver rule enables you to verify approver names when they are manually entered on
an approval request. This applies to either an Ad Hoc process type or an ad hoc override.
This rule validates the approver name at the time of entry by searching for a match to the entered
name on a specified form, for example, a signature authority form such as AP-Sample:Signature
Authority in the sample application.
Page 1766 of 4705
Home
You can define any number of Validate Approver rules. This allows you to search more than one
form to validate an approver name. This topic includes the following information:
To define a Validate Approver rule
Example of a Validate Approver rule
Warning
Approver names in Validate Approver rules are case sensitive. Make sure approver
names are entered correctly by providing a menu of names for requesters to select from.
See Working with menus.
To define a Validate Approver rule

Select Validate Approver from the Rule Type list.
The Run If condition is optional. Use this field to define a conditional statement to
control whether the rule runs.
Alternate The form exists on another server. Enter the remote server name in the
Server field.
Qualification area.
column.
8. Click Save.

The following figure illustrates an example of a Validate Approver rule from the Get Agreement
sample application. On the Set Fields tab, the qualification condition causes the rule to search the
Login Name field of the User form to find a match for a name entered in the approver field ($
Approver$) of the approval request form (AP-Sample2:Get Agreement).
Page 1767 of 4705
Home

Defining Signature Accumulator rules

A Signature Accumulator rule gathers data across the set of current signature records, for use by a
Statistical Override rule. You use Signature Accumulator rules when the standard signature
statistics gathered by the approval server are not sufficient.
The approval server automatically populates the hidden Total fields in the join forms with the
number of signature records in Pending, Approved, Rejected, Hold, More Information, Cancelled,
Error, and Closed states. These values are often sufficient to construct a Statistical Override rule. If
not, you can define Signature Accumulator rules to gather other data. This topic includes the
To define Signature Accumulator rules
Example of a Signature Accumulator rule
If a Signature Accumulator rule exists, it runs when a signature record is Approved, Rejected, or
Cancelled. The approval server collects a set of current signature records and applies the
Signature Accumulator rules for the approval process to each record (provided the Run If
qualification passes). After all rules have been applied for the current signature, the approval server
moves to the next signature and applies the rules.
A Signature Accumulator rule uses the Set Fields operation to collect and store the signature data.
Typically, the Set Fields operation in a Signature Accumulator rule performs an addition to
accumulate information, as in the following example:
$Temp Decimal 1$ = $Temp Decimal 1$ + $Signature Dollar Limit$
Page 1768 of 4705
Home
The assignment of the Set Fields operation is always to the Detail record that the approval server is
processing. After all rules have been applied for one signature, the approval server moves to the
next signature and applies the rules.
To define Signature Accumulator rules

Select Signature Accumulator from the Rule Type list.
Use the Run If qualification to include or exclude signatures. The Run If condition is
qualified on each signature, for example:
$Approval Status$ = "Approved"
If the Run If condition is met, the server will perform the Set Fields operation.
6. Enter a qualification statement to define the parameters for retrieving the authority data.
For example, to retrieve the current approver's signature authority limit, define a qualification
statement that sets $Approver$ (the current approver) to equal the user name field on the
signature authority form (such as Login Name on AP-Sample:Signature Authority).
column.
8. Click Save.
Example of a Signature Accumulator rule

The Get Agreement sample application includes an integrated set of Signature Accumulator and
Statistical Override rules in an Ad Hoc process. See Example of decision-making rules in a sample
application.
Defining Statistical Override rules

The Statistical Override rule evaluates data gathered by a Signature Accumulator rule or by the
approval server, and determines whether the process should immediately conclude with an
Approved or Rejected state, or should continue using the default approval server behavior. This
topic includes the following information:
Page 1769 of 4705
Home
To define a Statistical Override rule

Example of decision-making rules in a sample application
To change the rules to active status
To create a request that activates the example rules
To observe the approval process in the AP:Detail-Signature form
Example of a Statistical Override rule with default data
To define a Statistical Override rule

Select Statistical Override from the Rule Type list.
In Statistical Override rules, the Run If condition specifies the condition to be
evaluated. For example, to check if 50 percent or more of the signatures have been
approved, you create a Run If condition as follows:
$Total Signatures$ / $Total Approved$ >= .5
To derive the statistical override value, you can use static values, arithmetic
operations, keywords, the results from functions, and values from the record that the
approval server is processing in the AP:Detail-Signature form.
3. In the Set Fields Type field, select the appropriate action type.
See Using the Set Fields tab on the Rule Definition form .
5. In the On Serverfield, select the server where the form is located.
6. Enter a qualification statement, if any.
7. In the Fields Data area, type one of the following values (or its integer equivalent) into the
first entry in the Valuelist:
Approved
Rejected
In a Statistical Override rule, the Field column on the Set Fields tab is automatically
populated with the statistical override field name. The Set Fields function sets the
specified value in the statistical override field on the Detail form. The only valid
statistical override values are Approved or Rejected.
8. Click Save.
Page 1770 of 4705
Home
Example of decision-making rules in a sample application

The Get Agreement sample application uses an Ad Hoc process that contains four interrelated
statistical decision-making rules. These are Issue Retrieve Signature Limit and Issue Increment
Signature Limit (Signature Accumulator rules), and Issue Statistical Approval and Issue Statistical
Boundary Condition (Statistical Override rules).
For more information about the Get Agreement sample application, see Using the Lunch Scheduler
sample application.
Activating the sample rules

When the sample application is installed, these rules are set to Inactive status. To follow the
procedures in this section, you must change the status to Active.
To change the rules to active status
1. Open the Rule tab on the AP:Administration form.
2. In the Show For Process field, select the process Issue Approved.
3. Check the Status column. If any rules are set to Inactive, click View to open the rule.
4. In the Status field of the Basic tab, select Active.
5. Click Save, and Close.
Sample data for the statistical decision-making rules

The approvers in this example have the following signature authority:
Jack Miller's signature limit is $100.00.
Larry Goldstein's signature limit is $500.00.
Violet Anderson's signature limit is $2000.00.
The signature authority data that supports these sample rules is imported with the sample
applications and stored in the Signature Dollar Limit field of the AP-Sample:Signature Authority
form, as shown in the following figure.
Dollar signature limits in the AP-Sample:Signature Authority form
Rule functionality
Page 1771 of 4705
Home
When one of the sample approvers responds to a request, the sample statistical decision-making
rules run. Signature Accumulator rules run before Statistical Override rules. In this case, they both
have a Run If condition that causes the Set Fields action to occur only when the approver's
signature is set to Approved. (If the approver's signature is set to Rejected, these rules do not run
and default behavior causes the request to be rejected.)
The rule Issue Retrieve Signature Limit has execution order 0, so it runs first. It retrieves the
Signature Dollar Limit for the current approver, and sets the value in a temporary field (Temp
Decimal 1) on the Detail form.
For this rule, the Set Fields qualification used is:
'Login Name' = $Approvers$
This qualification retrieves the signature authority amount for the current approver by
matching the current approver's login name to the Login Name field on the AP-Sample:
Signature Authority form.
The rule Issue Increment Signature Limit has execution order 1, so it runs next. It increments
another temporary field in the Detail form with the current cumulative signature dollar value
for all approvers who have responded.
The example Statistical Override rules run after the Signature Accumulator rules are complete.
The rule Issue Statistical Approval has execution order 0. The Run If condition causes it to
run only when the Approver response is set to Approved.
It checks the current cumulative signature authority. If the current cumulative
signature authority is greater than $500, the Set Fields action sets Statistical Override
to Approved.
This approves the request, regardless of whether all approvers have responded. In
this way, the rule preempts the default approval server behavior and approves the
request. In this case, the other Statistical Override rule does not run because the
request is done.
If the current cumulative signature value is less than $500, the Set Fields action does
not occur, and the request is not yet done.
The rule Issue Statistical Boundary Condition has execution order 1. It runs only if the first
Statistical Override rule did not result in approving the request.
If signatures are still pending, the Set Fields action does not occur, and the approval
process continues.
If a hold exists or a More Information request is pending, the Set Fields action does
not occur, and the approval process continues.
Page 1772 of 4705
Home
If approvers remain, and the current cumulative signature authority is not greater than
$500, the Set Field action sets Statistical Override to Rejected, and the request is
done.
These two Statistical Override rules work together to assure that the approval process
always ends with the request set to either Approved or Rejected.
Note
This example assumes that the request is for an amount greater than $500.
The Get Agreement sample application does not include a field for the
amount of the request. In an actual approval process, you would also need a
field to gather the amount of the request, and a Run If condition to test the
amount.
Using the sample application with statistical decision-making rules
This section describes how to create a request that will activate the example Signature
Accumulator and Statistical Override rules, and how to observe the action of the rules after each
approval. Use a browser to perform these procedures.
To create a request that activates the example rules

1. Log in to the appropriate AR System server as the sample user Frank Williams.
2. Open the AP-Sample2:Get Agreement form in New mode.
3. In the Summary field, type:
I want to purchase a new laser printer .
4. In the Details field, type:
A really nice new laser printer costs $600.
This entry is only a comment, and does not affect the behavior of the rule.
5. In the Initial Approvers field, type:
Jack Miller; Larry Goldstein; Violet Anderson
Make sure to type a semicolon between each approver's name.
6. Click Save. To illustrate how statistically driven approvals work, the following procedure uses
the AP:Detail-Signature form to view the approval status after a response by each approver.
To observe the approval process in the AP:Detail-Signature form

1. Using a browser, log in to BMC Remedy AR System as an administrator, and open the AP:
Detail-Signature form in Search mode.
2. In the Approval Status field, select Pending, and click Search.
The approval request created by Frank Williams is pending for Jack Miller, Larry Goldstein,
and Violet Anderson.
3.
Page 1773 of 4705
Home
3. Log in as Jack Miller, open Approval Central, and approve the request from Frank Williams.
Observing rule activity in the AP:Detail-Signature form
4. Repeat steps 1 and 2.

The sample statistical decision-making rules require the cumulative signature authority to be
greater than $500. Because Jack's signature authority is weighted at $100, the approval is
still pending for either Larry or Violet's signature.
5. Log in as Larry Goldstein, open Approval Central, and approve the request from Frank
Williams.
6. Repeat steps 1 and 2.
The request is no longer pending when you search the AP:Detail-Signature form. Because
the cumulative signature authority of Jack Miller and Larry Goldstein is $600 ($100 + $500),
the approval condition in the Issue Statistical Approval rule is met, and the request is
approved, even though Violet has not responded.
Violet's signature authority is weighted at $2000. Therefore, Violet could have approved
Frank's request without requiring either Larry or Jack's approval.
Example of a Statistical Override rule with default data

The approval server automatically populates the hidden Total fields in the join forms with the
number of signature records in Pending, Approved, Rejected, Hold, More Information, Cancelled,
Error, and Closed states. You can use these field values in Statistical Override rules. In this case,
no Signature Accumulator rule is necessary.
For example, the following Run If condition would check if 50 percent or more of the signatures
have been approved:
$Total Approved$ / $Total Signatures$ >= .5
When the Run If condition has been met, the preempted decision is specified on the Set Fields tab.
Defining Completion rules

A Completion rule determines when the approval routing process is complete. For example, a
Completion rule can compare the current approver's signature authority against the estimated total
on the approval request.
Page 1774 of 4705
Home
Completion rules are usually teamed with the Get Authority or Get Authority Regular rules. The
authority rules retrieve information about an individual's or role's authority from other forms and
make the information available to Completion rules.
To define a Completion rule

Select Completion from the Rule Type list.
Construct a rule condition. The Completion rule condition defines whether the
approval process is complete (no further routing of the request is necessary). If the
condition is met, the process is complete. If it is not met, the approval server returns
the request to the Get Next Approver stage of the approval process.
2. Click Save.
Example of a Completion rule

The following figure illustrates an example Completion rule from the Lunch Scheduler sample
application. In this example, the temporary field Temp Decimal 1 on the AP:Detail form contains the
current approver's signature limit, which was retrieved by a Get Authority rule. The rule compares
the Estimated Total field on the approval request to this signature limit. If the condition passes, the
approval process is considered complete.
You must define a Get Authority or a Get Authority Regular rule for the Completion rule to work
correctly in this example.
Example of a Completion rule
Defining Approval Process Done rules

Approval Process Done rules define the actions taken when the approval process is done. The
approval process is considered done when an approval request is approved and passes a
Completion rule, or if it is Rejected, Cancelled, or ends with an approval error.
Approval Process Done rules are often used to change the state of the approval request. For
example, you use one Approval Process Done rule to change the state of the approval request to
Page 1775 of 4705
Home
Approved and another Approval Process Done rule to change the state of the approval request to
Rejected.
When an approver marks an approval request as either Approved or Rejected, the approval server
sets this status in the AP:Signature record for that approver. When the conditions are met to
approve the request, as determined by the process definition or a Completion rule, the approval
server sets the status in the AP:Detail record for the request. To change the status in the approval
request form, you use an Approval Process Done rule. This also applies to approval requests that
are cancelled or that end in an error.
To define an Approval Process Done rule

Select Approval Process Done from the Rule Type list.
Select one or more rule conditions from among the radio buttons: Approved, Rejected
, Cancelled, or Error.
The rule executes when the AP:Detail record is put into the selected state.
3. Select a value from the Set Field Type list. See Using the Set Fields tab on the Rule
Definition form.
4. In the Field Data area, enter the appropriate Field Name and Value to change the status of
the approval request.
5. Click Save to save the rule.
Example of an Approval Process Done rule

The following figure illustrates an example Approval Process Done rule from the Lunch Scheduler
sample application. This Approval Process Done rule is activated when the AP:Detail record is
marked Approved during the Completion check. In this rule, the Set Fields action sets the hidden
Approval Workspace field on the AP-Sample:Lunch Scheduler request form to Cost approved. In
this case, the value set is used by the chained processes in the application. A later action results in
marking the request approved overall. See Chaining approval processes.
Example of an Approval Process Done rule
Page 1776 of 4705
Home
Working with existing rules

This topic contains information about viewing, modifying, and deleting existing approval rules.
To filter the list by process type
To filter the list by rule type
To modify a rule
To delete a rule
You can use the table of rules on the Rule tab of AP:Administration to filter rules by process, or by
rule type.
To filter the list by process type

1. Open the AP:Administration form and click the Rule tab.
2. In the Show For Process field, select the name of the process whose rules you want to view,
for example, Issue Approval.
The list is refreshed with rules that belong to the selected process.
To filter the list by rule type

2. Clear any process name from the Show For Process field.
3. In the diagram below the table of rules, click the link for the rule type you want to view, for
example, Process Done.
The list is refreshed to show all existing rules of the selected type.
To modify a rule
2. Select the rule to be modified, and click View.
The AP:Rule Definition form opens in Modify mode, showing the current values for the rule.
3. Modify the rule as needed. For specific information about fields in the rule, see the "Defining"
topic for the rule type.
4. Click Save.
To delete a rule
Note
The delete operation is permanent and cannot be undone. Check for any rule
dependencies before deleting a rule. For example, Self Approval and Completion rules
might depend on a Get Authority, Get Authority Regular, or Get Authority Self rule. If the
Get Authority rule is deleted, the dependent rule will no longer function as designed.
Page 1777 of 4705
Home

2. Select the rule to be deleted from the list, and click Delete.
3. Click Yes when prompted to confirm the deletion.
The rule is deleted and no longer appears in the list of rules.
Using the Lunch Scheduler sample application

The Lunch Scheduler is a sample application deployed with BMC Remedy Approval Server (
approval server).
The following topics provide information about the purpose of the three processes in Lunch
Scheduler, and illustrates how to chain several processes together to form one approval process:
Lunch Scheduler application introduction
Main Lunch Scheduler forms
Sample process descriptions
Chaining approval processes
Working with sample users
Lunch Scheduler application introduction

The Lunch Scheduler sample application gathers approvals for employees of an imaginary
company to schedule lunches with customer accounts. It uses three processes, each a different
type, to implement the business rules of the company. Each process uses various types of rules.
This section describes the application's processes and how they work together. For information
about the rules used in each process, see Defining approval rules.
Note
The Lunch Scheduler and Get Agreement sample applications are not actually packaged
as BMC Remedy AR System applications. They consist of a related set of workflow
objects, including the approval request form, active links and filters, approval processes,
and approval rules.
Lunch Scheduler approval request form
Page 1778 of 4705
Home
When using Lunch Scheduler, the requester specifies information about the customer, the
restaurant, and the number of attendees. These choices populate fields containing details about the
total costs and information about the customer's relationship with the company.
Lunch Scheduler includes three different approval processes chained together and uses three
different filters with Run Process commands to start these processes. For more information, see
Using Run Process and $PROCESS$ commands .
The chained processes are:
Management Cost Authorization This is a managerial approval based on the total cost
of the lunch. It is a Parent-Child process, so the request is routed to a hierarchical series of
managers until a manager with sufficient cost authority approves it. The filter AP-Sample:
Start Cost Approval starts this process.
Major Account Level Approval This process runs if the account is a major or enterprise
account. It is a Level process that causes the request to be routed to the major account and
enterprise account teams. The filter AP-Sample:Start Level Approval starts this process.
Page 1779 of 4705
Home
Special Overdue Approval-- This process implements a special review of the request if the
account is currently overdue. It is a Rule-Based process. The filter AP-Sample:Start Overdue
Approv starts this process.
When requests are submitted in this application, they follow the appropriate approval processes.
The processes enforce the business rules of the company, and the approval data gathered
provides an auditable record of the business lunch activity at the company.
Note
The Questions, Comments with attachments, Notes, and Multi-process preview features
are available out-of-the-box with this sample application. For more information, see
AP-Show-Detail form.
Main Lunch Scheduler forms

This section lists the main forms associated with the Lunch Scheduler application.
AP-Sample:Lunch Scheduler This is the approval request form for the application.
AP-Sample:Lunch-Detail This is the inner join between the AP-Sample:Lunch Scheduler
and AP:Detail forms. It is used for internal processing by the approval server and for Global
Override operations. The join criteria is Request ID to Request.
AP-Sample:Lunch-Detail-Signatu This is the three-way inner join between the
AP-Sample:Lunch Scheduler and AP:Detail-Signature forms. This is the detail form that is
available to approvers when they choose to view a request in Approval Central. The join
criteria is Request ID to Request.
AP-Sample:Company This is a supporting form that stores data about customer
accounts. This data supports menus, workflow, and queries about the customer companies
in the application.
AP-Sample:Restaurant This is a supporting form that stores data about restaurants. This
data supports menus, workflow, and queries about the restaurants in the application.
AP-Sample:Signature Authority This is a supporting form that stores data about
approvers. The approval server uses this data from this form to identify hierarchical
relationships in the organization. This data supplies information about the account teams
and is used to identify next approvers in the Parent-Child and Level processes. The
application's rules and processes use information from this form about approvers' signature
authority to determine routing and whether the process is done.
Sample process descriptions

In this topic:
Management cost authorization
Major account level approval
Page 1780 of 4705
Home
Special overdue approval

The Lunch Scheduler application uses three separate approval processes that run serially.
Approval processes that are designed to run serially are referred to as a chained approval process.
Two of the processes run conditionally, using a condition statement to determine if the process is
required for each request.
This section describes the operation of each process. To see how each process is initiated and
how the processes are chained together, see Chaining approval processes.
Management cost authorization

This is a Parent-Child process that runs first and acts on every request. It uses Auto Approval and
Self Approval rules to determine if the requester has authority to approve his or her own request. If
not, the approval process routes the request to the manager by using the AP-Sample:Signature
Authority form. The approval server routes the request to subsequent managers until a manager
with sufficient authority signs the request. If no one with sufficient authority can be found for an
individual, or if an individual has no manager, the process terminates with an error.
The filter AP-Sample:Start Cost Approval starts the Management Cost Authorization process. This
filter uses the following application command:
Application-Command Approval New-Details -t "Management Cost

Authorization"
In this command, the -t option identifies the name of the process to run. See BMC Remedy
Major account level approval

This is a Level process that runs if the request is for lunch with a major or enterprise account. The
process uses a Completion rule to stop lunch requests for major accounts from advancing beyond
the major account level. Only enterprise accounts need to go to both the major account and
enterprise account levels. The Account Type field on the request form identifies the account as a
major or enterprise account.
The filter AP-Sample:Start Level Approval starts the Major Account Level Approval process. The
Run If criteria in the filter must be met for this filter to run. The filter uses the following command:
Application-Command Approval New-Details -s "$SCHEMA$" -e

"$Request ID$" -t "Major Account Level Approval"
In this command, the -s option identifies the name of the approval request form, the -e option
identifies the request ID for the current request, and the -t option identifies the name of the process
to run. See BMC Remedy Approval Server application commands .
Page 1781 of 4705
Home
Special overdue approval

This is a Rule-Based process that runs only if the company currently has an overdue account. This
process includes an example of using Prep Get Next Approver rules, which retrieve and set data for
Get Next Approver processing. The Account Overdue check box on the AP-Sample:Company form
identifies whether the account is overdue.
The filter AP-Sample:Start Overdue Approv starts the Special Overdue Approval process. The Run
If criteria of the filter must be met for this filter to run. The filter uses the following command:
Application-Command Approval New-Details -t "Special Overdue Approval"
In this command, the -t option identifies the name of the process to run. See BMC Remedy
Chaining approval processes

In this topic:
Using filters and a process status field
Restarting an approval process
The Lunch Scheduler application demonstrates the technique of chaining three different approval
processes together to approve Lunch Scheduler requests. The Lunch Scheduler application uses
workflow to start the initial process and to automatically run the additional processes when
necessary.
Using filters and a process status field

The main tasks implementing this workflow are to link the filters to the approval form with the
appropriate Execute On conditions, and to use a field to store the current process status on the
request form. The workflow filters that start each chained process test the process status field with
a Run If condition to determine whether the chained process should run.
In the Lunch Scheduler application, the filter that starts the initial process, Management Cost
Authorization, is configured to run when the AP-Sample:Lunch Scheduler form is submitted or
modified. Using the Submit condition assures that this process will run first. The chained processes,
Major Account Level Approval and Special Overdue Approval, use filters that are configured to run
only when the AP-Sample:Lunch Scheduler form is modified.
In the Lunch Scheduler application, a character field named Approval Workspace, ID 536870920,
tracks the process status. The Approval Process Done rules for each process enter a string in this
field to represent the current process status. The Run If conditions of the filters that start the Major
Page 1782 of 4705
Home
Account Level Approval and Special Overdue Approval processes test this value to determine if the
chained process should run.
The three processes in the sample Lunch Scheduler run in this order:
1. The Management Cost Authorization process runs first because the filter is configured to run
when the request is submitted.
In the Process Done stage of this process, the Approval Process Done rules populate
the Approval Workspace field of the Lunch Scheduler request form. For example, if
the request is approved, the Approval Process Done rule enters Cost-Approved in this
field.
2. Because the request form was modified, the filters for the two chained processes are run.
If the customer is a major or enterprise account, the filter's Run If condition causes the
Major Account Level Approval process to run.
When the Major Account Level Approval process is done, its Approval Process Done
rules modify the Approval Workspace field to indicate the process result. For example,
if the request is approved, the Approval Process Done rule enters Level-Approved in
this field.
If the customer is not a major or enterprise account, the Major Account Level
Approval process does not run.
If the account is not overdue, the Special Overdue Approval process does not run. If
the account is overdue, this process runs only after the Approval Workspace field has
been set to Level-Approved.
3. If the Major Account Level Approval process runs, its Approval Process Done rules again
modify the request form. This causes the filters for the two chained processes to start again.
In this case:
If the Level process completed with an approval, and the request is marked to
indicate that the account is overdue, the filter's Run If condition causes the Special
Overdue Approval process to run.
If the Level process completed with any other result (such as rejection), or if the
request does not indicate that the account is overdue, the Special Overdue Approval
process does not run, and the overall approval process is complete.
These three steps explain how the three processes are chained together to create the
overall approval process in the Lunch Scheduler application.
In addition to the filters that start the three processes, a fourth filter, AP-Sample:Test
Level Approval, runs whenever the approval request is modified. This filter runs only
after the Approval Workspace field is marked Cost-Approved, and if the Account Type
is not major or enterprise. The filter performs a set fields action that sets
Level-Approved in the Approval Workspace field. This assures that the Approval
Process Done rules function the same, even though the Level process did not actually
run.
Page 1783 of 4705
Home
Restarting an approval process

Occasionally, after an approval process has been started, it becomes inappropriate to proceed.
You can configure your approval process to restart in such a situation.
For example, in the Lunch Scheduler application, a request automatically restarts if anyone
changes the restaurant, the company, or the number of attendees. This ensures that users cannot
make a change after the request has been approved.
The sample application implements this functionality by using a set of filters that watch for a change
to the Company, Number of Attendees, and Average Cost/Person fields when the form is modified.
If this occurs, a filter sets the Approval Workspace field to contain a cancellation string. Another
filter resets the status of the request to Pending Approval in this case. (If the requester cancels the
request by another means, such as by modifying the Approval Status field, the request does not
restart because in that case the Approval Workspace field has not been set.)
Working with sample users

The approval server sample applications include records for a set of sample users that are
preconfigured for testing the Lunch Scheduler application.
Licensing sample users

To activate sample users, an AR System administrator must enter them in the User form, with
either a fixed or floating write license. Make sure you have purchased sufficient write licenses to
create the sample users as actual accounts in your AR System database.
Alternatively, you can use existing licensed users with the sample applications. To do so, you must
modify the data in the AP-Sample:Signature Authority form by replacing the sample login names
with login names that already exist in your AR System User form.
Sample user approval authority

The sample application users are set up in a Parent-Child hierarchy. Each has a spending authority
limit, as shown in the following figure. To follow the sample application procedures in this document
, configure at least the users Frank Williams, Jack Miller, Larry Goldstein, and Violet Anderson. If
you use your own existing AR System users, configure at least four users, one each with the
signature authority values matching these four sample users.
Hierarchy and spending authority of sample users
Page 1784 of 4705
Home
Worksheets for setting up processes and rules

The following topics provide information about the worksheets for setting up processes and rules:
Worksheets for setting up processes
Worksheets for setting up rules
Worksheets for setting up processes

The worksheets in this section are intended to assist you in designing the various components of
BMC Remedy Approval Server. Reproduce the worksheets as needed.
The following process worksheets help you set up your process and escalations:
Defining a process
More Information escalations
Signature escalations
You can print one or more of these worksheets at a time on separate pages, and use them as
checklists when setting up your processes and escalations.
Defining a process
Use this worksheet to help you define a process.
Process Name
___________________________
Form
___________________________
Type
___________________________
Request Owner Field
___________________________
First Approver Field
___________________________
Approval Success
No more approvals
Page 1785 of 4705
Home
Completion rule
If Multiple Approvers
One Must Sign
All Must Sign
Allow Only One Approver
Allow Ad Hoc Next Approver?

Anyone
Approver
No one
For Self Assignment

Use Get Next Approver Rules
Assign to Owner If Approver
Always Assign to Owner
Validate Approvers?
Yes
No
Require Password?
Yes
No
More Information escalations

Use this worksheet to help you set the More Information escalations parameters on the Process
form.
Business Calendar
Holiday Calendar
Notification: Still Outstanding
First Interval
______________
Unit
______________
Repeat Interval
______________
Unit
______________
Signature escalations
Use the following worksheets to help you set the Notification parameters on the Process form.
Page 1786 of 4705
Home
Normal priority notifications

Use Schedules
Business Calendar
Holiday Calendar
Automatic Action
After Interval
__________
Unit
__________
Change State
o Pending o Approved o Rejected

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Notification: Still in State Pending

First Interval
__________
Unit
__________
Repeat Interval
__________
Unit
___________
Notification: Still in State Error

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Notification: Still in State Hold

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Notification: Still in State More Information

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Page 1787 of 4705
Home
Urgent priority notifications

Use Schedules
Business Calendar
Holiday Calendar
Automatic Action
After Interval
___________
Unit
___________
Change State

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Page 1788 of 4705
Home
Low priority notifications

Use Schedules
Business Calendar
Holiday Calendar
Automatic Action
After Interval
___________
Unit
___________
Change State

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________

First Interval
___________
Unit
___________
Repeat Interval
___________
Unit
___________
Worksheets for setting up rules

The worksheets in this section are intended to assist you in designing the various components of
BMC Remedy Approval Server (approval server). Reproduce the worksheets as needed.
Use the following worksheets to help set up your rules:
Auto Approval rules
Get Authority rules
Get Authority Self rules
Self Approval rules
Navigating the BMC Remedy AR System Administration console interface
Get Authority Regular rules
Page 1789 of 4705
Home

Completion rules
Approval Process Done rules
Auto Approval rules

Rule Name
Purpose
For Process
Rule
Audit Text
Get Authority rules

Rule Name
Purpose
For Process
Run If Qualification
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Page 1790 of 4705
Home
Get Authority Self rules

Rule Name
Purpose
For Process
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Self Approval rules

Rule Name
Purpose
For Process
Rule
Audit Text
Page 1791 of 4705
Home
Validate Approver rules

Rule Name
Purpose
For Process
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification

Rule Name
Purpose
Rule Type
Run If Statement
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Page 1792 of 4705
Home

Rule Name
Purpose
Rule Type
If Multiple Results
Value from First
Values from All
Return Error
clear
One Must Sign
All Must Sign
clear
Next Approver Rule Is

Additive
Ending
Exclusive
clear
Run If Statement
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Page 1793 of 4705
Home
Get Authority Regular rules

Rule Name
Purpose
For Process
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Page 1794 of 4705
Home

Rule Name
Purpose
Rule Type
If Multiple Results
Value from First
Values from All
Return Error o clear
One Must Sign
All Must Sign
clear
Next Approver Rule Is

Additive
Ending
Exclusive
clear
Guaranteed Add
No
Yes
Run If Statement
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Qualification
Set Field
Value
__________
__________
__________
__________
__________
__________
Page 1795 of 4705
Home

Rule Name
Purpose
For Process
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Set Field
Value
__________
__________
__________
__________
__________
__________

Rule Name
Purpose
For Process
Set Fields Type
Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Set Field
Value
__________
__________
__________
__________
__________
__________
Completion rules
Page 1796 of 4705
Home
Rule Name
Purpose
For Process
Rule
Approval Process Done rules

Rule Name
Purpose
For Process
Rule State
Approved
Rejected
Cancelled
Error
Set Fields Type

Value
Query
SQL
Process
Other
From Form
On Server
__________
Server
__________
Set Field
Value
__________
__________
__________
__________
__________
__________
Approval forms
AR System administrators, process administrators, and approvers can access the most important
approval server functionality in the Approval Central and AP:Administration forms. For example,
BMC recommends using AP:Administration to access the AP:Server Settings and AP:
Admin-Rename forms, rather than opening the helper forms independently.
The following topics provide information about approval forms:
Administration forms
User forms
Page 1797 of 4705
Home
Administration forms
Administration forms are used either by approval administrators to manage process settings, or by
the approval server to manage data.
This section contains information about these administration forms:
AP-AdhocDetails form
AP-Administration form
AP-Admin-DeleteVerify form
AP-Admin-Rename form
AP-Admin-ServerSettings form
AP-Customize-SourceID form
AP-Detail form
AP-Detail-Signature form
AP-DynamicLabels form
AP-Form form
AP-Notification form
AP-Preview Data form
AP-PreviewInfo form
AP-PreviewSignatures form
AP-Process Administrator form
AP-Process Definition form
AP-Question-Comment-Info form
AP-Reserved Word form
AP-Role form
AP-Rule Definition form
AP-Signature form
AP-AdhocDetails form
This form stores the information entered through the AP:AdhocDialog form. See AP-AdhocDialog
form.
AP:AdhocDetails form
Page 1798 of 4705
Home
Fields on the AP:AdhocDetails form

Field
Description
Name
The name of the ad hoc approver.
Sequence
The sequence at which the ad hoc approver is added.
If Multiple
One Indicates that at least one ad hoc approver must approve the corresponding request.
All Indicates that at all the ad hoc approver must approve the corresponding request.
Independent
Yes Indicates to the Approval Server that the request can proceed to the next level of its process
without waiting for the signature of the current ad hoc approver.
No Indicates to the approval server that the current ad hoc approver's signature is required before the
request can proceed to the next level of its process.
Signature ID
The signature ID for which the ad hoc approver is added.
Detail ID
The detail ID corresponding to the signature for which the ad hoc approver is added.
Process Name
The name of the process to which the corresponding request belongs.
Form Name
The application request form through which the request was created.
Current
Sequence
The current sequence of the corresponding process.
Application
Request ID
The request ID of the application through which the corresponding request was created.
Locked
Yes Indicates to the approval server that the ad hoc approver entry is ready to be associated with the
corresponding approval request.
No Indicates to the approval server that the ad hoc approver entry is not to be associated with the
corresponding approval request.
Note
When AP:AdhocDialog is used to add ad hoc approvers, this field is set to Yes by default.
SigToBeDeleted
When an ad hoc approver entry is deleted, this field is used to indicate the corresponding signature entry that
should be deleted.
Page 1799 of 4705
Home
For more information, see Using a custom ad hoc dialog box with the approval server .
AP-Administration form
Process administrators use this form to create and modify the records that make up approval
processes. See Working with the AP-Administration form.
AP:Administration form Process tab
Fields on the AP:Administration form

Field
Description
Show for process
Use the menu to limit the display list to items associated with the selected process. This
field is not active for the Role and Form categories.
Process, rule, notification, role, form,

administrator, alternate
Click a tab to display a list of items of that type. This also selects which category of items
is used when you click the buttons on this form.
View
Click this button to open the item selected.
Search
Click this button to open a search form for items of the category determined by the
current tab.
Create
Click this button to create a new item of the category determined by the current tab.
Delete
Click this button to delete the currently selected item.
Refresh
Click this button to reload the displayed list.
Server settings
Click this link in the navigation pane to open the Server Settings form. See
AP-Admin-ServerSettings form.
Rename
Click this link in the navigation pane to open the AP:Admin-Rename form. See
AP-Admin-Rename form.
Page 1800 of 4705
Home
AP-Admin-DeleteVerify form
This form appears when a process administrator tries to delete an entry in the AP:Administration
form. The entry could be a process, rule, notification, role, form, another process administrator, or
an alternate approver.
You can delete only one entry at a time. When you select a process and click Delete, the dialog
indicates that if you proceed, the associated rules, notifications, and administrators are also deleted
.
Click Yes to delete the entry. The corresponding record in AP:Question-Comment-Info is
deleted.
Click No to close the dialog box without deleting the entry.
AP-Admin-Rename form
This form appears when a process administrator selects Rename in the navigation pane of the
Administration form.
Fields on the AP:Admin-Rename form
Field
Description
Select the type of object to be

renamed
Select Process to rename a process, or Form to rename a form.
Select the form to be renamed

/Select GUID of the process to
Select the process name from the menu. When BMC Remedy AR System supplies the GUID,
select the supplied GUID.
be renamed
Enter new process name /
Enter new form name
Scope of update
Type the replacement name for the process or form. The name of a process can be as long as
80 bytes. This equates to 80 characters in English and most European languages, but only 40
characters in double-byte languages.
Select an option from the menu to determine which of the associated detail records are
renamed.
All Requests renames all detail records for current and past approval requests
associated with the form or process.
Only Active Requests renames detail records only for currently open approval
requests associated with the form or process.
Including object itself

Select this check box to include the form or process you are renaming.
Deselect this check box if you have already renamed the form or process manually, and
are now renaming the associated requests.
Rename
Complete the rename operation.
Cancel
Close the form with no action performed.
Page 1801 of 4705
Home
Note
If you renamed a process manually instead of using the AP:Admin-Rename form, the
Rename command will not change names of attached rules. You must restore the process
name manually and rename the entire process, or you can rename all the attached rules
by using this form.
AP-Admin-ServerSettings form
Process administrators use this form to change server settings for the approval server. To open this
form, select Server Settings in the navigation pane of the AP:Administrator form.
Basic tab
Fields on the AP:Admin-ServerSettings form Basic tab
Field
Description
Logging Settings
Approval
Debug
Mode
Select this check box to enable approval server logging.
Log File
Type the directory path and file name for the log file.
Name
Other Settings
Definition
Check
Interval
Type a number of seconds to define how often the approval server checks the definitions for changes. A larger
number increases BMC Remedy AR System performance by checking less often. A smaller number of seconds is
useful while creating and testing a process. A zero (0) in this field causes the system to check for definition changes
with each operation.
Note: When testing custom applications, after creating a process, you should wait until the Definition Check Interval
period before creating requests. Otherwise, the processing of requests fails, and the following error is written to the
logs:
No join between applicationFormName and the approval detail form.
Private
AR
Server
RPC
Socket
Type the RPC socket number of a private queue to use when accessing the AR System server. Leave this field empty
if you do not use a private queue.
Plugin
Type the RPC socket number of a private queue used for loopback calls. Leave this field empty if your server does
Loopback
RPC
not use a dedicated queue for loopback calls.
Socket
Due-Soon
Interval
Page 1802 of 4705
Home
Type the duration after which approval requests that are due for action should be highlighted on Approval Central.
Use the adjacent drop-down list to specify whether this duration should be measured in hours or days. This interval is
subtracted from the value of the Automatic Action interval defined at the process level. Requests are displayed as
Due-Soon approvals on Approval Central. For more information, see Approval Central. For example, if the process
states that the automatic action interval for a request is five days, and the Due-Soon Interval is four days, the request
appears as a Due-Soon approval for the relevant approver one day before the automatic action is due.
Recent
Type the duration within which a user can see in the recent history an approval request that was submitted or acted
History
Interval
upon. Select the unit of measurement (Hours or Days) using the adjacent drop-down list. This affects My Recent
Approvals on Approval Central. See Approval Central.
Save
Save to apply your changes.
Reset
Reset to reload the form with the previously stored values.
Close
Close the form without saving any changes.
For information about the basic tab, see Configuring server settings for BMC Remedy Approval
Server logging and loopback calls.
Notifications tab
The Notifications tab allows you to enable or disable notifications for various approval server events
.
AP:Admin-ServerSettings form Notifications tab
You can specify whether or not to send notifications on the following events:
Page 1803 of 4705
Home
New Signature
Error
Approve
Cancel
Reject
More Info Return
Alternate Approve
Reject by /at Later Level
Alternate Reject
Cancel at Later Level
Override Approve
Reject by Another Approver
Override Reject
Hold
Global Approve
More Info
Global Reject
Change After Approval / Approved
Reassign
Before Reassign
When any of these event types occur during an approval process, the approval server acts
according to the following choices:
Disabled No notifications are sent.
Enabled Notifications are sent to all the approvers.
Enabled Including Alternate (default setting) Notifications are sent to all the approvers
and active alternates.
To use notifications, you must define the specific notifications for each process in the AP:
For information about the notification tab, see Setting notifications for approval events.
Escalations tab
AP:Admin-ServerSettings form Escalations tab
Page 1804 of 4705
Home
Fields on the AP:Admin-ServerSettings form Escalations tab

Field
Description
Still Active
Disabled means the approval server disables escalations for this event type during an approval process.
Still Active (
repeat)
Still
Pending
Still
Pending (
repeat)
Enabled means the approval server enables escalations for the approver list when this event type occurs
during an approval process.
Enabled Including Alternate (default setting) means the approval server enables escalations to the approver
list as well all active alternates when this event type occurs during an approval process.
These settings enable escalations for each event type. To use escalations, you must define the specific
escalations for each process in the AP:Process Definition form.
Still Hold
Still Hold (
repeat)
Still More
Info
Still More
Info (repeat)
Still Error
Still Error (
repeat)
For information about the escalation tab, see Setting escalations for approval events.
Page 1805 of 4705
Home
AP-Customize-SourceID form
This form appears when you click the Customize link on the Basic tab on the AP:Form. This form
enables you to specify the application form that opens when users click the Request ID link on
Approval Central.
The following table lists the fields available on the AP:Customize-SourceID form and their
descriptions.
Fields on the AP:Customize-SourceID form
Fields
Descriptions
Display
Displays the following window types. For information about each window type, see the Open Window action. Select
Mode
the mode in which you want to open the custom form.

Modify
Display
Modify Directly
Display Directly
Dialog
Search
Submit
Form
Displays the list of all available forms on the server, except the Display-Only forms.
Name
Note
If you selected Dialog for the Display Mode field, the Form Name list also includes the Display-Only form
names.
Select the form you want to open when you click the Request ID link on Approval Central.
View
Label
Displays the lists of available views for the selected form. Select a view for the selected form.
Note
If you do not select a view, the form opens in the default view.
Lookup
Field
Displays a list of fields present on the selected custom form (See the Form Name field description).
Note
This option appears if the Display Mode field contains one of the following items:
Modify
Display
Modify Directly
Display Directly
Page 1806 of 4705
Home
Select a field from the list with which you want to compare the Request ID field value (ID 1) on the application request
form. When you click the Request ID link on Approval Central, the custom form opens with a record that matches the
value in the selected field.
Note
Do not select a CLOB field.
This option does not support the following fields types:

Integer
Real
Decimal
Date/Time
Date
Time
Currency
Diary
Field
Mappings
Displays ten fields with IDs 14301 to 14310 that you can use to map the fields on the custom form to the fields on the
application request form.
Note
This option appears if you selected Dialog, Submit or Search in the Display Mode field.
Select an application request form field from the menu list that you want to map with the custom form field. You can
map up to 10 fields from the application request form to the custom form. The reserved IDs (14301 to 14310) are
assigned to these fields on the custom form. When you open the custom form through the Request ID link, these
mappings populate the custom form fields (14301 to 14310) with the corresponding values on the request form fields
that you selected or mapped for the current request.
Note
If you do not define the mapping between the custom form fields and the application request form, a blank
form opens when you click the Request ID link on Approval Central.
AP-Detail form
This form holds all data about an approval request. You can use this form to determine the status of
a request, and to see a history of activity on the request for any approval process. In addition to the
fields described in this section, the AP:Detail form also includes hidden Currency, Date, and Time
fields to store temporary results during workflow. For example, Currency Field 1 and Currency Field
2 are temporary fields of the currency type.
AP:Detail form
Page 1807 of 4705
Home
Fields on the AP:Detail form

Field
Description
Application
The BMC Remedy AR System populates this field the with name of the approval request form for the request.
Request
The BMC Remedy AR System populates this field with the AR System ID for the request.
Process
The BMC Remedy AR System populates this field with the name of the approval process for the current Detail
entry.
Comments
The BMC Remedy AR System stores comments entered by approvers in this field.
Priority
Displays the priority of this request, as set by the process.
Submitter
The BMC Remedy AR System populates this field with the AR System user name of the person who submitted
the request.
Status
The BMC Remedy AR System populates this field with the status of the request.
Approval
Audit Trail
This field contains an audit trail of date, time, and approver for actions taken on this request. This information is
part of the permanent record for this request.
Global
Approves the request, overriding the regular approval process. You must have process administrator override
authority to perform this action. However, BMC recommends using Approval Central for overrides.
Approve
Global
Reject
Rejects the request, overriding the regular approval process. You must have process administrator override
authority to perform this action. However, BMC recommends using Approval Central for overrides.
Assignee
Group
Permissions
The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports
the multi-tenancy feature.
Process
The BMC Remedy AR System populates this field with the GUID for the process associated with the request.
Instance ID
Signing
Method
Tracks the method (Approval Console or Email Engine) used for approving or rejecting a request.
AP-Detail-Signature form
This form is a join form that combines data from the AP:Detail and AP:Signature forms. You link
this form to your application's approval request form to create a three-way join when you add
approvals to your application. The approval server uses this form for internal processing. The
visible fields of this form appear by default in the three-way join form, which displays request details
.
To open the three-way join form, click Request ID on Approval Central, and click the Show
Page 1808 of 4705
Home
Signatures button (if implemented) on the application form that appears.

In addition to the fields described in this section, the AP:Detail-Signature form also includes many
hidden fields used to store temporary results during workflow.
AP:Detail-Signature form
Fields on the AP:Detail-Signature form

Field
Description
Approval
Status
The BMC Remedy AR System populates this field with the current status for the signature record.
Pending The approval server is waiting for a response to a request for this signature line.
Approved The request is approved for this signature line.
Rejected The request is rejected for this signature line.
Hold The request is on hold for this signature line, so no approval server actions occur.
More Information The approver associated with this signature line is waiting for a response to a More
Information Request.
Cancelled This request was withdrawn from the approval process.
Error The approval server detected an error state while processing this request.
Closed This request is ended and operations can no longer be performed on it.
Password
This field is optional. The administrator should configure it to appear on the three-way join form when the process
has Require Passwords set to Yes. Type your password for verification. The approval server verifies the contents
of this field before a Save operation occurs.
Approval
Priority
Displays the priority of this request as defined in the approval process.
Comments
Enter any comments you want to store with the approval request.
Next
Approvers
When the process allows ad hoc approvers to be added, type the AR System user names of the next approvers.
If Multiple
If you enter ad hoc approvers, select how the approval process operates when more than one approver appears in
the Next Approver field.
Approvers
One Must Sign A single signature entry is created for all approvers in the Next Approver field. Only one
of those approvers needs to take action on the request.
All Must Sign Separate signature entries are created for all approvers in the Next Approver field. All
approvers must act on the request for it to move to the next stage.
Page 1809 of 4705
Home
Field
Description
Reassign
To
Type the AR System user name of an approver to whom you want to reassign this request.
Approvers
The BMC Remedy AR System populates this field with the AR System user name of the approver for this signature
line.
Approval
Audit Trail
This field contains an audit trail of date, time, and approver for actions taken on this request. This information is
part of the permanent record for this request.
Assignee
Group
The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the
multi-tenancy feature.
Permission
For
Application
The BMC Remedy AR System populates this field with the name of the approval request form for the request.
For
Request
The BMC Remedy AR System populates this field with the AR System ID for the request.
For
Process
The BMC Remedy AR System populates this field with the name of the approval process of this request.
Submitter
The BMC Remedy AR System populates this field with the name of the person who submitted the request.
Approver
Signature
This field records the AR System user name of the approver who has responded for this signature line. The name
appears only after an authorized person modifies the Approval Status field.
Alternate
Signature
This field records the AR System user name of the alternate approver who modifies the Approval Status field, if any
.
More
Information
This field contains More Information requests sent by the approver for this request and signature line, and the
responses to those requests. The field is not populated until the requestee responds to the More Information
request.
Show
Details
Opens the approval request form for this request.
More
information
Opens AP:Dtl-Sig-MoreInfoDialog and searches for More Information requests associated with this approval
request.
Signing
Method
Tracks the method (Approval Console or Email Engine) used for approving or rejecting a request.
AP-DynamicLabels form
This form enables you to set locale-specific labels for four fields on the AP:Show-Detail form, and
the tool tip labels for the fields on the AP:Form Tooltip Configuration tab.
AP:DynamicLabels form
Page 1810 of 4705
Home
Fields on the AP:DynamicLabels form

Field
Description
Application
Select an application name.
Process
Select the process for which you want to customize the field labels.
Locale
Select a locale from the menu.
Labels for Request Details:

Label for
14508
Provide labels for the fields 14508, 14509, 14510, and 14511, and click Save. For information about where these
labels appear, see AP-Form form.
Label for
14509
The default labels for these fields are GL Account, Cost Center, Total Cost, and Phase, respectively.
Label for
14510
Label for
14511
Labels for ToolTip:
Label for
14711
Provide labels for the fields 14711, 14712, 14713, 14714, 14715, 14716, 14717, 14718, 14719, and 14720, and
click Save. For information about where these labels appear, see AP-Form form.
Label for
14712
Label for
14713
Label for
14714
Label for
14715
Label for
14716
Label for
14717
Label for
14718
Page 1811 of 4705
Home
Label for
14719
Label for
14720
AP-Form form
This form is linked to the Form tab of AP:Administration. Process administrators use this form to
attach approval request forms to the approval server.
Basic tab
AP:Form Basic tab
Fields on the AP:Form form Basic tab

Field
Description
Form Name
Select a form on the current server, or type a form name.
Lookup
Keyword
Type a keyword to be used by the approval server when searching for this form. The keyword acts as a
permanent search term, even if the name of the form changes.
Used By
This field contains the name of the BMC Remedy AR System application that uses this form. BMC Remedy
AR System populates this field with Approval.
Approval
Reporting
Enter the name of a form used for reporting, if any.
Assignee Group
Permission
The BMC Remedy AR System populates this field with the Assignee Group for the request. This field
supports the multi-tenancy feature.
Search
In Search mode, click this button to perform your search.
Save
In Submit mode, click this button to save your changes.
Close
Click this button to close the window.
Advanced tab
The Advanced tab enables Process administrators to define field mappings for a request form at
the application level. These mappings are not mandatory. Not all field types are supported for
mapping.
Page 1812 of 4705
Home
Warning
If you define mappings on the unsupported field types on the AP:Form form, the approval
server might fail.
Supported field types
Unsupported field types
Character
Date
Integer
Real
Time
Diary
Date/Time
Currency
Attachment
Checkbox/Radio box
AP:Form Advanced tab

The fields on this form are reserved field IDs in the approval server. You can map them to other
fields on the application forms by using the corresponding menus. The values from the mapped
fields are displayed on Approval Central and AP:Show-Detail. The following table describes where
these values appear.
Fields on the AP:Form form Advanced tab
Field
Description
Application
Request ID
Map to an application ID, which could be the request ID or any other ID field in the application. For example, BMC
Change Management uses its own IDs to represent a particular record, apart from the one generated by BMC
Remedy AR System. You can map this field to that field from the BMC Change Management application. The
value from the mapped field is displayed on Approval Central as the Request ID link. If the value is NULL, the
request ID is displayed by default. See Approval Central.
Requestor
Map to a user field on the application form. The value from the mapped field is displayed in the Requestor column
on Approval Central.
Field 1 {
14506}
The value from the mapped field is displayed in the Summary column on Approval Central.
Field 2 {
14507}
Currently, the approval server does not use Field 2. This field was used in releases earlier than 7.5.00 to display
certain fields on the approval console.
Page 1813 of 4705
Home
Field 3 {
14508} Field
The values from the mapped fields are displayed in the top panel on AP:Show-Detail. For example, for a request
of the Lunch Scheduler sample application, these values appear against the following labels:
4 {14509}
Field 5 {
14510} Field
6 {14511}
P-C GL Account
P-C Cost Center
P-C Total Cost
P-C Phase
In your application, you can specify the labels that should appear for these fields on AP:Show-Detail.
Field 7 {
14512}
The value from the mapped field can be used in accordance with the user requirement. Currently, the value of
Field 8 {
14513}
The value from the mapped field is displayed in the Notes field for a request on Approval Central.
Field 9 {
14514}
The value from the mapped field is displayed in the Attachment table on the AP:Show-Detail form.
this field is not displayed anywhere on Approval Central.
Note: You can map this field only to other Attachment fields.
Define
Labels
Click to define labels for the fields 14508, 14509, 14510, and 14511, for various applications, processes, and
locales. The AP:DynamicLabels form appears. See AP-DynamicLabels form.
Save
Close
Note
Changing the field mappings on this form only affects new requests. The older requests
retain their original field values.
ToolTip Configuration tab

The ToolTip configuration tab enables Process administrators to define tool tip field mappings for a
request form at the application level. These mappings are not mandatory.
AP:Form Tooltip Configuration tab
You can map them to fields on the application forms by using the corresponding menus. The values
Page 1814 of 4705
Home
from the mapped fields are displayed in a tool tip on Approval Central. The following table
describes where these values appear.
Fields on the AP:Form form --- ToolTip Configuration tab
Field
Description
Field 1 {
14711}
The values from the mapped fields are displayed in a tool tip that appears when you hover on the summary column
of the request on Approval Central.
Field 2 {
14712}
Field 3 {
14713}
Note: To display the tool tip, you must also define labels for all the mapped fields. If you have defined labels, but
not mapped any fields, then the tool tip will display the labels without corresponding value. If you have mapped the
fields, but not defined any labels, the tool tip does not appear.
Field 4 {
14714}
Field 5 {
14715}
Field 6 {
14716}
Field 7 {
14717}
Field 8 {
14718}
Field 9 {
14719}
Field 10 {
14720}
Define
Labels
Click to define labels for the fields 14711, 14712, 14713, 14714, 14715, 14716, 14717, 14718, 14719 and 14720,
for various applications, processes, and locales. The AP:DynamicLabels form appears. See AP-DynamicLabels
form.
Save
Close
Note
If the value from the mapped fields contains any HTML content, approval server renders
the content as HTML content.
For information about the Administrative Information tab, see Administrative Information tab on
AP-Alternate form.
Page 1815 of 4705
Home
AP-Notification form
Process administrators use this form to create and modify notifications sent by approval processes.
This form opens from when you click View or Create from the Notification tab of the AP:
Basic tab
AP:Notification form Basic tab
Fields on the AP:Notification form Basic tab

Field
Description
Notification
name
Type a name for the notification.
Process name
Select the process name from the list. The process must already exist.
Status
Use the drop-down list to select the status of the notification.

Active Notification will be sent when the process triggers it.
Inactive The notification will not be sent.
Process Instance
ID
The BMC Remedy AR System populates this field with the GUID of the selected process.
Notify On
Use the drop-down list to select the type of event that will trigger this notification.
Note
If you choose Error, the notification is sent only if the status of the request is set to Error in the AP:
Signature and AP:Detail forms.
Page 1816 of 4705
Home
Assignee Group
Permission
Qualification
If necessary, enter additional conditions to control when the notification is sent. The approval server uses
condition in this field in addition to the Notify On event.
Search
In Search mode, searches the AP:Notification form.
Save
In New mode, saves the notification.
Close
Close the window without saving changes.
Details tab
AP:Notification form Details tab
Fields on the AP:Notification form Details tab

Field
Description
Method
Use the drop-down list to define the method of notification.

None No notification is sent.
Email Notification is sent by email.
User Default Notification is sent using the default notification method defined in the User form for each of
the recipients.
Workflow For information about this notification method, see Creating workflow-based notifications.
If you select Email or User Default, the Email tab is activated.
Send to
Notify List The approval server sends notifications to the default recipients for the event type. See the
following table. When a request is approved or rejected, the notification is sent based on the If Multiple
Approvers setting on the AP:Process Definition form:
One Must Sign The notification is sent only to that approver and not the other approvers in the
signature line.
All Must Sign The notification is sent to that approver and all the other approvers for whom
signature lines have been created. See AP-Process Definition form.
Other If you select Other, enter the notification recipients in the field to the right. To use a field reference (
for example, $ fieldName$ ) click the field menu icon.
Page 1817 of 4705
Home
Subject
Type a subject line for the notification message. You can select AR System variables from the list.
Additional
To attach additional field information to the notification, use the drop-down list to select the field names.
Fields
Message
Type the message text for the notification. Use the drop-down list to include AR System variables in the message
text.
Priority
Select a priority from 0 to 10 to allow users to sort their notifications by order of importance. Entries created with an
earlier version of the approval server will default to a Priority of 1.
Email tab
AP:Notification form Email tab
Fields on the AP:Notification form Email tab

Field
Description
Fields
Each field on this form includes the Fields button. Use this menu to select fields from the approval server forms
when completing each field, if appropriate.
Keywords
Each field on this form includes the Keywords button. Use this menu to select AR System key words when
completing each field, if appropriate.
Mailbox name
Enter the name of the AR System outgoing mailbox that you want to handle the notifications.
From
Enter a name for the sender of the notification, or select variables from the Fields and Keywords menus.
Reply To
Enter a name for the Reply-To field of the notification email, or select variables from the Fields and Keywords
menus.
CC
Enter the recipients of the notification email, or select variables from the Fields and Keywords menus.
BCC
Enter the recipients of the notification email who should receive blind copies, or select variables from the Fields
and Keywords menus. Recipients entered in this field do not appear in the recipient list for other users.
Use Email based

Approval
template
Select "Yes" to use the email based approval template. The appropriate template name will be automatically
displayed in the Content field. Default value is "No".
Organization
Enter a company name, an organization, a keyword, or a field reference to a name for the notification email.
Page 1818 of 4705
Home
Header
Enter the names of templates to use for the header of the email notification. You can enter the name of the
template directly, or enter a field reference or keyword to retrieve a template name.
Content
Enter the names of templates to use for the content of the email notification. You can enter the name of the
Note
If you select "Yes" for the Use Email based Approval template field, the template name will be
automatically displayed for this field.
Footer
Enter the names of templates to use for the footer of the email notification. You can enter the name of the
For information about the Administrative Information tab, see Administrative Information tab.
AP-Preview Data form

This form stores intermediate data that is used to generate the multi-process preview for an
approval request. See Using the multi-process preview.
The field values correspond to the input parameter values of the Generate-Multi-Process-Preview
command. See BMC Remedy Approval Server application commands .
AP:Preview Data form
Fields on the AP:Preview Data form
Page 1819 of 4705
Home
Field
Description
Application
Request ID
The application request ID.
Application
Form Name
The application form name.
Preview Type
Indicates whether a single process or multi-process preview is generated.
Process List
The list of processes separated by semicolons ( ; ).
Phase-Process
List
The semicolon-separated list of processes, each prefixed with some related information and separated by a
colon (: ). Some processes might not have any related information prefixed.
AP-PreviewInfo form
The approval server uses this form to store preview data when the process is configured to
generate previews. Process administrators can use this form to preview all the approvers assigned
to work on an approval request.
You must enter data into all the visible fields to search the AP:PreviewInfo form.
See Configuring approval server to work with flowcharts .
AP:PreviewInfo form
Fields on the AP:PreviewInfo form

Field
Description
Request/
The request ID that you want previewed.
Ticket
Number
Single/
Multi
Process
Select the appropriate value to indicate whether you want to generate a single process or multi-process preview.
Users have an option of specifying a value as a qualification for the query being made.
Page 1820 of 4705
Home
Field
Description
Retrieval
Type
Full Returns list of all completed signatures (from the AP:Signature form), and all previews from the
preview form.
Remaining Returns list of only the preview signatures (those that are not yet opened and entered in the
AP:Signature form).
Complete Returns list of only the signatures that have already been completed, that is, those that already
exist on the AP:Signatures form, and are still open (Pending/More Info). You can query the AP:Signature form
for this information as well, but form displays such data in a better format.
Show for
Process
Select the process related to the request.
Application
Select the application form name related to the request.
Form
Name
AP-PreviewSignatures form
This form keeps track of signature entries generated as part of the approval preview feature (except
for real-time preview).
Note
The approval server uses this form internally, and users must not use this form to create
records manually.
When a signature or detail record-related application command is submitted, the approval server
creates signatures of future approvers in the chain if the Generate Preview field for the process
definition is set to one of the following:
On Request Only
On Start of Process
On Generation or Change to a Signature
These signature records are stored in the AP:PreviewSignatures database schema.
Real-time preview does not use the AP:PreviewSignatures form because it stores signature records
in-memory.
AP:PreviewSignatures form
Page 1821 of 4705
Home
Fields on the AP:PreviewSignatures form

Field
Description
Approval ID
The application request ID.
Approval Status
The current status of the request.
Approvers
List of approver names separated by semicolons.
AP-Process Administrator form

This form opens when you click View or Create on the Administrator tab in AP:Administration. AR
System administrators and process administrators use this form to create, delete, and modify the
abilities of other process administrators. See Configuring process administrator capabilities.
AP:Process Administrator form Process Administrator tab
Fields on the AP:Process Administrator form Process Administrator tab

Field
Description
Individual
Enter the AR System user name of the individual who is to be a process administrator.
Authority
Use the drop-down list to select the privileges allocated to the individual in the field preceding.
Full Admin Grants the ability to modify processes as well as the ability to approve or reject a request
regardless of the normal process.
Override Only Admin Grants the ability to approve or reject a request regardless of the normal process,
but not the ability to create or modify processes.
Notify
Method
Use the drop-down list to determine the method for notifications to this user.
None The approval server does not send a notification.
Email The approval server sends the notification through email. Notifications can be sent to non-AR
System users, to an alias for a group, or to an email address representing a program.
User Default The approval server sends the notification using the default notification method defined in the
User form for each of the recipients.
Page 1822 of 4705
Home
Covering
This option determines the processes for which this person receives process administrator privileges.
All Grants process administrator authority for all Approval processes defined in the Process Definition form.
Specific Process Grants process administrator authority for the process you select in the Process Name
field.
Process
Name
Use the drop-down list to select a process name if you selected Specific Process in the Covering field.
Status
Use the drop-down list to determine the status of this person's process administration privileges.
Active The process administrator authority is enabled and the user can immediately work on processes or
requests.
Inactive The process administrator authority is disabled. This allows you to temporarily suspend authority
of the user when it is not needed, and enable it at a later time.
Search
In Search mode, searches the AP:Process Administrator form.
Save
In New mode, saves the entry to the form.
Close
Close the window without saving.
For information about the Administrative Information tab, see Administrative Information tab.
Note
The first process administrator must be created by your AR System administrator.
AP-Process Definition form

This form opens when you click View or Create on the Process tab of AP:Administration. Process
administrators use this form to create and modify approval processes. See Using the Process tab
on AP-Administration.
Basic tab
AP:Process Definition form Basic tab
Page 1823 of 4705
Home
Fields on the AP:Process Definition form Basic tab

Field
Description
Process
Enter a name for this process. Process names must be unique and must have no more than 254 characters (
including spaces). It is helpful to make the name descriptive of the process's function.
Form
Select the AR System form that you are connecting to the approval server. This becomes the approval request
form.
Note: You must add the form to the Form tab of the AP:Administration form to make it appear on this menu.
Type
Select the process type from the available options:

Parent-Child
Level
Ad Hoc
Rule-Based
See Approval process types.
Status
Select the process status from the available options:

Active (Default) The process generates approvals for the approval request form.
Inactive The process is disabled and generates no approvals.
You might want to set the status to Inactive during the development of the process and the associated rules. When
all the appropriate rules are in place, you can modify the process and set the status to Active. Requests related to
processes in the Inactive state are displayed on Approval Central, but approvers cannot act upon such requests.
The following message is displayed in such an event:
This action is not allowed on the selected requests, because the related process is inactive. (ARERR
46411).
However, approvers can take action on requests that are related to processes in the Inactive state from the
application's three-way join. To prevent approvers from acting on such requests from the three-way join,
developers need to write the appropriate workflow.
Request
Owner Field
Enter a valid AR System user name or select the field that identifies the owner of the approval request from the
menu. The fields in this menu are populated from the approval request form. See Request Owner field.
First
Approver
Field
Enter a valid AR System user name or select the field that identifies the first approver for this process from the
menu. The fields in this menu are populated from the approval request form. This field is required for Ad Hoc
process type, optional if you allow ad hoc overrides, and otherwise unused.
Generate
Preview
Select generate preview setting from the available options:

None The approval server does not generate preview information in the Preview Signatures form for the
process.
On Request Only The approval server generates preview information only when it receives a
Generate-Preview signal. With this option, the application controls the load on the approval server.
On Start of Process The approval server generates preview information when any of the following
events occurs:
A Generate-Preview signal is received.
A new approval process starts (for example, when a details request is created, or when an existing
request that was closed is reopened).
A new signature is created.
The status of an existing signature changes.
On Generation or Change to a Signature The approval server generates preview information when any
of the following events occurs:
Page 1824 of 4705
Home
A Generate-Preview signal is received.

A new approval process starts (for example, when a details request is created, or when an existing
request that was closed is reopened).
A new signature is created or the status of an existing signature is changed.
Real-time Only The approval server generates preview information (but does not cache it) only when a
preview is requested. This option displays the most current information, but it puts the highest load on the
approval server.
Note: If you select the On Request Only, On Start of Process, or On Generation or Change to a Signature option,
the preview displayed might not be the most current information.
Can
Reassign?
Specify whether approvers should or should not be able to reassign a request of this process type to another
Full Name
Select a form that provides the full name of the approver to be added to the signature line. You could also enter a
custom form name by using the adjacent text field. This information is pushed to the Full Name field on the AP:
Signature form. For more information, see Full Name and Full name form.
Form
Exclude
User Field
approver.
This menu lists all the fields on the application form. Select a field that contains user names. The users from the
selected field are excluded from the list of approvers (their signatures are not created) for a request of this process
type. If the selected field contains a role:
Users belonging to that role are excluded.
If the role is part of an approval chain and contains only one user, the other approvers can act on the
request and the process can complete successfully regardless of the One Must Sign or All Must Sign
setting. If an excluded user is an approver in the middle of an approval chain, the approver before the
excluded user can act on the request, and the request remains open. However, when the excluded user is
encountered, the request state is changed to Error on the application and detail form, and no further action
can be taken. The exclusion takes place only after the Get Next Approver rule is executed. Because these
users are excluded from the list of approvers, they do not appear on the Approver tab of the AP:
Show-Detail form. For a Level process, if one of the approvers is excluded on a level, other approvers can
take action, and the request can proceed. When processing Auto Approval and Self Approval rules, the
approval server ignores this field. If a user specified in this field is the only approver for the request, the
approval process fails and an error is reported. The user exclusion operations and the related errors, if any,
are listed in the approval log files. The values in this field are ignored in the following situations:
When defining a process:
If you select the Ad Hoc type.
If one of the users specified for exclusion is also specified as the first approver.
When acting on a request (regardless of process type):
If an approver reassigns a request to one of the users specified for exclusion.
If an approver specifies one of the users specified for exclusion as the next approver.
Note: The check for excluding users from the list of approvers is done before signature creation,
therefore it does not impact the requests for which signatures have already been created.
Approval
Success
Select the manner with which the approval server determines whether the approval process for a request is
complete:
No More Approvers (Default) The process is complete when all signature lines are complete. If you
select this option and if the signature line for a request is cancelled and no other signature exists, the
request is marked Approved, not Cancelled.
Completion Rule Use a Completion rule to determine the successful completion of the approval process
. If you select this option, you must create a Completion rule and associate it with this process or the
process is never considered complete.
If Multiple
Approvers
Page 1825 of 4705
Home
This field applies only if you are defining an Ad Hoc process or are going to allow ad hoc overrides. The value you
select determines how many signature line records the approval server creates when building an approver list.
Specify using the available options how to manage signature entries when a request is assigned to multiple
approvers:
One Must Sign Create only one signature line for a list of potential approvers. The signature line is
complete when one of the approvers acts on the request. The first approver to act on the request
determines the response; the request is withdrawn from the other approvers.
Note: The field for approver names on a signature-line record is limited to 255 characters on certain
databases. Using roles might help you to work around this limitation, because roles are internally expanded
to individual approver names during further processing.
This option overrides 4the If Multiple Approver setting on any roles selected as an approver.
All Must Sign Create separate signature lines for each approver. All approvers must act on their own
signature line for the request to proceed.
If an approver list includes roles, the If Multiple Approver setting for the specific role determines whether the role is
expanded into individual signature lines for each member of the role or a single signature line is created for the
entire role. See Defining roles.
Allow Only One Approver (Default) Create a single signature line for one individual. If you use this
option and a requester specifies multiple approvers, the approval server stops the process and marks it as
an error.
For information about how notifications are sent when a request is approved or rejected, see AP-Notification form.
Allow Ad
Hoc Next
Approver?
This field applies to Parent-Child, Level, and Rule-Based process types. Specify using the available option
whether users can add approvers to the approver list for a request:
Anyone The requester and any approver can select an ad hoc next approver.
Approver Only approvers can specify an ad hoc next approver.
No one (Default) The process should not allow users to specify an ad hoc next approver.
For Self
Assignment
This field specifies how the approval server determines the next approver, when the requester is not the person
who submitted the approval request (for example, when an assistant enters an approval request on behalf of
someone else). Select from the available options:
Use Get Next Approver Rules (Default) Use a Get Next Approver rule to determine the first approver.
Assign to Owner if Approver Use the requester as the first approver if the requester is defined as a
valid approver for the approval server. If you select this option, you must define a Validate Approver rule to
verify whether the owner is a valid approver.
Always Assign to Owner Use the requestor as the first approver in all cases.
Validate
Approvers
This field tells the approval server whether to verify the value in your next approver field with a Validate Approver
rule when creating a request. Select from the available options:
Yes Validate the approvers when saving a request.
No (Default) Skip validating approvers.
Require
password
This field determines whether the approver must enter a password to save changes to an approval request. Select
from the Available options:
Yes Mandate the use of a password when saving changes to an approval request.
No (Default) Allow saving changes to request without validating the password.
Page 1826 of 4705
Home
Assignee
Group
Permissions
The BMC Remedy AR System populates this field with the Assignee Group for the request; the Public group is
selected by default. The approval server uses this field to support multi-tenancy for use by application service
providers. If you use this field for multi-tenancy support, create workflow to populate this field with the correct
assignee group name. You do not need to change this setting when creating the rule. The ID of this field is 112,
and it appears on all approval server forms. The field 112 value from records created in the AP:Detail form is used
automatically in all the other approval server forms (for example, AP:Signature, AP:More Information, and so on).
See Error 333 and Assignee Group Permission.
Ad Hoc
Settings
This field is enabled only if you select:

An Ad Hoc process type
A process type other than Ad Hoc and "Anyone" or "Approver" in the Allow Ad Hoc Next Approver field The
options are:
Default (Default) Disables the adjacent Ad Hoc Form field. When an approver clicks the Adhoc button on
the AP:Show-Detail form, the AP:AdhocDialog dialog box appears. Data about the ad hoc approver entered
through AP:AdhocDialog is stored in the AP:AdhocDetails form.
User Defined Enables the adjacent Ad Hoc Form field. When an approver clicks the Adhoc button on
the AP:Show-Detail form, the form specified in the Ad Hoc Form field appears. Data about the ad hoc
approver entered through this form is stored in the AP:AdhocDetails form.
Ad Hoc
Form
This drop-down list displays all the forms in the AR System server. Select the form that you want to be displayed
when an approver clicks the Adhoc button on the AP:Show-Detail form. Approvers should be able to provide data
about ad hoc approvers in this form, and the form should have the necessary workflow to store this data in the AP:
AdhocDetails form. If you select a custom form, make sure that application developers have added the necessary
fields and workflow to it.
Retrieving
first
approver
failed, error
?
This field determines the course of action in case the approval server fails to retrieve the first approver for a
request.
Yes (Default) Set the state of the request to Error and add the error details to the audit trail.
No Set the state of the request to Pending. Later, if Add-Sig is started for that request, the same AP:
Detail record is used.
Search
Appears in the Search mode; click to search the AP:Process Definition form.
Save
Appears in the New mode; click to save the entry to the AP:Process Definition form.
Close
Closes the window without saving.
Request Owner field

The setting of this field is crucial for:
The execution of Self Approval rules The value of this field is compared with the current
user's name, and if they match, the rule is executed, otherwise it is skipped.
Finding the first approval in the approval chain In the Parent-Child, Level, and Rule-Based
process types, the first approver in the chain is completely dependent on the name of the
person stored in the field mapped to AP:Process Definition > Request Owner Field. The
Request Owner field must contain a valid entry in the approval lookup form (for example,
AP-Sample:Signature Authority is the lookup form for the Lunch Scheduler sample
application).
To set an appropriate value for Request Owner field, a process administrator must consider
the following:
Does this field store the name of the person defined in the approval lookup form?
Page 1827 of 4705
Home
Is the organizational structure for this user defined in the approval lookup form?
The value of Request Owner field is not considered when finding the first approver in
an ad hoc process, because the requester is responsible for specifying all the
required approvers.
Full name form

If your application does not contain a User form that contains the full name of a person, you should
create a custom form that provides this information. The custom form should contain the following
character fields, with their input lengths set to 0:
The field with the ID 10001 contains the login name.
The field with the ID 10002 captures the full name, which can be generated by any means.
Create a filter on this form, which runs on a service action. This filter uses the data in the first field (
10001) as input to generate the corresponding full name for the second field (10002).
See Full Name.
Configuration tab
AP:Process Definition form Configuration tab
Fields on AP:Process Definition Configuration tab

Field
Description
Process Intervals
These fields are used to determine the action date for signatures on a request pertaining to this process. See Associating an
action date for a process or signature .
Process
Due
Enter a number in the Interval field and the select the Unit of measurement. This specifies the total duration in
which the process is due.
Signature
Enter a number in the Interval field and the select the Unit of measurement. This specifies the total duration in
which each signature for the process is due.
Due
Note: If you enter a value more than what is specified in Process Due, this value is ignored. The value in Process
Due is then used to compute the action date, instead of the one you specify in this field.
Buffer
Period
Enter a number in the Interval field and the select the Unit of measurement. This buffer period is considered as a
delta to be deducted from all process intervals, except Signature Due, when computing the action date.
Page 1828 of 4705
Home
Enable
Preview
Select Yes to use the Preview feature in calculating the Signature Due Date. The Preview feature is used to fetch
information about the future approvers, to calculate the total number of signatures required to complete the
process. The Signature Due interval is then computed as the Process Due interval divided by the total number of
signatures required. Select No to avoid the use of the Preview feature. In this case, only the value specified in
Signature Due is considered.
Note: This field is used only in the case of Parent-Child and Level processes. The value of this field is not
considered when calculating the Signature Due interval for ad hoc requests.
Specify menu name to list users for the following operations

More
Information
Reassign
Ad-hoc
Select the menu from which to derive user names for the corresponding operations. The selected menu
determines the list of users that appears when a user creates a More Information request (by adding a question or
comment), or chooses to reassign a request, or to assign a request to an ad hoc approver. If you do not specify a
menu for any of these operations, users do not have the option of choosing names from a user list; they can
continue with the operation by entering login names manually.
Rejection Justification
Require
Justification
on
Rejection
Justification
Field
Select Yes to make it mandatory for an approver to provide a justification when rejecting a request. In addition to
storing the justification in various approval server fields, it is pushed to the application form's field specified in the
Justification Field menu. Select No to indicate that rejection justification is optional; an approver is not prompted to
justify rejecting a request. However, if provided, the justification is processed further.
Select the field in which to store the rejection justification. This menu lists Character fields from the application
form.
Note: Currently, this menu also displays Attachment fields along with Character fields, because of an AR System
server issue.
From the list of available fields, select a Character field whose length is unrestricted (0 ). Otherwise, if the approver
enters a justification of more than 255 characters:* A warning is added to the approval log.
The justification is not made available on the application form.
If you do not select a field from this menu, the approver's input is stored in the Justification field (ID 14518) on AP:
Signature and as a comment of the Justification type on AP:Question-Comment-Info. See AP-Rejection
Justification form.
Signature Escalations tabs

AP:Process Definition form Signature Escalations (Normal) tab
Page 1829 of 4705
Home
The three tabs (Normal, Urgent, and Low) on the Signature Escalation tab contain identical fields.
Fields on the AP:Process Definition form Signature Escalations tabs
Field
Description
Use schedules
Business
Use the drop-down list to select a workday schedule created on one of the business time workday forms.
calendar
Holiday
calendar
Use the drop-down list to select a holiday schedule created on one of the business time holiday forms.
Automatic action
After
Interval
Type a numeric value for the amount of time to pass before this action is taken. For example, type a 2 for two hours or
two days. The unit is determined in the next field.
Note: This is called the Automatic Action interval, which is used to compute the action date for the corresponding
process.
Unit
Select the unit of Hours or Days as the unit for the interval in the previous field.
Change
State
Use the drop-down list to select the status you want to force on this request if no activity occurs in the interval defined
in the two preceding fields. Leave this field and the preceding two empty if you do not want the status of a request
changed automatically.
Note: This reflects on AP:Show-Detail > Action Date field and Approval Central > Action Date column. See
AP-Show-Detail form and Approval Central.
Notification: Still Outstanding and Notification: Still in State are used to determine the escalation or notification mechanism for
signatures on a request.
Use these fields to send a notification to an approver whose signature is in Pending or Hold state for a specified interval.
First
Interval
Type a numeric value for the amount of time to pass before this notification first occurs.
Note: This is one of the Escalation intervals, which is used to compute the action date for the corresponding process.
Unit
Select the unit of Hours or Days for the interval in the previous field.
Note: This reflects on Approval Central > Past Due requests > Action Date column. See Approval Central.
Repeat
Interval
Type a numeric value for the amount of time to pass before this notification recurs. For example, type a 2 for two
hours or two days. The unit is determined in the next field.
Unit
Notification: Still in State

Use these fields to send a notification to an approver for signatures in an active state.
On State
Set the separate escalation and repeat intervals to occur when a form is saved with the status of Pending, Error, Hold,
or More Information.
First
Interval
Page 1830 of 4705
Home
Type a numeric value for the amount of time to pass before this notification first occurs. For example, type a 2 for two
Note: This is one of the Escalation intervals, which is used to compute the action date for the corresponding process.
Unit
Repeat
Interval
Type a numeric value for the amount of time to pass before this notification recurs. For example, type a 2 for two
Unit
More Information Escalations tab

You can use the fields on this tab to send a notification to the addressee of the More Information
request.
AP:Process Definition form More Information Escalations tab
Fields on the AP:Process Definition form More Information Escalations tab

Field
Description
Use schedules
Business
calendar
Use the drop-down list to select a workday schedule created on one of the business time workday forms.
Holiday
calendar
Use the drop-down list to select a holiday schedule created on one of the business time holiday forms.
Notification: still outstanding

First
interval
Type a numeric value for the amount of time to pass before this action first occurs. For example, type a 2 for two
Unit
Repeat
interval
Type a numeric value for the amount of time to pass before this action recurs. For example, type a 2 for two hours
or two days. The unit is determined in the next field.
Unit
Page 1831 of 4705
Home
For more information about the Administrative Information tab, see Administrative Information tab.
AP-Question-Comment-Info form
The approval server uses this form internally to store additional information that requestors and
approvers provide about requests.
The following table describes the data stored in this form and the source of that data.
Records in the AP:Question-Comment-Info form
Record
type
Source field
Question
Stores text from the Question field on AP:Show-Detail or AP:More Information.
Comment
Stores text from the Summary field on AP:Show-Detail or the Comment field (if added) on the application form. If
you add an activity log entry of the Justification type on AP:Show-Detail, text from the Summary field is also stored
here. Attachments associated with comments are stored in the attachments table adjacent to this field.
Justification
Stores text from the Justification For Action field on AP:Show-Detail or Approval Central. If the Justification For
Action field and its appropriate workflow is added to the application form or the three-way join form, the
corresponding text is stored here.
This form also stores the text from the following sources:
Form
Field
AP:More Information
Response
AP:Show-Detail
Response
Notes
Application form
Notes (if added with the appropriate workflow)
AP-Reserved Word form

Process administrators use this form to create keywords and functions for approval processes.
AP:Reserved Word form
Fields on the AP:Reserved Word form
Page 1832 of 4705
Home
Field
Description
Name
Type the word you want to reserve.
Name Type
Click the option button to select whether the word is a keyword or function.
Assignee Group Permissions
Select the name of the special control group for you want to have row-level permissions.
AP-Role form
This form opens when you click View or Create on the Role tab of AP:Administration. Process
administrators use this form to create role definitions for approval processes. See Defining roles.
AP:Role form Role Information tab
Fields on the AP:Role form Role Information tab
Field
Description
Role Name
Type the name for this role.
If Multiple
Approvers
Select one of the options:

One must sign A single signature entry is created for all individuals in the Member List field. Only one
individual needs to take action.
All must sign Separate signature entries are created for all individuals in the Member List field. All
individuals must take action for the request to move forward.
This field is valid only if more than one entry exists in the Member List field.
Status
Use the drop-down list to select the status of this role.

Active This role can be used by any approval process.
Inactive This role is disabled for all approval processes.
Page 1833 of 4705
Home
Member List
Type the AR System user name for each person who is a member of this role. Use a semicolon (:) as a separator
between names.
AP-Rule Definition form

This form opens when you click View or Create on the Rule tab of AP:Administration.
Basic tab
AP:Rule Definition form Basic tab
Process administrators use this form to create and modify rules for approval processes. See Using
the Rule tab on AP-Administration.
Fields on the AP:Rule Definition form Basic tab
Field
Description
Definition
Rule Name
Type a name for this rule. The name of a rule can be as long as 254 characters in English and most European
languages, but only 127 characters in double-byte languages.
For
Process
Use the drop-down list to select a process for this rule.
Process
Instance ID
The BMC Remedy AR System automatically populates this field with the GUID of the process.
Rule Type
Use the drop-down list to select the rule type. See Defining approval rules
Order
Type a number to determine execution order for this rule. Larger numbers execute after smaller numbers. Rules
with the same number in this field execute in an unpredictable order.
Status
Use the drop-down list to select the status of this rule.
If Multiple
Results
Use the drop-down list to select the behavior when multiple results are found.
Value from First The approval server uses the value from the first record retrieved.
Page 1834 of 4705
Home
Values from All The approval server uses all of the values retrieved.
Return Error The approval server produces an error message if more than one record is retrieved.
If Multiple
Approvers

One Must Sign A single signature entry is created for all approvers. Only one of those approvers needs
to take action on the request.
All Must Sign Separate signature entries are created for all approvers. All approvers must act on the
request for it to move to the next stage.
Next
Approver
Rule Is
Use the drop-down list to select the behavior when multiple Get Next Approver rules exist.
Additive This rule appends approvers to the existing approver list, and further rules are processed.
Ending This rule appends additional approvers to the existing approver list, but no further rules are
processed.
Exclusive This rule assigns the approver list, and no further rules are processed. If a previous rule
created an approver list, the process ignores it.
This field is usually used for a Rule-Based process that has a set of Get Next Approver rules to build an approver
list.
Assignee
Group
Permissions
multi-tenancy feature. See Error 333 and Assignee Group Permission.
Qualification
Run if
This field label appears for the following rule types:

Get Authority
Get Authority Regular
Get Authority Self
Get Next Approver
Parameterized Get Next Approval Rule
Prep Get Next Approver
Signature Accumulator
Statistical Override
Validate Approver
Enter the qualification in the Run If field. Use the buttons and drop-down list to help. See Using the Rule tab on
AP-Administration. In addition, you can dynamically define the search criteria by using the EXTERNAL keyword.
When using the EXTERNAL keyword, make sure you see fields using single quotes instead of dollar signs, for
example:
'Submitter' = "John"
Otherwise, if you enter:
$Submitter$ = "John"
the value from the current transaction will be returned: "John" = "John"
Rule
This field label appears for the following rule types:

Auto Approval
Self Approval
Completion Rule
Page 1835 of 4705
Home
Enter the qualification in the Rule field. Use the buttons and drop-down list to help. See Using the Rule tab on
AP-Administration. In addition, you can dynamically define the search criteria by using the EXTERNAL keyword.
When using the EXTERNAL keyword, make sure you see fields using single quotes instead of dollar signs, for
example:
the value from the current transaction will be returned: "John" = "John"
Audit text
This field appears for Auto Approval and Self Approval rules. Type the text you want to appear in the permanent
record for the request whenever this rule executes. Use the drop-down list to select keywords to include in your
audit trail message.
Rule State
This field label appears for Approval Process Done rules. Select one or more rule conditions from among the radio
buttons. The options are:
Approved
Rejected
Cancelled
Error
The rule executes when the approval detail record moves to the selected state.
Guaranteed
Add
Yes The parameterized rule runs even when a Completion rule would otherwise determine that the
process is done, thus guaranteeing that the user will be added as an approver.
No (Default) If a Completion rule determines that the conditions exist for the process to be done, the
process does not return to the Get Next Approver stage to run this rule.
Search
In Search mode, click this button to perform your search.
Save
Close
Set Fields tab

The Set Fields tab appears only when you select a rule type for which you can specify a Run If
qualification and the subsequent Set Fields actions.
AP:Rule Definition form Set Fields tab
Page 1836 of 4705
Home
Fields on the AP:Rule Definition form Set Fields tab

Field
Description
Set Fields
Type
Select an item from the drop-down list to specify how the rule should populate this field type. The options are:
Value, Query, SQL, Process, and Other.
From Form
For a query, select the name of the form that contains the data to retrieve.
On Server
Use the drop-down list to select the server that contains the form.
Current Select this option if the form resides on the same server as the approval server.
Alternate Select this option if the form resides on another server.
Server
Type the name of the server that holds the form. This field is available only when the On Server field contains the
value Alternate.
Separator
string
Type the letters, numbers, or symbols to use when separating multiple entries set in the same field. This field is
disabled with some options available in the Set Field Type field.
Qualification
Query builder
buttons
The Fields from Set Fields Form, Fields from Application Form, and other SQL keywords and operator buttons are
available for use only when you select a Set Fields type other than Value. For example, choosing SQL causes
Select, From, Where, and the comma separator ( , ) buttons to appear so that you can construct SQL statements
easily.
SQL
Command /
Qualification
Type a qualification or use the other fields to select functions or keywords. You can dynamically define the search
criteria by using the EXTERNAL keyword. When using the EXTERNAL keyword, make sure you see fields using
single quotes instead of dollar signs, for example:
then the value from the current transaction is returned:
"John" = "John"
Fields data
Field name
Page 1837 of 4705
Home
Type a field name or use the drop-down list to select a field name. The Field Name field is disabled with some
options available in the Set Field Type field. One rule can populate more than one field by using separate lines for
Field Name and Value.
Value
Type the value or use the drop-down list to select a value to populate the field. The Value field is disabled for
some Set Field types. One rule can populate more than one field by using separate lines for Field Name and
Value.
AP-Signature form
This form stores the signature lines for approval requests. Administrators can use this form to
review the responses to a request. However, you should modify this information only through
Approval Central.
AP:Signature form
Fields on the AP:Signature form

Field
Description
Approval ID
The BMC Remedy AR System populates this field with the AR System ID for this request.
Approvers
The BMC Remedy AR System populates this field with the name of the approver for this signature line.
More
Information
The BMC Remedy AR System populates this field with the questions and answers to More Information
Requests.
Approval
Status
The BMC Remedy AR System populates this field with the status of the request.
Next Approver
The BMC Remedy AR System populates this field in an ad hoc situation with the name of the next approver.
If Multiple
Approvers
This field is valid only if multiple entries exist in the Next Approver field. Select one of the options:
One Must Sign A single signature entry is created for all approvers in the Next Approver field. Only
one of those approvers needs to take action on the request.
All Must Sign Separate signature entries are created for all approvers in the Next Approver field. All
approvers must act on the request for it to move to the next stage.
Page 1838 of 4705
Home
Field
Description
Alternate
Signature
The BMC Remedy AR System populates this field with the user name of an alternate approver, if the alternate
acts on the request.
Approver
Signature
The BMC Remedy AR System populates this field with the user name of the approver when the approver acts
on the request.
Signature
Method
The BMC Remedy AR System populates this field with the method by which this request was approved.
Alternate An alternate signed this request instead of a normally scheduled approver.
Regular A normally scheduled approver signed this request.
Override Someone with process administration authority performed an override to respond to this
request instead of a normally scheduled approver.
Assignee Group
Permissions
Full Name
Used to store the full names of approvers to whom the corresponding request is assigned.
Role ID
Used to make a signature role aware. For more information, see Creating signature escalations.
The approval server automatically drops duplicate signature lines if an approver appears in multiple
groups to which a request is assigned or if there are duplicate individual mappings.
In such an event, entries such as the following are recorded in the approval log:
<APPR> * Process option set to not validate user so no work needed

<APPR> Expanding roles for approver(s): SGP000000000082|CAB-Member
<APPR> Expanding roles for approver(s): SGP000000000084|CAB-Member
APPR> Dropping duplicate approver line for USER1;USER2;USER3;
<APPR> Dropping duplicate approver line for USER1;USER2;USER3;
You can safely ignore such log entries. The signature lines are dropped because the approval
server maintains only one signature line for an approver per request until the associated process is
active.
Full Name
The approval server uses the login name to search for the corresponding full name when creating a
signature entry. It first searches the User forms, and if they do not full name information is not
present, it searches the custom form specified on the AP:Process Definition form. This information
is stored in the Full Name character field (14201). See Full name form.
If there is no custom Full Name Form, or if the full name information is not found through this form,
the login name is used as default.
Setting the full name on a signature line is a one-time activity; this value is not set at run time. The
full name provided at the time of signature line creation stays constant. When upgrading to release
7.5.00 or later, if the Full Name value is not available, it is set according to the current Full Name
Page 1839 of 4705
Home
value from the related form. If the Full Name value must be set dynamically, application developers
must write the appropriate escalations. Applications can fetch user information from different forms,
such as the User form, the CTM:People form, and so on.
Role ID
If a signature is created by expanding a role, the Role ID character field (14200) stores the role ID
of the source role, which was expanded to create the individual signature line. The following
situations could occur:
If a role has One Must Sign set to true, only one signature entry is created for all the
members belonging to the role. The related role ID is copied to the Role ID character field.
If a role has All Must Sign set to true, the role ID is copied to each signature entry that is
created by expanding the role.
Depending on the process definition, the signature entries are created as follows:
When One Must Sign is defined at the process level, only one signature entry is created,
regardless of the If Multiple Approvers setting at the role level. In this case, the individuals
defined as approvers and the individuals expanded from the roles provided as approvers
appear in a single signature entry. Role IDs for all the roles in the approvers list are put in
the newly added field on the AP:Signature form for the corresponding signature.
When All Must Sign is defined at the process level, multiple signatures are created according
to the If Multiple Approvers setting at the role level. In this case, each signature entry
contains the role ID that was responsible for creating the entry by expanding the individuals
in the role.
The values in the Role ID field could differ as follows:
The Role ID field remains blank for individuals in the approvers list.
The Role ID field can have a single role ID or multiple roles IDs based on the definitions. All
role IDs are enclosed between semicolons.
Consider a case where a role is defined as an approver, which in turn is composed of roles.
When this is expanded recursively to write individuals in the signature entry, the Role ID field
has the role ID of the base role that was provided as the approver.
For example: The Finance role contains the users Jim and Frank. The Purchase role
contains the users Paul and Bob. The Administrator role is a superset of Finance, Purchase,
and a few more roles. When the Administrator role is defined as an approver for a request,
even though it expands the Finance, Purchase, and other roles recursively to get individual
approvers, the Role ID fields of the signatures created for these approvers contains the role
ID of the Administrator role.
User forms
User forms are used by submitters, approvers, process administrators, and so on.
This section contains information about these user forms:
Page 1840 of 4705
Home
Approval Central
AP-AdhocDialog form
AP-Alternate form
AP-Dtl-Sig-MoreInfoDialog form
AP-More Information form
AP-Password form
AP-Reassign form
AP-Rejection Justification form
AP-Show-Detail form
AP-ShowDetail-DeleteVerify form
AR System Business Time forms
Approval Central
The Approval Central form, which acts as the approval server console, appears when you log in to
BMC Remedy AR System and click the Approval Central link on the home page. This link is
localized.
Tip
The localized link is visible only if the Localize Server option is enabled on the Advanced
tab of the AR System Administration: Server Information form. See Setting performance
and security options.
Note
The Approval Central view is not supported on 7.0.01 or earlier versions of AR System
clients. When Approval Central is opened in version 7.0.01 of BMC Remedy Mid Tier, a
warning message is displayed and the counts against the links in the left pane are not
displayed.
Approvers use Approval Central to respond to approval requests, and to access request details.
Requesters use it to access More Information requests sent to them. See Processing approval
requests.
Approval Central enables you to quickly review the approval requests awaiting your attention.
These could be direct requests or requests for which you act as an alternate approver. You can
approve, reject, hold, or view the details of a pending request by using the appropriate buttons
provided in the form. You can act on single or multiple requests at one time without opening each
request individually.
Page 1841 of 4705
Home
You can reassign a pending request only if the Can Reassign option for the corresponding approval
process is set to Yes in AP:Process Definition.
When you open Approval Central, the Pending Approvals table appears by default, and it displays
requests that have the Pending, Hold, or More Information status.
The left pane contains two sections: Summary and Actions. Clicking a link in these sections
displays a corresponding panel in the right pane.
Summary
The links in this section correspond to pre-defined searches. A table in the corresponding panel on
the right displays the search results. See Approval Search Result table.
Fields on Approval Central Summary section
Field
Description
Pending
Approvals
Click to view the requests that await your approval. Such requests are in the Pending state. The following links are
displayed under the Pending Approval link:
Needs Attention
Past Due
Due Soon
For more information, see Pending Approvals table.
Needs
Attention
Click to view the requests for which a question or answer is directed at you. Such requests are in the More
Information state. The Need Attention Approvals panel displays a table with the columns: From, To, Action Date,
Description, Application, Request, and Status.
Past Due
Click to view the requests whose Action Date has passed. The Past Due Approvals table displays requests having the
Pending, Hold, or More Information status. For more information about the Action Date, see step 5 and step 6 of the
To enter signature escalations section.
Due Soon
Click to view the requests whose Action Date is approaching. The Due Soon Approvals table displays requests having
the Pending, Hold, or More Information status. A Process Administrator configures, through AP:Administration, the
time factor that decides whether an approval request falls under the Due Soon category. For more information, see
step 5 of the To enter signature escalations section.
My
Approval
History
Click to view the requests that you approved or rejected, and requests that have the Error status. This is a pre-defined
search, the results of which appear on the right pane in the My Approvals History table. Requests displayed in this
table have the Approved, Rejected, or Error status. A Process Administrator configures the number of history items to
display. See AP-Admin-ServerSettings form. The Rejected by Others link is displayed under My Approval History.
Rejected
by Others
Click to view the requests that you approved earlier, but are rejected by an approver further in the approval sequence.
This is a pre-defined search, the results of which appear on the right pane in the Approvals Rejected by Others panel.
Approval requests that need attention

When you click the Needs Attention link in the Summary section of the left pane, a table of
questions and answers posted to you appears in the right pane.
Page 1842 of 4705
Home
The table contains the columns: From, To, Action Date, Application, Request, and Status, which
display the corresponding information for each request.
You can perform one of the following actions on any selected request in this table:
Click Respond to answer the corresponding question. The AP:More Information form opens
in Modify mode.
Click View to open the corresponding question-answer thread. The AP:More Information
form opens in Display mode.
After you respond to a question or view the answer to a question you raised, the state of the
request changes from More Information to Pending.
Actions
Field on Approval Central Actions section
Field
Description
My Alternate
Approvers
Click this link to open the AP:Alternate form in New mode. For more information, see AP-Alternate form.
The right pane displays the appropriate panels when you click the link in the Summary or the
Actions sections in the left pane. You can expand or collapse these panels using the arrow icon
next to the panel title.
Pending Approvals table

In the right pane, the Pending Approval table displays requests with the Pending, Hold, and More
Information, status.
Some rows might have a bell icon displayed in the first untitled column, indicating that the
corresponding request is Urgent.
The second untitled column contains check boxes that you can use to select the corresponding
requests. Use the check boxes to select multiple requests on which you want to perform similar
actions or use the check box in the table header to select all the requests.
Clicking on a row without using the corresponding check box, will select that row and deselect
everything else. To select or deselect all the requests in this table, select the check box in the table
header. See Working with multiple pending requests.
Note
Page 1843 of 4705
Home
When you click Approve, Reject, or Hold, the status of the selected requests
changes. These modified requests continue to appear in the Pending Approvals
table until the table is refreshed, or until you navigate to another page or link.
When you click a row-level icon without explicitly selecting the row, the row gets
selected first. To execute any row-level action, the row must be selected first.
Fields on Approval Central Approval Search Result table

Field
Description
Action Date
The date on or before which, if you do not act upon the request, either you receive a notification that it is still
outstanding, or the state of the request is changed automatically. This is applicable only to those requests where
Notification:Still Outstanding, or Automatic Action, or both are configured in the corresponding AP:Process
Definition form. The Action Date is calculated as the least of these two values, if both are specified. See Signature
Escalations tabs and step 5 of the To enter signature escalations section.
Summary
The description associated with the Request ID (Application ID). This value is populated from field 14506 on AP:
Detail that contains the Description value for the associated application request. When you hover over this field, a
tool tip displays the information mapped in the Tooltip Configuration tab of AP:Form. This additional information
helps you take a quick decision about the request.
Note
This tool tip appears only if the appropriate setting is done on the Tooltip Configuration tab of AP:Form.
See AP:Form form.
Requester
The name of the requestor. This information is obtained from the three-way join form for the related application.
Acting As
The name of the approver to whom the request is originally assigned. This field contains a value only if you are the
alternate approver for the original request assignee.
Priority
The priority of the approval request that is stored in the corresponding AP:Detail record. The possible values are:
Urgent, Normal, and Low.
Application
The application name associated with the request. For example: SRM, Change Management. This name is
provided by the application itself.
Status
The current state of the request. The possible values are: Pending, Approved, Rejected, Cancelled, Hold, More
Information, Error, and Closed.
Approve
icon
Click to approve the selected request.
Reject icon
Click to reject the selected request. If rejection justification is mandatory, but the Justification For Action field is
empty, a dialog box prompts you to enter a reason for rejecting the request. See Rejection justification for approval
requests.
Hold icon
Click to put the selected request on hold.

In case of approval generated by a Process Designer process, the Hold option is not supported for SRM and
Change requests.
Page 1844 of 4705
Home
Reassign
icon
Click to reassign the selected request to another person. If Can Reassign is set to Yes for the corresponding
process, the AP:Reassign dialog box prompts you to enter the name of an approver; otherwise an error is displayed
. For more information, see Reassigning approval requests.
In case of approval generated by a Process Designer process, the Reassign option is not supported for Service
Request Management (SRM) and Change requests.
Note
The AP:Reassign dialog box appears only once, which means that all the selected requests are assigned
to the same person. Validation for the user name entered in the dialog box is not provided out-of-the-box.
Approval
Details icon
Click to open the AP:Show-Detail form, which displays the details of the highlighted approval request and enables
you to take further action.
Note
When you click the Approval Details icon on the Approval Central form, if the AP:Show-Detail form does
not load the sequence diagram, the following error message appears: Error during loading
document
To fix the issue, perform the following steps:
1. Open the Visualizer Module Registration form.
2. Click Search.
3. Select the BMC Remedy Approval Server record that has an attachment of the Approval_0.jar file.
4. Delete the attachment and add the Approval_0.jar file again.
5. Restart BMC Remedy Mid Tier
6. Stop the running Apache Tomcat service.
7. From the BMC Remedy Mid Tier Install folder, delete the contents in the PluginCache folder.
8. Start the Tomcat service and open the Approval Central form.
9. Select a request and click the Approval Details icon.
You can see the sequence diagram without errors.
For more information, see Working with request details.

View
Questions
and
Responses
icon
Click to display all the questions and responses, if any, for the selected request. If there is no question for the
selected request, the following pop-up message is displayed:
Preferences
Click to set the preferences to display items in this table. You can choose to display or hide a column, set the
refresh interval, and reset or save the display settings.
Refresh
Click to refresh the contents of the table.
Justification
For Action
Enter some meaningful text in this field to be recorded as a justification for your action, and click Reject. An entry is
added to the Activity Log table. If you click any other action button, this field is ignored. For information about how
No Questions Present
your input is processed, see Rejection justification for approval requests.
Page 1845 of 4705
Home
Approval Search
Enables you to specify criteria for searching through approval requests. Select or enter field values
in this section of the form to search for requests and display the results in the Search Results table.
Approval search on Approval Central
Quick search
Select an approval status from the Show list to search for requests with the selected status. The
default status is Pending. After you select a value for this field, the Search Results table is
refreshed.
To filter your search results further, you can enter a search string in the text box, and click the
Search icon. The approval server finds all the requests with the selected status, that also contain
any of the specified words in a field, instead of matching a string of characters. This search action
tries to match the search string to the data present for the Summary, Application, and the
Requestor fields for the requests.
Advanced search
You can also use Advanced Search to specify a detailed search criteria.
Note
When you enable Advanced Search, the quick search is disabled.
Fields on Approval Central Approval Search section

Field
Description
Application
Select an application from the list of available applications. Select the name of the approval request form from the list
to search for approval requests related to that form.
Process
Select a process. If you select an application, only the processes belonging to that application appear in this menu.
Acting As
Page 1846 of 4705
Home
Select a value from the list to search for requests with the selected type of approver authority. The default is Myself.
If you choose All and perform a search, the resulting list contains the same requests that appear when you click the
Pending Approvals link.
Note
The Acting As field cannot be blank.
User
Contains the name of the current user or the user on whose behalf you are acting as alternate or performing an
override.
If Acting As is set to Myself or Global Override, BMC Remedy AR System populates this field with the name
of the current user.
If Acting As is set to Alternate or Override, you must enter the AR System name of the user for whom you are
acting as an alternate, or performing an override.
Approval
Status
Select an approval status from the list to search for requests with the selected status. The default is Pending.
Requester
Type all or part of a requester's BMC Remedy AR System full name to search for approval requests from that
requester. The search results display the requests created by this requester only if you have the correct privileges on
the corresponding requests.
Summary
Enter one or more words in the summary that you want to search for.
Action
Date
Select the Action Date. See Signature Escalations tabs and step 5 of the To enter signature escalations section.
Priority
Select the priority. This is the priority of the approval request and not that of the application request.
Modified
Date
Select the date on which the requests you want to search for were last modified.
Search
Click to perform the search after you specify all the required criteria.
Clear All
Click to clear all the search fields.
Request-ID
Type the Request ID to search for approval requests.
Approval Search Result table

The Approval Search Result table is displayed in the right pane. The contents of the table change
according to the links you click in the left pane, or the advanced search criteria.
Some rows might have a bell icon displayed in the first untitled column, indicating that the
corresponding request is Urgent.
The second untitled column contains check boxes that you can use to select the corresponding
requests. Use the check boxes to select multiple requests on which you want to perform similar
actions.
Page 1847 of 4705
Home
Clicking on a row without using the corresponding check box selects that row and deselect
everything else. To select or deselect all the requests in this table, select the check box in the table
header. See Working with multiple pending requests.
Note
When you click Approve, Reject, or Hold, the status of the selected requests changes.
These modified requests continue to appear in the Pending Approvals table until the table
is refreshed, or until you navigate to another page or link.
Fields on Approval Central Approval Search Result table

Field
Description
Action Date
The date on or before which, if you do not act upon the request, either you receive a notification that it is still
outstanding, or the state of the request is changed automatically. This is applicable only to those requests where
Notification:Still Outstanding, or Automatic Action, or both are configured in the corresponding AP:Process
Definition form. The Action Date is calculated as the least of these two values, if both are specified. See Signature
Escalations tabs and step 5 of the To enter signature escalations section.
Summary
The description associated with the Request ID (Application ID). This value is populated from field 14506 on AP:
Detail that contains the Description value for the associated application request. When you hover over this field, a
tool tip displays the information mapped in the Tooltip Configuration tab of AP:Form. This additional information
helps you make decisions about the request.
Note
This tool tip appears only if the appropriate setting is done on the Tooltip Configuration tab of AP:Form.
See AP:Form form.
Requester
The name of the requestor. This information is obtained from the three-way join form for the related application.
Acting As
The name of the approver to whom the request is originally assigned. This field contains a value only if you are the
alternate approver for the original request assignee.
Priority
The priority of the approval request that is stored in the corresponding AP:Detail record. The possible values are:
Urgent, Normal, and Low.
Application
The application name associated with the request. For example: SRM, Change Management. This name is
provided by the application itself.
Status
The current state of the request. The possible values are: Pending, Approved, Rejected, Cancelled, Hold, More
Information, Error, and Closed.
Approve
icon
Click to approve the selected request.
Reject icon
Click to reject the selected request. If rejection justification is mandatory, but the Justification For Action field is
empty, a dialog box prompts you to enter a reason for rejecting the request. See Rejection justification for approval
requests.
Page 1848 of 4705
Home
Hold icon
Click to put the selected request on hold.
Reassign
icon
Click to reassign the selected request to another person. If Can Reassign is set to Yes for the corresponding
process, the AP:Reassign dialog box prompts you to enter the name of an approver; otherwise an error is displayed
. For more information, see Reassigning approval requests.
Note
The AP:Reassign dialog box appears only once, which means that all the selected requests are assigned
to the same person. Validation for the user name entered in the dialog box is not provided out-of-the-box.
Approval
Details icon
Click to open the AP:Show-Detail form, which displays the details of the highlighted approval request and enables
you to take further action. For more information, see Working with request details.
View
Questions
and
Responses
icon
Click to display all the questions and responses, if any, for the selected request. If there are no questions for the
selected request, the following pop-up message is displayed:
Preferences
Justification
For Action
No Questions Present
your input is processed, see Rejection justification for approval requests.
Working with multiple pending requests

To select a single row in the Approval Requests table, click anywhere on the row; its check box is
selected and those of other rows are unselected. To select multiple requests, use the
corresponding check boxes. To select all the requests in this table, select the check box in the table
header. However, at a time only one row appears highlighted (regardless of the status of its check
box).
Note
Multiple row selection does not work for requests of the Needs Attention category.
You can now select multiple requests and change the status. When you click the appropriate action
button, a guide runs through the individual requests and performs the actions. If one or more of the
associated processes require passwords, you are prompted to provide them once, before the
action is performed.
Setting display preferences on Approval Central

Use the Preferences menu to set display preferences for the tables on this screen as follows:
Add Column Use to select a column to be displayed.
Remove Column Use to select a column to be hidden.
Page 1849 of 4705
Home
Set Refresh Interval Click to open a dialog box that allows you to specify the duration (in
minutes) after which the table is automatically refreshed.
Reset Click to revert any changes you made to the appearance of the table, or the refresh
interval.
Save Click to save any changes you made to the appearance of the table or the refresh
interval. These changes are saved only for the current session and are not persistent, which
means they are not retained when you log out and log in again.
Action buttons
You can select one or more requests on Approval Central and click the appropriate buttons to
perform the desired actions. The buttons are disabled only if there are no requests to be selected.
Selecting one or more requests enables all the action buttons regardless of the status of the
request. If a certain action can not be performed on a selected request, one of the following occurs:
Clicking the action button has no effect. For example, if you select a request that is on hold,
clicking the Hold button will have no effect.
Clicking the action button displays an error message and the request remains unchanged.
For example, if you select an request with the Approved, Rejected, or Error status and click
either Approve, Reject, Hold, or Reassign, the following error message is displayed:
Select atleast one row with appropriate status to perform the buttonLabelaction. (
ARERR errorNumber)
Action buttons to operate on selected requests
Field
Description
Approve
Selected
Click to approve the selected requests. If other approvers are required, BMC Remedy AR System routes the
requests to the respective next approvers. If no further approvers are required, the request statuses change to
Approved, and the approval process is done.
Reject
Selected
Click to reject the selected requests. If rejection justification is mandatory, but the Justification For Action
field is empty, a dialog box prompts you to enter a reason for rejecting the request. The same comment is
applied to all the selected requests. See Rejection justification for approval requests.
Hold
Selected
Click to put the selected requests on hold. The request statuses change to Hold until any further action is
performed on them.
Request Details
The Request Details section displays all the data related to an approval request. This data is
fetched from the AP:Show-Detail form. For more information, see AP:Show-Detail form.
For information about the approval request details, see AP:Detail form.
Fields on Approval Central Request Details section
Field
Description
Page 1850 of 4705
Home
Request
ID
Displays the application ID (the request ID or any other ID in the application) as a link. Click the link to display the
relevant application form.
Note
If you upgrade from an earlier version of the BMC Remedy Approval Server to 7.5.00 or later, this link displays
the correct application ID for newly created requests. The application ID might not be accurate for requests
that were created before upgrading. To specify the value for this link, the process administrator must map the
Application Request ID field on the Advanced tab of AP:Form to the appropriate field on the application form
. See AP:Form form.
Activity
Log
Displays the activity log (Questions, Comments, and other information) associated with the Request ID. Click View
Activity Summary to view all the activities related to the current request in a report format.
When you click any of the Approve, Reject, or Hold, or Reassign icons, a dialog box prompts you
to enter your password. The statuses of the selected requests are changed only if you provide a
valid password, otherwise an error message is displayed.
More Information
The More Information section enables you to add questions or comments to the current request in a
table.
More Information section on Approval Central
To modify or delete questions or comments associated with the current request, you must go to the
Activity Log tab on the AP:Show-Detail form.
For more information, see Activity Log tab.
Fields on Approval Central More Information section
Field
Description
Type
This drop-down list enables you to specify whether you are creating a comment or a question.
Question
To
Select a name from the user list or enter the AR System login name of the person to whom you want to raise a
question. This field is enabled only if you select Question from the Type drop-down list. Using the Question To field,
an approver can ask questions to the requestor or any other person who belongs to the same group as the approver.
Note
Page 1851 of 4705
Home
The approval server does not have any way to know where a particular user's details are stored. (The
consuming applications are responsible to validate the login name.) The source of a user could be any form
other than the User form that the BMC Remedy AR System provides, for example, the user information
could be retrieved from an LDAP server.
Question
/
Summary
This field is labeled as Question when you choose to add a question to the approval request; enter the question here.
It is labeled as Summary when you choose to add a comment; enter the brief comment here.
Response
/ Notes
This field is labeled as Response when you view a question about the approval request; the corresponding response
appears here. It is labeled as Notes when you choose to add a comment; enter the detailed comment here.
Save
Click to save a new comment or question.
AP-AdhocDialog form
This form appears when you click the Adhoc button on the AP:Show-Detail form for a request. The
appearance of this dialog box is dependent on the value of the Ad Hoc Settings field on the AP:
Process Definition form; it appears only if the Default option is selected. However, if the process
administrator selects the User Defined option, the custom dialog box for the corresponding form is
displayed.
The AP:AdhocDialog form shows the list of existing ad hoc approvers, if any, and enables you to
add to or remove from this list. If the table contains multiple rows, the first row is selected by default
.
AP:AdhocDialog form
Fields on the AP:AdhocDialog form

Field
Description
Name
Select a name from the user list or enter the name of a new ad hoc approver. You can also specify multiple ad hoc
approvers by typing their names separated by semicolons. If you select a row in the following table, the
corresponding approver name appears in this field, but you can modify and save it.
Sequence
Enter or modify the sequence at which to add the ad hoc approver. The default is 1.
If Multiple
Approvers
Page 1852 of 4705
Home
One Must Sign Only one signature entry is created. If you specified multiple approvers, only one of them
needs to take action on this request.
All Must Sign A separate signature entry is created for each approver in the Name field. All of them must
take action on the request for it to move to the next stage.
Independent
Select one of the options.

Yes Indicates to the approval server that the request can proceed to the next level of its process without
waiting for the signature of the current ad hoc approver.
No Indicates to the approval server that the current ad hoc approver's signature is required before the
request can proceed to the next level of its process.
Preferences
Note
This menu is available on the mid tier only.
Refresh
Click to refresh the contents of this table.
Note
This field is available on the mid tier only.
Add
Click to add a new ad hoc approver, after you enter appropriate values in the fields.
Modify
Select a row that you have not yet saved, and click to modify the details of the corresponding ad hoc approver.
Note
This button remains disabled when you select rows that have already been saved.
Delete
Select one or more rows using the corresponding check box and click to delete the association of the
corresponding ad hoc approvers with the current request.
Save
Select one or more rows using the corresponding check box and click to save the new ad hoc approvers to the AP:
AdhocDetails form.
Note
Even though a row is added to the table, it is not saved until you explicitly select it and click Save.
Close
Click to close the dialog box; if there are any unsaved records in the table, you can confirm whether to return to the
dialog box and save them or ignore them and close the dialog box. If you make any changes to the list of ad hoc
approvers, the contents of the Approver tab reflect the same.
Note
Page 1853 of 4705
Home
After you add an ad hoc approver at the current level and save the record (the data is
saved in the AP:AdhocDetails form), you cannot modify it. If you need to make changes,
delete the existing ad hoc approver record and create a new one. You can modify the
record of an ad hoc approver who is assigned for a future level.
AP-Alternate form
Approvers use this form to create, delete, maintain, and search alternate approvers to take action
on their behalf. However, they are not permitted to define alternate approvers for anyone other than
themselves.
Alternate Information tab

AP:Alternate form Alternate Information tab
Fields on the AP:Alternate form Alternate Information tab

Field
Description
Alternate
Type the AR System user name of the person who is to act as alternate.
For
BMC Remedy AR System automatically populates this field with the user name of the current user.
Note
Only an administrator has write permission for this field.
Start Date
Open the calendar control and select the date and time when the alternate's authority begins.
End Date
Open the calendar control and select the date and time when the alternate's authority ends.
Notify Alternate
Select whether the alternate is notified when a request comes to the original approver.
Yes notifies the alternate when a request is pending.
No does not notify the alternate.
To notify alternates, the process administrator must perform the following tasks:
1. Create notifications on the New Signature notify on event.
2. Select Enabled Including Alternate on the AP:Admin-Server Settings form.
Page 1854 of 4705
Home
Select a value to identify which processes are included in this alternate's authority.
Covering
All This alternate has authority to approve all processes for which the original approver has
authority.
Specific Process This alternate has authority for only the process specified in the Process field.
Process
If you selected Specific Process, select the process for which the alternate has authority.
Process Instance
ID
BMC Remedy AR System automatically enters the GUID of the process selected in the Process field.
Status
BMC Remedy AR System automatically completes this field based on the server's current date and time.
Future This alternate is not yet active.
Current The alternate is presently active.
Past The alternate is no longer active.
Cancelled The alternate record has been cancelled and the alternate is not active.
Search
In Search mode, searches the AP:Alternate form.
Save
Save changes and entries to the form.
Close
Close the window without making any changes.
Administrative Information tab

AP:Alternate form Administrative Information tab
Fields on the AP:Alternate form Administrative Information tab

Field
Description
Alternate ID
BMC Remedy AR System populates this field with an AR System ID for this record.
Create Date
BMC Remedy AR System populates this field with the date this alternate was created.
Assigned To
Type the name of the original approver assigning authority to this alternate. The default is the current user.
Help Text
Type information to aid users who are setting up alternates.
Change
history
Type any additional information to be recorded with the alternate assignment. This information becomes part of
the permanent record for this alternate.
Last Modified
By
BMC Remedy AR System populates this field with the name of the person who last modified this alternate.
BMC Remedy AR System populates this field with the date of the last modification to this alternate.
Page 1855 of 4705
Home
Last Modified
Date
AP-Dtl-Sig-MoreInfoDialog form
This form appears when you click More Information on the AP:Detail-Signature form, or Manage
More Information on the three-way join forms in the sample applications. When opened, it is
populated with a list of More Information requests related to the current approval request.
AP:Dtl-Sig-MoreInfoDialog form
Fields on the AP:Dtl-Sig-MoreInfoDialog form

Field
Description
Existing More
Information records
This field displays any More Information records attached to the current approval process.
Preferences
Click to set the preferences to display items in this table. You can choose to display or hide a column, set
the refresh interval, and reset or save the display settings.
Refresh
Refreshes the list.
New Record
Opens the AP:More Information form in New mode, where you can create a new More Information
request.
Open
Opens the selected item in list.
Close
Close the form.
AP-More Information form

This form contains More Information requests. It opens when you click New Record or Open on the
AP:Dtl-Sig-MoreInfoDialog form.
AP:More Information form
Page 1856 of 4705
Home
Fields on the AP:More Information form

Field
Description
To
Select the recipient's name from the menu, or enter the recipient's AR System user name. You can not select or
enter multiple names in this field. The user names in this drop-down list are determined by the menu specified in
the process definition. For more information, see AP-Process Definition form.
From
AR System user name of the sender of the More Information request. This field is read-only after the record is
saved.
More Info
Status
Status of the More Information request.
Application
The application to which the request belongs.
Request
Request ID of the request.
Question
The question pertaining to the More Information request.
Response
Response to question about the More Information request.
Assignee
Group
multi-tenancy feature.
Permission
AP-Password form
This form appears when an approver clicks Approve, Reject, or Reassign on Approval Central for a
request whose process requires a password. An approver must enter the correct AR System user
password and click Submit. If the password in authenticated, the request status is changed.
Otherwise, an authentication error is displayed and no action is taken on the request.
Fields on the AP:Password form
Field
Description
Submit
Enter the correct password to approve or reject the request, and click to submit the password for authentication. If
authenticated, an Approve or Reject action occurs. If not authenticated, BMC Remedy AR System returns an
authentication error.
Cancel
Click to close the dialog box without submitting the password. No action is taken on the request.
AP-Reassign form
This form appears when an approver selects one or more approval requests on Approval Central or
opens the AP:Show-Detail form for a record, and clicks Reassign.
Page 1857 of 4705
Home
Select a name from the user list or enter the precise AR System login name of the approver to
whom you want to reassign the request, and click OK.
If the requests you selected belong to different processes, each of which have a different menu
configuration for the user list, the user list pertaining to the first request is displayed. To choose
from the appropriate user list for a request, work with a single request at a time.
Click Cancel to close the dialog box without performing any action on the request.
AP-Rejection Justification form

This form appears when an approver selects one or more approval requests on Approval Central or
opens the AP:Show-Detail form and clicks Reject without entering some text in the Justification For
Action field.
The approver can perform the following actions:
Enter the justification for rejecting the request, and click OK.
When rejecting multiple requests simultaneously, the dialog box appears only once. The
same comment is added to the activity log of all the selected requests.
Click Cancel to close the dialog box without providing a comment.
If the process mandates rejection justification, the Reject action is skipped and a message to
that effect is displayed. The request remains in the Pending state.
AP-Show-Detail form
The AP:Show-Detail form displays all the data related to an approval request. This data is fetched
from the AP:Detail form.
For more information, see AP-Detail form.
AP:Show-Detail form Approver tab with multi-process preview
Page 1858 of 4705
Home
The P-C Phase, P-C GL Account, P-C Cost Center, and P-C Total Cost are generic character fields
, which application developers can use to show additional character data. The labels of these fields
can also be changed dynamically so that the labels are in sync with the values. These labels are
localized.
Note
Localized labels are visible only if the Localize Server option is enabled on the Advanced
tab of the AR System Administration: Server Information form. See Setting performance
and security options.
The Action Date field indicates the duration after which the state of the approval request is changed
automatically or a notification is sent to the relevant approver to act on the same. This occurs only if
it is so defined in the process. For more information, see AP-Process Definition form and Creating
signature escalations.
You can use this form to perform the following operations:
View a history of activities on a request for any approval process in the form of a table or a
flowchart.
Add or remove ad hoc approvers to the approval chain.
Add and view questions, comments, notes, and attachments for further information.
Fields on the AP:Show-Detail form
Page 1859 of 4705
Home
Field
Description
Approver
tab
Displays the approval process preview for the current request as a flowchart or a table.
Activity
Log tab
Displays the list of questions and comments associated with the current request in a table. You can also add or delete
questions and comments.
Approve
Click to approve the current request.
Reject
Click to reject the current request.
Reassign
Click to reassign the current request to another person. If Can Reassign is set to Yes for the corresponding process, a
dialog box prompts you to enter the name of an approver; otherwise an error is displayed.
Hold
Click to put the current request on hold.
Adhoc
Click to add ad hoc approvers to the approval chain or remove existing ad hoc approvers for the selected requests.
The table or flowchart in the Approver tab is updated accordingly. The Adhoc button is disabled in the following
conditions:
Ad Hoc Settings are not defined for the associated process.
The request is in the Process Done stage.
If the Default option is selected for the Ad Hoc Settings of a process, the AP:AdhocDialog appears for the
corresponding request. See AP-AdhocDialog form.
Close
Click to close the AP:Show-Detail form.
When you click any of the Approve, Reject, Reassign, Hold, or Adhoc buttons, a dialog box
prompts you to enter your password. The request status is changed, or the AP:AdhocDialog form is
displayed, only if you provide a valid password, otherwise an error is displayed.
Approver tab
This tab displays a preview of the processes through which the current request might traverse until
it reaches the Completion Check stage.
Fields on the AP:Show-Detail form Approver tab
Field
Description
Preview
Type:
Current
Process
Only
Click to see a preview of how the current request might traverse through the current approval process. This preview
is generated after the process begins (when the detail and signature records for the current request have been
created).
Preview
Type:
Multiple
Processes
Click to see a flowchart or tabular view of the path the current request might traverse when it pertains to multiple
View As:
Sequence
Diagram
Click to see a flowchart view of the current approval request. See Sequence diagram.
processes. This view appears only when the Generate-Multi-Process-Preview application command is executed,
whose input values determine the what appears in the view. See Using the multi-process preview.
Page 1860 of 4705
Home
View As:
Table
Click to see a tabular view of the current approval request. See Table.
Zoom
Click the icon to see an enlarged flowchart view in a new window.
Note
This button is available only when viewing the Sequence Diagram.
Refresh
Click to refresh the contents of this tab.
Note
This button is provided because the mid tier does not allow the use of the F5 key (Windows) to refresh the
contents of the current screen.
A legend at the bottom of this tab indicates the meaning of the status icons attached to each
signature in the preview.
Note
When the AP:Show-Detail form is viewed through versions earlier than 7.5.00 of BMC
Remedy Mid Tier, the Preview Type option on the Approver tab is unavailable (disabled).
Sequence diagram
The sequence diagram is a flowchart representation of the approval chain for the current request. If
you add or remove an ad hoc approver, or perform any other action on the request, it is reflected in
the flowchart immediately. If an approver name is not available, the flowchart displays empty blocks
in its place. The flowchart displays only valid approvers.
The flowchart view is localized. Its elements can be displayed in all languages available with BMC
Remedy AR System.
Note
Localized data is visible only if the Localize Server option is enabled on the Advanced tab
of the AR System Administration: Server Information form. See Setting performance and
security options].
Page 1861 of 4705
Home
The flowchart view is available out-of-the-box on the AP:Show-Detail form, which has two related
active links, namely, the AP:Show-Detail-LoadObject and AP:Show-Detail-HandleEvent forms.
To display a customized flowchart view on your own form, you need:
A Data Visualization Field (DVF) pointing to the Visualizer module.
Two active links that accept three input values, namely, application request ID, application
form name, and detail ID. Providing the detail ID is optional.
Note
The DVF cannot be seen using Firefox 2.0.0.11 on Mac 10.4.11. This is an issue with the
browser.
The flowchart view is backward compatible with BMC Remedy Mid Tier releases 7.1.00 and 7.0.01.
You can use BMC Remedy Mid Tier to see the flowchart view for an approval request.
Note
When the AR System server has encryption enabled (Premium Security or Performance
Security), the multi-process preview flowchart might take longer to load.
Table
The table depicts the approval sequence. If you add or remove an ad hoc approver, or perform any
other action on the request, it is reflected in the flowchart immediately.
Activity Log tab
AP:Show-Detail Activity Log tab
Page 1862 of 4705
Home
Fields on the AP:Show-Detail form Activity Log tab

Field
Description
Refresh
Click to refresh the contents of this tab.
Justification
For Action
your input is processed, see Rejection justification for approval requests. After you enter text in this field and click
Reject, the entry might not appear in the Activity Log table. However, the activity is recorded and the corresponding
entry is visible when the request is opened again in the AP:Show-Detail form.
Note
Like the Comment and Question options, you cannot use the Justification option to create a justification to
the approval request. Even though you select Justification from the Type drop-down list, Comment is
selected. This is because, the Justification option is used to display existing justifications for the rejected
requests.
Activity Log
Details
This section enables you to add, modify, and delete comments, questions, notes, and attachments to the current
request.
Type
This drop-down list enables you to specify whether you are creating a comment or a question.
Question
To
Select a name from the user list or enter the AR System login name of the person to whom you want to raise a
question. This field is enabled only if you select Question from the Type drop-down list. Using the Question To field,
an approver can ask questions to the requestor or any other person who belongs to the same group as the approver
.
Note
The approval server does not have any means to know where a particular user's details are stored. (The
consuming applications are responsible to validate the login name.) The source of a user could be any
form other than the User form that BMC Remedy AR System provides, for example, the user information
could be retrieved from an LDAP server.
Question /
Summary
This field is labeled as Question when you choose to add a question to the approval request; enter the question
here. It is labeled as Summary when you choose to add a comment. Enter the brief comment here.
Page 1863 of 4705
Home
Response /
Notes
This field is labeled as Response when you view a question about the approval request; the corresponding
response appears here. It is labeled as Notes when you choose to add a comment. Enter the detailed comment
here.
Attachment
Use this field to add an attachment along with your comment. Only one attachment is allowed per comment. If you
view a comment that has an attachment associated with it this table field displays the file name, size, and label for
the same. Note that attachments cannot be associated with questions. This field is disabled when you select
Questions from the Type drop-down list.
Submitter
Displays the name of the submitter.
Submit
Date
Displays the date and time of submission.
Add
Click to add a comment or question to the approval request. This field is enabled only if you have the necessary
permissions.
Save
Click to save a new comment or question.
Cancel
Click to cancel any new comment or question that you were trying to add to the current request.
Delete
Click to delete the selected comment or question.
Right click anywhere in this tab to open the Preferences context menu. This menu enables you to
refresh the contents of the table, add or remove columns from the view, set the refresh interval, and
reset or save the changes you make to the table.
Comments
This feature enables submitters (requestor and approvers) to include comments and attachments
for an approval request. These could be useful as additional information for the next approver in the
chain.
Approvers can work with comments in the following ways using this form:
Add or delete their own comments, and view the comments included by other approvers.
Include an attachment at the time of creating a comment. They can also modify or delete the
attachments associated with their own comments.
Edit or delete comments of other approvers if they are the Alternate Approvers or
Administrators. Approvers other than these can only view the corresponding details.
Requestors can work with comments in the following ways:
Provide a comment with an attachment through the application form. The workflow on the
Activity Log checks the respective application form for the requestor's comment on the
selected approval request. If a comment is available, it displays the comment in the Activity
Log table.
Modify or delete comments they created. If the requestor modifies a comment or its
attachment, or both, the Activity Log displays the modified details whenever an approver
invokes the Activity Log (or refreshes the table).
Questions
Page 1864 of 4705
Home
This feature enables approvers to ask questions about an approval request to requestors and other
approvers. These answers could be useful as clarifications to the current and future approvers in
the chain.
Approvers can work with questions in the following ways using this form:
Add, modify, and delete their own questions, and view the questions raised by other
approvers.
Edit or delete questions raised by other approvers if they are the Alternate Approvers or
Administrators. Approvers other than these can only view the corresponding details.
Requestors can work with questions in the following ways:
Cannot create a question because the Activity Log, which is invoked from Approval Central,
is available only to approvers. A requester does not have access to the Activity Log.
Provide the response to a question through the More Information form.
The Questions feature works as follows:
An approver can raise a question to any user of the system (or application). If the
notifications are configured, the respective user receives a notification. The user then clicks
the Response button in the Request Details section of Approval Central to open the AP:
MoreInformation form for the request.
An approver can raise only one question at a time per request because, when a question is
created, the status of the request is changed to More Information. After a requestor or
approver responds to the question, the request is again assigned the Pending status.
Approvers can modify or delete the questions they raised before the addressees respond to
them. No notification is sent in this case.
The question details in the table are associated with the Approval ID, Signature ID, and a
Question ID.
Questions cannot be redirected.
Every question can be associated with only one answer.
AP-ShowDetail-DeleteVerify form
This form appears when an approver tries to delete an Activity Log entry in the AP:Show-Detail
form. The entry could be a question, comment, or justification that the approver created.
You can delete only one entry at a time. You cannot delete entries created by the requestor or
other approvers.
Click Yes to delete the entry for the request. The corresponding record in the AP:
Question-Comment-Info form is deleted.
Click No to close the form without deleting the entry.
Page 1865 of 4705
Home
AR System Business Time forms

Process administrators use the following AR System forms to determine the business hours and
holidays to be used by approval processes and other AR System workflow:
See Using the old Business Time forms .
Running the approval utilities

You can run the following approval utilities by running the approval-utils.bat (Windows) or
approval-utils.sh (UNIX) file:
Approval Join Fix - joinfix (See Running the Approval Join Fix utility )
Approval Change Schema - chgschema (See Approval Change Schema utility)
Approval Upgrade - upgrade (See Overview of the Approval upgrade utility )
To run the approval utilities

1. Open the approval-utils.bat or approval-utils.sh file in the approvalServerInstallDir\bin
directory.
2. The interface prompts as follows:
Approval Utility Commands

===========================
Exit/Quit
<e | q>
Help
<h | help>
Approval Join Fix

Approval Change Schema
Approval Upgrade
<joinfix>
<chgschema>
<upgrade>
Command:
3. Type the name of the utility that you want to run.

a. If you type joinfix, and press enter, the interface displays the parameters for the
utility and prompts the user to enter the required arguments as follows:
Info - Created command - joinfix

Approval Join Fix
Usage:
[-x Server]
[-u User]
[-a Authentication String] [-r RPC Port]
[-f Form]
Page 1866 of 4705
Home
[-m Mode]
1. Update Join Criteria
2. Add new fields in Three-way Join Form
3. Update Password Objects on Three-way Join Form
Arguments:
b. If you type chgschema, and press enter, the interface displays the parameters for the
Info - Created command - chgschema

Approval Change Schema
Usage:
[-x Server]
[-u User]
[-r RPC Port] [-a Authentication String]
Arguments:
c. If you type upgrade, and press enter, the interface displays the parameters for the
Info - Created command - upgrade

Approval Upgrade
Usage:
[-d Installation Directory]
[-l Log File Path]
Arguments:
Note
The logs for the chgschema and joinfix utilities are stored in the
approval-utils.log file located in the approvalServerInstallDir\bin directory.
The log for the upgrade utility is stored in the log file as per the -l parameter.
However, if the value for this parameter is not specified, then the logs are stored in
the approval-utils.log file.
After running the utilities, you must restart the approval server for the changes to
take effect.
Page 1867 of 4705
Home
Setting up DSO to synchronize data across

BMC Remedy Distributed Server Option (DSO) enables you to transfer requests between servers
and to keep copies of a request synchronized across multiple servers, even if those servers are
geographically dispersed. DSO is available for Windows and UNIX platforms.
Before using DSO, you should be familiar with BMC Remedy AR System.
DSO has many uses, including the following:
Transferring requests to the location where they are processed
For example, suppose your company repairs office furniture. Desks are repaired in San
Francisco, and chairs are repaired in Chicago. When a request for a chair repair is submitted
to the San Francisco site, DSO can automatically transfer the request to a server in Chicago.
If the request needs the attention of a specialist, such as an upholsterer, DSO can transfer
the request to a different Chicago server that handles upholstery repairs.
Transferring requests between regions in a customer support environment that operates 24
hours a day, 7 days a week
You can configure DSO to forward open requests to another site at the end of each site's
business day. For example, suppose your company has customer support centers in San
Francisco, Paris, and Tokyo. DSO can forward open requests from San Francisco to Tokyo
at the end of San Francisco's business day, from Tokyo to Paris at the end of Tokyo's
business day, and so on. This helps alleviate employee down time and increases the speed
at which requests are processed.
Important
Depending on your environment, using DSO as a database synchronization engine
might not provide real-time distribution of all data to all users. Before you
implement DSO for this use, your environment should be evaluated to ensure that
DSO can perform as expected in it.
Creating a distributed knowledge base so that problem-solving information is accessible from

any location
For example, you can create filters or escalations that instruct DSO to forward requests
closed on one server to all other servers in the environment. All servers then have access to
the problem-solving information and solutions contained in the closed requests.
Archiving old requests
If you have a server dedicated to archiving, DSO can send closed requests to the that server
.
Page 1868 of 4705
Home

Distributed operations introduction
Distributed operations components
Implementing DSO
Distributed operations scenarios
Chained and broadcast distributed transfers
Distributed Server Administration program
Managing request IDs in distributed environments
Overwriting all fields in duplicate requests
Distributed operations introduction

With the add-on product BMC Remedy Distributed Server Option (DSO), you can deploy BMC
Remedy AR System in a distributed architecture, with multiple AR System servers installed at
different locations, each with its own database instance. This allows you to use each server
independently, and since each server is located close to its user base, the users do not experience
a network lag. This distributed setup can be used for serving a globally dispersed user base, and
also for setting up a separate instance for backup or reporting purposes.
You can use DSO to perform the following distributed operations:
Distributed transfers
Distributed updates
Distributed returns
Distributed deletes
Distributed transfers
A distributed transfer sends information from a source form on one server to a target form on
another server or on the same server. You configure a distributed transfer by defining a distributed
mapping (see Distributed mapping) and by creating workflow to perform the transfer (see Creating
workflow to perform DSO operations). Then, when a request is created or modified in the source
form, that action can trigger the workflow to create a copy of the request and transfer it to the target
form. The transfer can include all or some of the data in the request.
The following figure shows the basic flow of a distributed transfer. (The request in the darker form
has ownership after the operation is completed.) For an example of how to set up a distributed
transfer, see Distributed transfer scenario.
Distributed transfer flow
Page 1869 of 4705
Home
Stages of a distributed transfer

The stages of a distributed transfer are listed in the following table:
Stages of a distributed transfer

Stage
DSO server action
Gets a list of pending items to process from the distributed pending queue. The list includes details about each operation.
For information about the distributed pending queue, see Managing pending distributed operations.
Identifies the next pending item to process from the list obtained in stage 0.
Gets the definition of the source form associated with the pending item.
Gets detailed information about the request to transfer, which is identified by the request ID in the Source ID field of the
pending item.
Gets the definition of the distributed mapping associated with the pending item.
Verifies that it can implement the mapping.
Gets the definition of the target form associated with the pending item.
Transfers the request from the source form to the target form.
Page 1870 of 4705
Home
Stage
DSO server action

After the transfer operation is complete, updates information about the status of the operation in the request identified by
the Source ID field of the pending item.
The other types of distributed operations updates, returns, and deletes use a subset of these
stages.
To track these stages, use the DSO logs (see Configuring BMC Remedy Distributed Server Option
logging).
Request ownership chains

To modify a request, users must own it. Typically, ownership is transferred with a request.
When ownership is transferred with a request, an ownership chain is created. The ownership chain
begins with the copy of the request that has ownership also called the master copy (see the
definition for Master Flag in Distributed fields) and extends back through all copies of the
request from which ownership was transferred.
For example, a request on the sanfrancisco server must be resolved on the chicago server.
Therefore, you transfer the request with ownership to chicago so that chicago users can modify
the request as necessary. Depending on your workflow configuration, sanfrancisco users might
receive notice of changes made to the request on the chicago server through a distributed update
operation. But sanfrancisco users cannot modify their copy of the request unless the request is
returned with ownership through a distributed return operation.
Note
For information about mapping chains, see Setting up chained distributed transfers.
Types of distributed transfers

DSO can perform the following types of distributed transfers.
Types of distributed transfers
Type of
transfer
Data Only
Copy of request in target form

Holds
ownership
?
Is in
ownership
chain?
Can be
modified
?
No
No
No
Description
Typically used for archiving. Because data-only copies cannot hold

ownership, they cannot start ownership chains.
Data +
Ownership
Yes
Yes
Yes
Considered the master copy. Modifications made to this copy can be

automatically made to all other copies of the request in the ownership chain
(see Distributed updates).
Page 1871 of 4705
Home
Independent
Copy
Yes
No
Yes
Cannot receive updates from the master copy because independent copies
are outside the ownership chain. Independent copies can start new
ownership chains.
Copy +
Delete
Yes
No
Yes
Transfers an independent copy of a request to the target server and then

deletes the original request.
Dynamic data, such as an entry in a defect-tracking form, is often modified at the site to which it is
transferred. Use a Data + Ownership operation to transfer this type of data.
Static data, such as customer biographical information, is typically not modified at the site to which
it is transferred. Use a Data Only or Independent Copy operation to transfer this type of data.
Distributed updates
A distributed update keeps all copies of a request in an ownership chain synchronized with the
master copy (the request with ownership). Modified information in the master request is
automatically sent to other requests in the chain at a specified time interval: daily, hourly,
immediately, or whenever ownership of the request is returned.
For example, suppose you have a broken keyboard. You submit a replacement request on the
sanfrancisco server. Because the chicago server handles office equipment replacements, the
sanfrancisco server uses a Data + Ownership distributed transfer to send the request to the
chicago server. This creates an ownership chain between the sanfrancsico and chicago copies
of the request. After the keyboard is replaced, the status of the master request on the chicago
server is changed to Completed. Because the distributed mapping between the forms is configured
to update the other copies in the ownership chain immediately, this change triggers the DSO to
update the status of the copy on the sanfrancisco server.
Consider the following factors when deciding whether distributed updates are required:
When distributed transfers occur between two forms whose requests are static, the copy on
the source server probably does not need to be updated because the master request does
not change after it is transferred. For example, Data Only and Independent Copy transfers
usually fit this criteria.
If users at the target site modify the master request and users at the source site need those
modifications, copies in the ownership chain should be updated. For example, Data +
Ownership transfers usually fit this criteria.
The following figure shows the basic flow of a distributed update. (The request in the darker form
has ownership after the operation is completed.)
Distributed update flow
Page 1872 of 4705
Home
For an example of how to set up a distributed update, see Distributed update scenario.
Distributed returns
A distributed return is used to send an updated request back to the originating server with
ownership. Distributed returns are triggered by workflow on the server that returns the request.
For example, after the keyboard is replaced in the preceding example, the status of the master
request on the chicago server is changed to Completed. When this change occurs, workflow is
triggered and the modified request is transferred back to the sanfrancisco server with ownership,
leaving a data-only copy of the request on the chicago server. The request can now be modified
on the sanfrancisco server if necessary.
The following figure shows the basic flow of a distributed return. (The request in the darker form
has ownership after the operation is completed.)
Distributed return flow
Page 1873 of 4705
Home
For an example of how to set up a distributed return, see Distributed return scenario.
Distributed deletes
A distributed delete deletes copies of a request.
Warning
If the master copy in an ownership chain is deleted, all copies of the request in the
ownership chain are deleted. See Request ownership chains.
Additional delete capabilities enable you to delete specific requests, including data-only requests.
You must specify a separate filter or escalation action to run the distributed delete process for each
copy of the request.
For example, an employee submits a phone repair request on the sanfrancisco server. Because
telecommunication services are handled by the chicago server, a Data + Ownership distributed
transfer sends the request to the chicago server, creating an ownership chain between the
sanfrancsico and chicago servers.
Page 1874 of 4705
Home
Later, the employee discovers that his phone is unplugged, not broken, and calls the support center
to cancel the repair request. Instead of changing the status of the request to Completed, the
support person changes the status to Canceled. This change triggers previously configured
workflow to execute a distributed delete operation, which deletes the master request on the
chicago server and the copy of the request on the sanfrancisco server.
For an example of how to set up a distributed delete, see Distributed delete scenario.

This section contains information about configuring distributed operations using these elements:
Distributed mapping
Distributed logical mapping
Distributed fields
Distributed pools
Distributed mapping
Distributed mapping defines how data is transferred from one form to another, how frequently
distributed updates are processed, and how conflicts in distributed operations are resolved.
Distributed mapping is typically used to link two fields with matching field IDs or field names
between forms. You can also create custom distributed mapping that links nonmatching fields or
that links a single field to multiple fields. Distributed mappings are server objects. They are created
in the Distributed Mapping editor, and they are stored in the Distributed Mapping form.
Distributed Mapping editor
Configuring a distributed mapping to transfer data between identical forms is a simple process. To
transfer data between nonmatching forms, however, you must:
Determine which fields in the source form should be mapped to fields in the target form.
Consider the results of mapping fields containing different data types. For example, the data
types must be compatible, such as strings and integers.
Page 1875 of 4705
Home
Consider the results of mapping fields of unequal size. For example, if the length of a source
field exceeds the length of a target field, the distributed operation results in an error.
To ensure that BMC Remedy AR System uses the type of mapping appropriate for each situation,
you can create multiple mappings between forms. Then, when creating the filter or escalation that
triggers a distributed operation, you can specify which mapping to use or let the system select a
default mapping. See Creating distributed mappings.
You can also override settings in a mapping for a particular distributed operation. See Overriding
mapping settings on a per-request basis .

You can now configure distributed mappings by using temporary server names. Distributed logical
mapping is used to define the mapping between logical (temporary) and physical (actual) server
names. These mappings are created and stored in the Distributed Logical Mapping form. At run
time, the DSO replaces the logical server name with the physical server name in accordance with
the mappings in this form. While moving the distributed mappings (or workflow) from the
development environment to the production environment, this feature eliminates the need to
manually replace the server names in any distributed mapping. Now you only need to replace the
physical server name in the Distributed Logical Mapping form. You can use logical server names in
DSO actions as well.
For example, in the development environment, you create a logical mapping with the logical server
name as destination_server, physical server name as dev_server, and use the logical server
name in a distributed mapping. While moving the distributed mapping to the production
environment, you only need to replace the physical server name with the actual production server
name in the Distributed Logical Mapping form.
With the custom mapping option, you can also use distributed logical mapping to assign a logical (
temporary) constant string value for fields whose actual value is not known while developing the
distributed mappings. At run time, DSO replaces the logical constant string with actual value from
the Distributed Logical Mapping form.
In distributed mapping, a logical name (server name or constant string value) must be enclosed in
the dollar symbol ($).
Note
If a constant string from a custom mapping in an existing distributed mapping is enclosed
in the dollar symbol ($), you must prefix the dollar symbol with the caret symbol (^), which
acts as an escape character. Without this, the constant string is treated as a logical string
and DSO replaces it with an actual value from the logical mapping form.
Page 1876 of 4705
Home
Distributed fields
To manage ownership-based transfers, you must add distributed fields to the forms involved in the
transfers.
You can also override much of a mapping definition by assigning values to the distributed fields. At
runtime, DSO uses any such values in the source form's distributed fields to overwrite
corresponding values in the mapping definition.
The following groups of distributed fields provide different levels of control over distributed
mappings:
Full distributed fields
Advanced distributed fields
If you archive a form that contains distributed fields, the distributed fields are copied to the archived
form, but they are not updated after being archived.
You cannot add distributed fields to an archived form.
Basic distributed fields

Basic distributed fields are required for transfers with ownership (see Request ownership chains).
They hold information used by operations that transfer, return, and update requests. For example, if
you want to know where a request came from, you can review the information in the From Form
and From Server fields.
The data in all basic distributed fields is system-generated (DSO sets the values). Several are
protected and can be overwritten only by using the ardist program (see Distributed Server
Administration program).
Basic distributed fields
Field
Description
name
Transfer
Status
Displays one of these values after a transfer is attempted:

Success The operation succeeded.
Retry The operation failed, but it is still pending. The failure was caused by a situation that might correct
itself (such as a time out or a shutdown server). The operation is retried as follows:
Every 5 minutes for the first 30 minutes
Every 30 minutes after the first 30 minutes for up to 24 hours
Every hour after the first 24 hours
Failure The operation failed, was deleted, and will not be retried.
Timeout The operation was retried until the retry time expired. See Retries.
Canceled The operation was deleted from the pending table before it was processed.
You can use this field to examine the results of distributed operations, set up filters to detect failures, and set up
escalations to detect distribution problems.
Displays one of these values after an update or a return is attempted:
Page 1877 of 4705
Home
Update
Status
Success See the preceding field description.

Waiting The update is waiting for the next transfer time shown in the When to Update field. This status is
not used for immediate mappings.
Retry See the preceding field description.
Failure See the preceding field description.
Timeout See the preceding field description.
Canceled See the preceding field description.
You can use this field to examine the results of distributed operations, set up filters to detect failures, and set up
escalations to detect distribution problems.
Master
Indicates whether a request holds ownership. (The copy of a request that has ownership is called the master copy.)
Flag
From
Request
ID
Specifies the ID of the request in the source (From) form.
From
Form
Specifies the form from which a request was transferred. Also called the source form.
From
Server
Specifies the server from which a request was transferred. Also called the source server.
From
Pool
Specifies the distributed pool on the source (From) server that processed the distributed operation.

The full distributed fields group includes the basic fields. It also includes fields that provide greater
control over mapping selection when a possible conflict between mappings exists (see How
distributed mapping is selected).
In addition, this group of fields stores mapping history information. For example, if you want to know
where a request was transferred, you can review the To Mapping, To Form, and To Server fields.
Developers set some of these fields, and DSO sets others.
Field
name
Description
To
Mapping
Tells DSO which mapping to use when transferring the request. If the mapping specified in this field does not exist or
is disabled, the distributed operation fails.
From
Mapping
Specifies the mapping that was used during a transfer to create this request. Only DSO can set the value of this field.
To
Request
ID
Specifies the ID of the request to which the data was transferred. Only DSO can set the value of this field.
To Form
Specifies the form to which the request should be transferred. If this field and the To Server field are set, DSO looks
for a mapping based on their values. If no mapping to the specified form exists, the distributed operation fails. Also
called the target form.
Page 1878 of 4705
Home
To
Server
Specifies the server to which the request should be transferred. If this field and the To Form field are set, DSO looks
for a mapping based on their values. If no mapping to the specified server exists, the distributed operation fails. Also
called the target server.
Mapping
History
Contains a history-tracking record created at the time of transfer. The record includes the date and time of transfer, the
source request ID, the source form, the source server, and the name of the specific mapping used. The result is a
record of all transfers to this request. Only DSO can set the value of this field.
Note: By default, this is an unlimited-length character field. If you set a maximum length for this field, records might be
truncated.
Current
Form
Specifies the form in which the master copy of the request resides. Only DSO can set the value of this field.
Current
Server
Specifies the server on which the form with the master copy of the request resides. Only DSO can set the value of this
field.

The advanced distributed fields group includes the basic and full fields. Values entered in an
advanced distributed field override the corresponding setting in the mapping used in a distributed
operation.
For example, to change the method of distributed transfers from Data Only to Data + Ownership for
a particular distributed operation, you can use workflow to modify the Transfer Mode distributed
field. See Creating workflow to perform DSO operations.
Field name
Description
When to
Update
Specifies the frequency with which to update the original request if a transferred copy is updated. See When to
Update.
Transfer Mode
Specifies the type of transfer to perform. Valid transfer types are Data Only, Data + Ownership, Independent
Copy, and Copy + Delete. See Types of distributed transfers.
Duplicate
Request ID
Action
Specifies the action that occurs if you transfer a request and the To form already contains a request with the
Max Time to
Specifies the maximum times a distributed operation is retried before the system cancels the operation. See
Retries.
Retry
same request ID. See Duplicate Request ID Action.
Enforce
Pattern
Matching
Specifies whether to enforce patterns defined in fields on the target form during distributed operations. See
Enforce Pattern Matching.
Require
Required
Fields
Specifies 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. See Require Required Fields.
Matching
Specifies the qualification to use to match a source request with a request in the target form. See Default
distributed pool.
Qualification
For more information, see #Adding distributed fields to forms.
Page 1879 of 4705
Home
Overriding mapping settings on a per-request basis

Sometimes you must change a setting in a distributed mapping to satisfy the requirements of a
particular distributed operation. To enable this, perform these tasks:
Add the advanced distributed fields to the form that will be the source form in the distributed
operation. (See Adding distributed fields to forms.)
The names of the advanced distributed fields match the names of the fields in the Options
panel of the Distributed Mapping editor with the exception of Max Time to Retry, which is
called Retries in the editor (see Distributed Mapping editor). On the source form, these fields
accept the same values as their counterparts in the editor.
Create workflow to update the appropriate advanced distributed fields on the source form
when you submit or modify a request in that form.
The values that the workflow adds to the fields on the source form override the values set in
the editor when the mapping was created.
For example, you might have a mapping whose transfer mode is Data Only, but for one transfer
performed by that mapping, you need to send data and ownership. To do this, you would add
advanced distributed fields to the transfer's source form and then use workflow to set the Transfer
Mode field in the appropriate request to Data + Ownership.
Distributed pools
DSO uses distributed pools to process multiple distributed operations at the same time. This
simultaneous processing minimizes delays and significantly increases the output of distributed
operations when DSO activity is heavy.
Distributed pools are server objects. They are created in the Distributed Pool editor, and they are
stored in the Distributed Pool form.
After defining a pool, you must associate DSO filter or escalation actions with the pool (see
Creating workflow to perform DSO operations).
Pending distributed operations in a pool are queued and then executed in the order received (FIFO:
first in, first out). Therefore, when setting up pools, consider the interdependencies between the
forms in an application. All distributed operations associated with one form and all distributed
operations on interdependent forms should use the same pool to ensure that the operations are
executed in the correct order.
You can use different pools for unrelated distributed operations or when sending data-only or
independent copies of requests to different destinations. For example, suppose your system is
experiencing heavy distributed activity, and multiple data-only or independent copy transfers are
pending from different applications. Because these operations do not need to be completed in a
particular order, you can assign them to different pools.
Page 1880 of 4705
Home
Default distributed pool

You can designate one pool as the default pool or use the system default pool. If you do not create
any distributed pools or if you assign a pending distributed operation to a nonexistent pool, the
operation is handled by the default pool.
See Enabling distributed pools.
Implementing DSO
This section contains information about working with distributed fields, mappings, and pools. It also
explains how to administer data transfers between forms.
Adding distributed fields to join forms
Creating workflow to perform DSO operations
Enabling distributed fields
Enabling distributed mappings
Enabling distributed pools
Enabling logical mappings
Managing pending distributed operations
Performing distributed operations on join forms
Setting up distributed operations
To configure BMC Remedy Distributed Server Option (DSO), you need the appropriate permissions
. See Access control.
Adding distributed fields to join forms

Distributed fields are reserved fields. Join forms can contain only one instance of each reserved
field. If both forms underlying a join form contain distributed fields, you can add the distributed fields
from only one of those forms to the join form. This means that any runtime changes to a distributed
request based on the join form are applied only from the distributed fields on one of its underlying
forms.
For more information, see Enabling distributed fields and Reserved fields.
Creating workflow to perform DSO operations

This section contains information about configuring the following actions when creating a filter or an
escalation for a distributed operation:
Configuring DSO Transfer actions
Configuring DSO Return actions
Configuring DSO Delete actions
Configuring DSO Transfer actions

Use distributed transfers to transfer a request from one form to another.
Page 1881 of 4705
Home
To perform a distributed transfer operation, you must create a distributed mapping (see Creating
distributed mappings) plus a filter or an escalation with a DSO Transfer action on the source server.
To configure a DSO Transfer action

1. Create a filter or escalation (see Workflow objects).
2. In the Associated Forms panel of the Filter or Escalation editor, add the form designated as
the From form in the distributed mapping that you plan to use for this transfer.
3. In the Execution Options panel, select the filter trigger criteria.
Typically, the trigger criteria for distributed transfers is Modify or Submit.
4. Right-click the If Actions panel, and select Add Action > DSO.
5. In the Type list, select Transfer.
6. Fill in these fields:
Mapping The mapping to use for the transfer. Enter a mapping by clicking the
ellipsis button next to this field and then using the Object Selector.
This field enables you to use one filter or escalation to "broadcast" the same request
to multiple destinations by specifying different mappings in separate filter actions. See
Setting up broadcast distributed transfers.
You can enter a field reference or keyword in the Mapping field, but do not add any
text after the field reference or keyword. (The system removes the additional text.)
Distributed Pool The pool to use to process the action.
The Object Selector allows you to select either the distributed pools or the field from
which you want to source the pool name.
To select a distributed pool, you must first create a distributed pool. See Distributed
pools and Enabling distributed pools.
Warning
To ensure that DSO actions are executed in the correct order, assign all
related DSO actions to the same distributed pool. For example, all DSO
actions associated with the same form should use the same distributed pool.
To Server The physical name or the logical name of the target server for the
transfer.
Note
Logical server names appear in the list enclosed in the dollar sign.
Page 1882 of 4705
Home
If you specify a value in the Mapping field, this field is ignored.

If you do not specify a value in the Mapping field, DSO uses this value and the value
in the To Form field to determine which mapping to use.
To Form The name of the target form for the transfer.
If you specify a value in the Mapping field, this field is ignored.
If you do not specify a value in the Mapping field, DSO uses this value and the value
in the To Server field to determine which mapping to use.
7. (Optional) Select Override Loop Detection. See Avoiding infinite loops.
Configuring DSO Return actions

Use distributed returns to request the return of ownership from the form where ownership was
transferred. See Distributed returns.
To perform a distributed return operation, you must create a distributed mapping plus a filter or
escalation with a DSO Transfer action on the source server. On the target server, you must create
a compatible distributed mapping plus a filter or escalation with a DSO Return action.
To configure a DSO Return action

2. In the Execution Options panel of the Filter or Escalation editor, select the trigger criteria.
4. In the Type list, select Return.
5. To assign the DSO action to a distributed pool for processing, enter a valid pool name in the
Distributed Pool field.
The Object Selector allows you to select either the distributed pools or the fields from which
you want to source the pool name.
To select a distributed pool, you must first create a distributed pool. See Distributed pools
and Enabling distributed pools.
Warning
To ensure that DSO actions are executed in the correct order, assign all related
DSO actions to the same distributed pool. For example, all DSO actions associated
with the same form should use the same distributed pool.
6. (Optional) Select Override Loop Detection.

See Avoiding infinite loops.
Page 1883 of 4705
Home
Configuring DSO Delete actions

Use distributed deletes to delete specific requests, such as data-only copies of a request that are
not part of the original copy's ownership chain. See Distributed deletes.
To configure a DSO Delete action

2. In the Execute Options panel of the Filter or Escalation editor, select the trigger criteria.
Typically, the trigger criteria for distributed deletes is Delete.
4. In the Type list, select Delete.
5. Fill in these fields:
Request ID The request ID of the request to delete.
Distributed Pool The pool to use to process the action.
The Object Selector allows you to select either the distributed pools or the fields from
which you want to source the pool name.
To select a distributed pool, you must first create a distributed pool. See Distributed
pools and Enabling distributed pools.
Warning
To ensure that DSO actions are executed in the correct order, assign all
related DSO actions to the same distributed pool. For example, all DSO
actions associated with the same form should use the same distributed pool.
Server The physical name or the logical name of the server on which the form
containing the specified request resides.
Form The name of the form containing the specified request.
Enabling distributed fields

This topic explains how to add distributed fields to and delete them from forms.
Adding distributed fields to forms
To add distributed fields to forms
Deleting distributed fields from forms
To delete distributed fields from forms
For an overview of distributed fields, see Distributed fields.
Page 1884 of 4705
Home
Adding distributed fields to forms

All forms involved in distributed transfers with ownership must, at a minimum, contain the basic
distributed fields.
To add distributed fields to forms

1. In Developer Studio, open the appropriate form.
2. Select Form > Add Distributed Fields.
3. In the Add Distributed Fields dialog box, select one of these options:
Basic See Basic distributed fields.
Full See Full distributed fields.
Advanced See Advanced distributed fields.
4. To add the distributed fields as hidden fields, select the Add as Hidden Fields check box,
and click OK.
The selected distributed fields appear at the bottom of the form.
5. For forms with multiple views, add the distributed fields you selected in step 3 to the other
form views as follows:
a. Open another form view.
b. Select Form > Add/Remove Fields on View .
c. In the Add/Remove Fields in View dialog box, move the distributed fields from the
Fields Not in View list to the Fields in View list.
If you do not select individual views, the distributed fields are added to all form views
by default.
6. (Optional) Rearrange the distributed fields on the form.
Deleting distributed fields from forms

Use the following procedure to delete some or all distributed fields from a form.
Warning
When you delete a field on a From (source) form that is mapped to a field on a To (target)
form, you also delete the mapping to the target field. If the target field is optional, only
data transferred between the two fields is affected. If the target field is required, the entire
transfer operation fails.
To delete distributed fields from forms

1. In Developer Studio, open the appropriate form.
3. In the Add Distributed Fields dialog box, do one of the following:
To remove only the advanced fields, select Full.
Page 1885 of 4705
3.
Home
To remove the advanced and full fields, select Basic.

To remove all distributed fields, select None.
4. Click OK.
Enabling distributed mappings

This section contains information about creating, modifying, copying, and deleting distributed
mappings.
How distributed mapping is selected
Creating distributed mappings
Managing distributed mappings
For an overview of distributed mappings, see Distributed mapping.
For an example of how to create a distributed mapping, see Distributed operations scenarios.
How distributed mapping is selected

The mapping used in a distributed operation is selected according to the order of precedence. A
field or combination of fields takes precedence as long as no field of higher precedence contains a
value.
Order of precedence for selecting distributed mapping

Precedence
Field
Location
Mapping selected
To
Mapping
From (
source)
The mapping specified in this field is selected.
form
2
To
Server
and To
From (
source)
form
A list of mappings associated with the To server and the To form is generated. Default
mappings are listed first in the order they were created. The first mapping in the list is
selected.
Form
3
Mapping
Filter or
escalation
The mapping specified in this field is selected.
To
Server
and To
Form
Filter or
escalation
A list of mappings associated with the To server and the To form is generated. Default
mappings are listed first in the order they were created. The first mapping in the list is
selected.
From
Form
Distributed
mapping
A list of mappings is generated from all distributed mappings on the server whose From
Form value matches the name of the source form. Default mappings are listed first in the
order they were created. The first mapping in the list is selected.
Creating distributed mappings

Page 1886 of 4705
Home
Setting up automatic mapping

Using the excluded fields option
Creating custom mapping
For each server involved in ownership transfers and returns, you must define a separate,
compatible distributed mapping. That is, to transfer requests with ownership from server 1 to server
2 and to return them with ownership from server 2 to server 1, you must have a distributed mapping
on both servers.
Tip
On both server 1 and server 2, use the same distributed mapping name and to select the
same criteria for each mapping.
To create a distributed mapping

1. In Developer Studio, select File > New > Distributed Mapping.
2. Select the server on which to create the mapping, and click Finish.
3. In the Basic panel of the Distributed Mapping editor, enter the following information, then
select File > Save.
Field
Description
State
Specifies the availability of the mapping:

Enabled (default) Can be used.
Disabled Cannot be used.
Default
Mapping
When selected, specifies that the mapping is the default mapping. When the DSO action in a filter or
escalation does not specify a mapping, the default mapping is used. See Creating workflow to perform DSO
operations. For any pair of From and To servers and forms, only one distributed mapping should be specified
as the default. If two or more are specified as defaults, the system selects the mapping that was created first
when a mapping is not specified in a DSO action.
From
Server
Name
Specifies the name of the server from which the distributed operation is initiated (the source server). You can
enter or select any server on which you are a valid user. You can also select a logical server name that has
already been defined. To create or edit a logical mapping, see Enabling logical mappings.
Note
You can specify a server name other than the default server name for distributed operations. For
example, your operating environment might require you to use the fully qualified domain name (
FQDN) for your server. See Specifying a DSO host name.
Warning
Page 1887 of 4705
Home
This field is limited to 64 characters. If the server name exceeds that limit, it is truncated, and the
distributed operation fails. This is most likely to occur when you select the following Allow Any
Server in Server Group option. In that case, this field must contain the server name alias, which is
specified in the Server-Name option of the AR System server configuration file.
Allow
Any
Specifies that the mapping can use any server in the group as the From server. See Configuring DSO for a
server group. Available only when the server is in a server group.
Server
in
Server
Group
Note
When you select this option, the From Server Name field must contain the server name alias, which
is specified in the Server-Name option of the AR System server configuration file.
Form
Name
Specifies the name of the form from which the distributed operation is initiated (the source form). Enter the
form name, or click the ellipsis button to use the Form Selector.
To
Server
Name
Specifies the name of the server to which the transfer is mapped and from which update and return
operations occur (the target server). You can enter or select any server on which you are a valid user. You
can also select a logical server name that has already been defined. To create or edit a logical mapping, see
Enabling logical mappings.
Note
This field is limited to 64 characters. If the server name exceeds that limit, it is truncated, and the
distributed operation fails.
Form
Name
Specifies the name of the form to which the distributed operation is mapped (the target form). Enter the form
name, or click the ellipsis button to use the Form Selector.
4. In the Save Distributed Mapping As dialog box, enter a name for the mapping.
Distributed mapping names can include up to 80 characters, including spaces. In the
Options panel of the Distributed Mapping editor, enter the following information, then save
your changes.
Field
Description
When to
Update
Specifies the update frequency for the original request if a copy transferred with ownership is updated:
Daily At two minutes past midnight.
Hourly At two minutes past the hour.
Immediately Right after the copy is changed.
No Update Never.
On Return Only when ownership is returned.
Transfer
Mode
Specifies the type of transfer to perform:

Copy + Delete Transfers an independent copy of the request with ownership. If successful,
deletes the original in the source form.
Data + Ownership Transfers a copy with ownership inside the ownership chain. The
transferred copy becomes the master copy and can be modified in the target form. The original
becomes a data-only copy. See Request ownership chains.
Data Only Transfers a data-only copy. The original copy in the source form retains ownership.
Page 1888 of 4705
Home
Independent Copy Transfers an independent copy with ownership. It is outside the ownership
chain of the original copy.
See Types of distributed transfers.
Note
At a minimum, to transfer ownership, the form must have the basic distributed fields.
Duplicate
Request ID
Action
Specifies the action that occurs if you transfer a request and the target form already contains a request
with the same request ID:
Create New A new request is created on the target server for the transfer.
Error The transfer fails.
Overwrite The transferred request overwrites only the mapped fields on the request on the
target server that has the same request ID. (To overwrite all fields, see Overwriting all fields in
duplicate requests.)
Note
If you do not map the Request ID field, the system always creates a new Request ID on the To
server for the transferred request.
Enforce
Pattern
Matching
Specifies whether to enforce patterns defined in fields on the target form:

Yes The target system pattern checks data sent to the target form. Data transferred to fields on
the target form must follow pattern attributes defined in mapped fields on the target form.
No The target system does not pattern check data sent to the target form.
For example, suppose you map two character fields. On the target form, the mapped field's Pattern
property is set to $LOWER$. On the source form, a user enters uppercase letters in the mapped field.
When the system attempts a distributed transfer, the operation succeeds or fails depending on whether
you enforce pattern matching. Other field properties are also subject to pattern matching. See the
definition for "Pattern" in Field properties.
Require
Required
Fields
Specifies whether to require values in fields defined as required fields on the target form:
Yes The target system does not allow NULL entries in required fields on the target form.
Optional fields on the source form must contain data if they are mapped to required fields on the
target form.
No The target system allows NULL entries in required fields on the target form except in core
fields.
For example, suppose you map an optional field on the source form to a required field on the target form.
A user enters no data in the optional field on the source form. When the system attempts a distributed
transfer, the operation succeeds or fails depending on whether you allow NULL entries in required fields
on the target form.
Match by
Request ID
Specifies whether to use request IDs or another qualification to find the correct request in the target form:
Selected Distributed transfers are performed when the request ID in the target form matches
the request ID in the source form.
Cleared Target and source data are matched according to the qualification entered in the
following Matching Qualification field.
For example, if you do not want to use server-specific request ID prefixes to distinguish the requests from
one another, you can use this method (see Preventing duplicate request IDs). In this case, use a different
data field that uniquely identifies each request to match a target request with a source request.
Matching
Qualification
Page 1889 of 4705
Home
When the Match by Request ID check box is not selected, specifies the qualification to use to find the
correct entry in the target form. If you match by qualification, all form definitions used in the qualification
should be on the From (source) server. A unique index should be created on the field used to distinguish
requests. For more information about qualifications, see Building qualifications and expressions.
Retries
Specifies the maximum number of times a pending item is retried before the system cancels the item:
Forever The item is retried until its operation succeeds.
Only Once The item is tried one time. If its operation does not succeed, it is not retried.
Try for Maximum of The item is retried throughout the period of time that you specify.
See Managing pending distributed operations.
5. In the Transfer to Target panel of the editor, specify how the data in a source form is
mapped to a target form for a transfer.
See these sections:
6. In the Return from Target panel of the editor, specify how the data in a target form is
mapped to a source form for an update or a return.
See these sections:
7. To view, add, and edit Help text for the distributed mapping, use the Help Text property in
the Properties tab.
In most cases, the Help text is simply a description of the mapping. Only AR System
administrators and subadministrators who have the mapping open in the Distributed
Mapping editor can view and edit the Help.
See the definition for "Help Text" in Field properties.
8. To view, add, and edit change history for the distributed mapping, use the Change History
properties in the Properties tab, then save your changes.
For each distributed mapping, AR System automatically records information about the owner
, the user who last modified the mapping, and the date of the modification. You can view and
modify this information at any time by opening the mapping in the Distributed Mapping editor
.
See the definition for "Change History" in Field properties.

Automatic mapping is typically used to map transfers between identical forms.
Note
Before performing this task, ensure that the information in the Basic and Options panels
of the Distributed Mapping editor is correctly specified. See Creating distributed mappings.
Page 1890 of 4705
Home
To set up automatic mapping

1. Open the distributed mapping in the Distributed Mapping editor.
2. In the Transfer to Target or Return from Target panel, click Auto Map.
3. In the Auto Map dialog box, select an automatic mapping method:
Match IDs Maps fields on the source form to fields on the target form that have the
same field IDs. If you later add fields with matching IDs to both forms, BMC Remedy
AR System automatically maps them to each other.
Match Names Maps fields on the source form to fields on the target form that have
the same field names. If you later add fields with matching names to both forms, BMC
Remedy AR System automatically maps them to each other.
4. To prevent BMC Remedy AR System from mapping certain fields, select the fields in the
Auto Map table's Field column, and click Remove.
5. Click OK.
The mapped fields appear in the table on the Transfer or Return panel.
Note
If you are not creating mapping between identical forms, ensure that no unwanted
unmapped fields exist on the forms.
6. To customize any of the mappings listed in the table or to add custom mappings, see
Creating custom mapping.

For the Like Field IDs or Like Field Names mapping type, you can select a list of fields that you
want to exclude from mapping. DSO avoids mapping these fields for the DSO transfer or return
action. After the mapping is configured, if a new field gets added, it gets mapped automatically,
unless it is present in the excluded fields list.
You can use the excluded fields list for both DSO transfer and DSO return actions.
Note
Before performing this task, ensure that the information in the Basic and Options panels
To add a field in the excluded fields list

2. In the Transfer to Target or Return from Target panel, select Like Field IDs or Like Field
Names, and click Add.
3.
Page 1891 of 4705
Home
3. In the Object Selector, select the fields that you want to exclude from mapping, and click
OK.
The excluded fields appear in the table on the Transfer to Target or Return from Target
panel.

Use custom mapping in these situations:
The source and target forms contain fields whose IDs and names do not match.
You want to use keywords, static values, arithmetic operations, functions, or processes
based on the values of one or more fields in the source form to populate a field in the target
form.
Warning
If you modify a source or target form used in a custom mapping, the custom mapping
might be invalid until you make the appropriate changes to the mapping.
Before performing the following task, ensure that the information in the Basic and Options panels
To create custom mapping

2. Open the Transfer to Target or Return from Target panel.
3. Perform one of these actions:
To add a custom mapping, click the first empty Field cell, and then click the cell's
ellipsis button.
To customize an existing mapping, click the mapping's Field cell, and then click the
cell's ellipsis button.
4. In the Field Selector dialog box, select a field in the To (target) form, then click OK.
5. In the same table row, click the Value cell, and then click the cell's ellipsis button.
6. In the Expression Editor, specify one of the following items from which to derive a value in
the source form to pass to the target field specified in step 4:
Field in the From (source) form
Keyword
Static value
Arithmetic operation
Function
Process
Page 1892 of 4705
Home
Note
This option shows the logical strings that can be used for custom mapping.
For more information, see Distributed logical mapping.
When specifying field mappings in the Expression Editor, ensure that the values you
enclose in dollar signs ($) do not match strings used as keywords (unless you want to
map a keyword value). For example, if you have a field named OS (short for "
Operating System") and specify the field mapping as $OS$, map the value for the
keyword OS (in this case, your operating system) instead of the preferred field value.
For more information, see Keywords.
Important
Always map the source and target Request ID fields to each other. If you do
not, the system creates a new ID on the target server for the transferred
request. If you use matching qualifications, you must also map the fields
used in the qualification to uniquely match one request with another.
7. Repeat steps 3 through 6 for each field that you want to map.
8. To delete a mapping from the table, select the Field value, press Delete, then s.
Managing distributed mappings

In this topic:
Modifying distributed mapping
To modify a distributed mapping
Copying distributed mappings
To copy a distributed mapping
Deleting distributed mappings
To delete a distributed mapping
Modifying distributed mapping

Follow this procedure to modify a distributed mapping.
Warning
Page 1893 of 4705
Home
Before you modify the name of a distributed mapping, verify that it is not associated with a
packing list. Developer Studio does not update the name of a distributed mapping in a
packing list. Instead, the distributed mapping is removed, and you must re-add it to the
packing list under the new name.
To modify a distributed mapping

1. Open Developer Studio.
2. In AR System Navigator, expand the appropriate server tree.
3. In the server tree, expand the All Objects node.
4. In the All Objects list, double-click Distributed Mappings.
The Distributed Mappings tab appears in the object lists area. The tab lists the distributed
mappings defined on the server.
5. Double-click the distributed mapping that you want to modify.
The distributed mapping appears in the Distributed Mapping editor.
6. Modify the mapping as necessary.
For information about the fields in the editor, see Adding distributed fields to forms.
7. Select File > Save.
Copying distributed mappings

A copy of a distributed mapping contains all the properties of the original distributed mapping. The
only difference is the name.
Tip
You can use DSO to send copies of distributed mappings to other servers. This enables
you to administer the mappings from one server and ensure that all mappings remain
synchronized. See Broadcasting distributed mappings and pools.
To copy a distributed mapping

5. Double-click the distributed mapping that you want to copy.
The distributed mapping appears in the Distributed Mapping editor.
6. Select File > Save As.
7. In the Save Distributed Mapping As dialog box, enter a name for the new distributed
mapping.
8.
Page 1894 of 4705
Home
8. Click OK.
The new distributed mapping is listed on the Distributed Mappings tab.
Deleting distributed mappings

The delete operation cannot be undone. Make sure that you no longer need a mapping before
deleting it. You cannot delete open distributed mappings.
To delete a distributed mapping

5. Select the distributed mapping that you want to delete.
6. Select Edit > Delete.
The distributed mapping is deleted from the server, and its name is removed from the
Distributed Mappings tab.
Enabling distributed pools

This section contains information creating and modifying distributed pools:
Creating distributed pools
Managing distributed pools
Setting polling intervals for distributed pools
Using distributed pools is optional. If you use them, however, you must create them for various].
Tip
You can use DSO to transfer pool definitions to other servers, enabling you to administer
and synchronize all pools from one server. See Broadcasting distributed mappings and
pools.
Creating distributed pools

1. In Developer Studio, select File > New > Distributed Pool.
2. Select the server on which to create the pool, and click Finish.
3. In the Basic panel of the Distributed Pool editor, enter this information:
Field
Description
Page 1895 of 4705
3.
Home
Specifies whether the pool is active (enabled) or inactive (disabled). Select the appropriate value:
State
Enabled (default)
Disabled
Default
Pool
Specifies whether the pool is the default pool. The default pool is used when no pool is specified for a
Polling
Specifies whether the pool is a polling pool.

Selected It is a polling pool.
Not selected (Default) It is not a polling pool.
See Setting polling intervals for distributed pools.
Interval
If the Polling check box is selected, specifies the interval, in minutes, at which the pool queries the distributed
(mins)
pending queue.
Minimum interval is 5 minutes (default).
distributed operation. See Default distributed pool.
Maximum interval is 1440 minutes (24 hours).

If you enter values outside these limits, the system uses the limit closest to your value.
Note
When setting a polling interval, consider the number of requests processed by the pool. For example,
if a pool processes 2 million requests each day and has a 720-minute (12-hour) polling interval, the
pool will be deluged with 1 million requests to process every 12 hours.
See Setting polling intervals for distributed pools.

5. In the New Name field, enter a name for the pool, then click OK.
Distributed pool names can have up to 80 characters, including blank spaces. Do not use
special characters, such as a forward slash (/), a colon (:), or a question mark (?). Use
alphanumeric characters only. (See BMC Remedy Distributed Server Option logging .)
Note
DSO recognizes only one distributed pool for each pool name and creates a log file
for that pool (see Configuring BMC Remedy Distributed Server Option logging ).
Thus, you cannot use the same name for multiple pools, even if you use a different
case. For example, DSO considers pool names HIKE4, Hike4, and hike4 to be the
same and creates only one pool with these values.
6. (Optional) In the Properties tab, select the Help Text property, click its ellipsis button, enter
any appropriate Help text for the pool, and click OK.
7. (Optional) In the Properties tab, select the change history New Description property, click
its ellipsis button, enter any appropriate change history information for the pool, and click OK
.
See the definition for Change History in Field properties.
8. Select File > Save, then restart the DSO server.
Page 1896 of 4705
Home
Managing distributed pools

In this topic:
Modifying distributed pools
Copying distributed pools
Deleting distributed pools
To delete a distributed pool
Modifying distributed pools

4. In the All Objects list, double-click Distributed Pools.
The Distributed Pools tab appears in the object lists area. The tab lists the distributed
5. Double-click the distributed pool that you want to modify.
The distributed pool appears in the Distributed Pool editor.
6. Modify the pool as necessary.
For information about the fields in the editor, see Creating distributed pools.
7. Select File > Save, then restart the DSO server.
Copying distributed pools

The Distributed Pools tab appears in the object lists area. The tab lists the distributed pools
defined on the server.
5. Double-click the distributed pool that you want to copy.
The distributed pool appears in the Distributed Pool editor.
7. In the Save Distributed Pool As dialog box, enter a name for the new distributed pool.
8. Click OK.
The new distributed pool is listed on the Distributed Pools tab.
9. Restart the DSO server.
Deleting distributed pools

Follow this procedure to delete a distributed pool. You cannot delete enabled distributed pools.
Warning
Page 1897 of 4705
Home
The delete operation is permanent. Ensure that you no longer need a distributed pool
before deleting it.
To delete a distributed pool

The Distributed Pools tab appears in the object lists area. The tab lists the distributed pools
defined on the server.
5. Select the distributed pool that you want to delete.
The distributed pool is deleted from the server, and its name is removed from the Distributed
Pools tab.

By default, all distributed pools are nonpolling pools they query the distributed pending queue in
real time whenever a request associated with the pool is submitted to the queue.
For pools with heavy activity, however, BMC recommends that you make them polling pools, which
query the distributed pending queue at specified intervals. For example, suppose a pool is
configured to query the queue every 12 hours. If a request associated with the pool is submitted to
the queue 1 hour after the pool's last query, the request is not processed for 11 hours. Use this
option to shift the processing of noncritical requests to periods of low database activity.
To set a polling interval for a distributed pool, use the Distributed Pool editor. See Creating
distributed pools.
Default pool and polling

When a distributed pool is disabled, the operations associated with it are processed by the default
pool. If the default pool is a polling pool, the operations are not immediately processed. Consider
this when setting up your pools.
Enabling logical mappings

This section contains information about creating, modifying, copying, and deleting distributed logical
mappings:
Creating logical mappings
Managing distributed logical mappings
For an overview of distributed logical mappings, see Distributed logical mapping.
Page 1898 of 4705
Home
Creating logical mappings

You can define logical mappings for each server name involved in a transfer, return, or delete
action. While moving the distributed mappings from the development environment to the production
environment, this feature eliminates the need to manually replace the server names in any
distributed mapping. At run time, DSO replaces the logical server name with the physical server
name in accordance with the mappings in the Distributed Logical Mapping form.
You can also create a mapping to define a logical name for a field whose value is not known at the
time the distributed mappings are being developed. While moving this mapping to production
environment, you can change the value of the physical name with the actual value for this field in
the Distributed Logical Mapping form. This ensures that the mapping works properly for your
production environment.
To create a distributed logical mapping

1. In a browser, open the AR System Administration Console, and click System > Distributed
Server Option > Distributed Logical Mappings > New request .
2. Enter the following information:
Logical Name: Specifies the name of the logical entity (server or field name) defined
in the distributed mapping
Physical Name: Specifies the name of the actual entity (server or field name) where
the user wants to use the distributed mapping
Logical Server Name: When selected specifies that this logical name is for a server.
This is required only if you want to select the name of the logical server in the Server
Name box either in the Distributed Mapping editor or the DSO action editor in BMC
3. Click Save.
Managing distributed logical mappings

In this topic:
Modifying distributed logical mappings
Deleting logical mappings
To delete a distributed logical mapping
Modifying distributed logical mappings

Server Option > Distributed Logical Mappings > Search .
2. From the results list, select the item to modify.
3. Modify the mapping as necessary.
4. Click Save.
Page 1899 of 4705
Home
Deleting logical mappings

The delete operation cannot be undone. Make sure that you no longer need a mapping before
deleting it.
To delete a distributed logical mapping

Server Option > Distributed Logical Mappings > Search .
2. From the results list, select the item to delete.
3. Click Delete.
Managing pending distributed operations

This section contains information about managing items in the pending distributed queue:
Viewing items in the pending distributed queue
Removing items from the distributed pending queue
How errors affect pending items
Handling duplicate pending items
Logging failed pending items
Retrying failed pending items
Viewing items in the pending distributed queue

Use this procedure to view the distributed operations pending on your local AR System server.
To view items in the pending distributed queue

1. In the left pane of the AR System Administration Console, click System > Distributed
Server Option > Pending DSO Operations .
2. In the Distributed Pending form, enter the appropriate search criteria, and click Search.
For each item that appears in the results list, the form includes this information:
Field
Description
Pending ID
ID of the item.
Pending
Type
Distributed operation type (transfer, update, return, or delete).
Form
Name of the source form.
Source ID
ID of the source request.
Other
String that specifies additional information about the distributed operation. The string includes one or more
of these parameters:
-e ID of the target request in a distributed delete operation.
-E ID of the source request in a distributed delete operation.
Page 1900 of 4705
Home
-o Flag indicating a limit override in which the DSO server cannot initiate a transfer or return
operation.
-p Name of the pool to which a distributed delete operation is assigned.
-s Name of the form involved in a distributed delete operation.
-x Name of the server involved in a distributed delete operation.
Pool
Name of the pool to which the distributed transfer, update, or return operation is assigned.
Status
Status of the item.
Removing items from the distributed pending queue
Warning
This procedure completely removes the item so that it cannot be retried.
To remove items from the distributed pending queue

1. In the left pane of the AR System Administration Console, click System > Distributed
Server Option > Pending DSO Operations .
2. In the Distributed Pending form, enter the appropriate search criteria, and click Search.
3. In the results list, select the item to remove.
4. Select Actions > Delete.
5. Select View > Refresh Search to update the list of items.
How errors affect pending items

The DSO server reads items from the distributed pending queue and performs the specified
operation (transfer, update, return, or delete) for each item. By default, the DSO server checks for
new pending items at the following times:
When an internal signal mechanism triggered by workflow alerts the server.
Automatically at two minutes after every hour, ensuring that all pending items are processed
if the internal signal mechanism fails. (To change this default, see Setting a custom backup
polling interval.)
For information about when polling DSO servers and pools check for requests, see these sections:
If an item succeeds or if it fails with a nonrecoverable error, it is removed from the distributed
pending queue. (You can configure DSO to move pending items that fail with nonrecoverable errors
to the Distributed Pending Errors form. See Logging failed pending items.)
By default, if a pending item fails with a recoverable error, such as an unavailable target server,
DSO periodically retries the item as follows:
Page 1901 of 4705
Home
Every 5 minutes for the first 30 minutes

Every 30 minutes after the initial 30 minutes for up to 24 hours
Every hour after the first 24 hours
To specify whether the Status value of failed items remains set to New or is changed to Retry, set
the Mark Pending Retry field in the AR System Administration: Server Information form. (See the
definition for "Mark Pending Retry" field in AR System Administration - Server Information form DSO tab.)
To limit the number of times the item is retried, change the default Retries value in the distributed
mapping. See the definition for "Retries" in Creating distributed mappings.
If you specify values in the Retries "Try for Maximum of Hours/Minutes " option and the specified
time limit elapses, the item is removed from the distributed pending queue. This occurs even if one
or more retries were not attempted. In this case, if the item includes a Transfer Status or Update
Status field, it is set to Timeout.
Note
By default, the system allows three minutes of connection time for processing each
distributed operation. This might be an insufficient amount of time in some situations and
might cause pending distributed operations to fail. See Configuring the RPC timeout
setting.
Handling duplicate pending items

When the DSO server retrieves a list of pending items to process from the distributed pending
queue, the list sometimes includes duplicate items (items that have the same request ID for the
same form).
For example, suppose a filter containing a DSO action executes on both Submit and Modify
operations. If the following sequence of events occurs, two pending items for the same Help Desk
request are added to the distributed pending queue:
1. A user submits a request through the "Help Desk" form.
2. A Push Fields action transfers some data in the request to another form.
3. The data transfer triggers a Modify operation on the Help Desk form.
4. The Submit operation on the Help Desk form that began in step 1 is completed.
This example adds two pending items to the distributed pending queue (one in step 3 and one in
step 4) for the same request in the Help Desk form.
Page 1902 of 4705
Home
In such situations, the DSO server performs the distributed operation specified in only the most
recent duplicate item (in this example, the pending item created in step 4). For each of the other
duplicate items, it adds the following entry to its log file and then deletes the item:
<DIST>
DUPLICATE FOUND: This will be deleted later on.
For information about DSO logging, see Configuring BMC Remedy Distributed Server Option
logging.
Logging failed pending items

You can log failed pending items in the Distributed Pending Errors form. The form includes this
information:
The error message that is most relevant to the failure
The operational stage in which the failure occurred
The form is available only on AR System servers that have a license for DSO.
For more information about DSO logging, see Configuring BMC Remedy Distributed Server Option
logging.
Distributed Pending Errors form
To log failed pending items

1. Open the AR System Administration: Server Information form for the local server.
2.
Page 1903 of 4705
Home
2. On the DSO tab, select Log Errors to DSO Pending Errors Form .
3. Click OK or Apply.
Your changes take effect immediately. You do not have to restart the AR System server.
Retrying failed pending items

Instruct DSO to retry items in the Distributed Pending Errors form as follows.
To retry failed pending items

1. Open the Distributed Pending Errors form in Search mode.
2. Enter the appropriate search criteria, and click Search.
3. In the results list, select one or more pending items to retry.
4. Perform one of these procedures:
If you selected only one item in step 3:
a. Select Retry.
b. Click Save.
If you selected multiple items in step 3:
c. Select Actions > Modify All.
The Details pane changes to Modify All mode, and a blank form is displayed.
d. In the blank form, select Retry.
e. Click Save.
f. In the confirmation message, click Yes.
The specified items are removed from the Distributed Pending Errors form and
re-added to the Distributed Pending form. They are retried as follows:
If a polling interval is set for the local DSO server, the item is retried when the
polling interval expires. (See Setting a polling interval for the DSO server .)
If the item contains distributed pool information and the pool has a polling
interval, the item is retried when the pool polling interval expires. (See Setting
polling intervals for distributed pools.)
All other items are retried when the backup polling interval expires or when a
new pending item is created, whichever occurs first. (See Setting a custom
backup polling interval.)
Performing distributed operations on join forms

The Distributed Server Option can perform all types of distributed operations transfer, update,
return, and delete on join forms.
Before performing a distributed operation on a join form, complete these tasks:

Add the following field to at least one of the join form's underlying forms:
ARDS_RESERV_DISTRIB_UNIQUE_ID (field ID 322)
Page 1904 of 4705
Home
Add field ID 322 to the join form from one of the underlying forms.
Field ID 322 is a reserved field that has characteristics similar to field ID 112, the Assignee
Group field. A join form can contain only one instance of each reserved field.
For CREATE and MERGE operations that trigger DSO actions on join forms, create workflow
that populates field ID 322 with the request's joinEntryID before the DSO action occurs.
The joinEntryID is composed of the request IDs of both underlying forms, separated by a
vertical bar (|).
The system uses the contents of field ID 322 to populate the Source ID field of the
Distributed Pending form.
Note
Evaluate the workflow to determine whether you need to protect any of the merge
filters from the DSO user. If you do, use this qualification: $USER$ != '
Distributed Server'. For more information about the DSO user, see
Configuring a password for the DSO user .
Create workflow to propagate the distributed data to the underlying forms.
Note
For distributed operations involving join forms, the DSO logs do not include the Request
ID of the request created or modified in the target form.
Tip
BMC recommends that you perform distributed operations directly on the underlying forms
of a join form instead of on the join form whenever possible.
For more information, see Join forms.
Setting up distributed operations

To set up distributed operations, follow this process:
1. Activate DSO and configure it for your distributed environment.
See Configuring BMC Remedy Distributed Server Option .
2. Determine which forms you will transfer data from and which forms you will transfer data to.
3. Determine the amount of control you need over the transferred data:
Page 1905 of 4705
3.
Home
Should one server own master copies of transferred requests, or should all copies be
independent?
See Types of distributed transfers.
How often should requests be updated on a server?
See the definition for "When to Update" in Creating distributed mappings.
How should duplicate request IDs be handled?
See Managing request IDs in distributed environments.
Will you need to override distributed mapping settings on a per-request basis?
See Overriding mapping settings on a per-request basis .
4. Determine which distributed fields to add to the forms identified in step 2.
See Distributed fields.
5. Add distributed fields to the forms identified in step 2.
See Adding distributed fields to forms.
6. Determine whether you will use distributed pools.
See Distributed pools.
7. (Optional) Create distributed pools according to your analysis in step 3.
See Enabling distributed pools.
8. Determine how to map the forms identified in step 2.
See Distributed mapping.
9. Create the required distributed mappings.
See Creating distributed mappings.
Note
Unless otherwise noted, this section assumes that you are mapping between two
servers. To maintain data integrity on more than two servers, see Chained and
broadcast distributed transfers.
10. Create filters or escalations that define the conditions under which distributed operations
occur.
See Creating workflow to perform DSO operations.
11. (Optional) Employ some of these advanced functions:
Setting up chained distributed transfers
Setting up broadcast distributed transfers
Distributed operations scenarios

Distributed transfer scenario
Distributed update scenario
Distributed return scenario
Distributed delete scenario
Page 1906 of 4705
Home
Each of the topics in this section is a start-to-finish example of how basic distributed operations are
implemented between two geographically distinct servers at Acme Industries.
Acme makes custom office furniture that is distributed to and returned from vendors such as office
supply stores. Assume you are a manager with administrator privileges and a fixed license at the
Acme plant in San Francisco, California. Acme recently opened another plant in Chicago, Illinois.
Labor is divided between the plants as follows:
Plant
Manufactures and repairs
San Francisco
Request ID prefix
AW (Acme West)
Prize Desks
Prize Printer Stands
Chicago
AE (Acme East)
Choice Desk Chairs
Superior Side Chairs
Information about Acme's vendors is stored in Acme's customer information forms. Products
returned from vendors for various faults are entered into Acme's bug tracking forms. You must set
up distributed operations between the bug tracking form on the sanfrancisco server and the bug
tracking form on the chicago server. Both servers have DSO licenses.
Note
All the examples in this section assume that you have created the Acme West Bug
Tracking form on the sanfrancisco server and the Acme East Bug Tracking form on the
chicago server.
Distributed transfer scenario

To perform a distributed transfer operation from the sanfrancisco server to the chicago server,
create a distributed mapping and a filter (or escalation) with a DSO Transfer action on the From (
sanfrancisco ) server by performing these tasks:
1. Add distributed fields to the Acme bug tracking forms.
2. Create distributed mappings for the Acme bug tracking forms.
3. Create a filter with a DSO Transfer action on the From server.
4. Test the distributed mapping.
After you complete these tasks, a bug request created on the sanfrancisco server for
Choice or Superior products is transferred to the chicago server.
Note
Page 1907 of 4705
Home
In this section, you create identical distributed mappings on the From (

sanfrancisco) and To (chicago) servers. Such mappings are required for
distributed update and return operations, which are covered in the following
sections.
Add distributed fields to the Acme bug tracking forms

For overview information, see Distributed fields.
To add distributed fields to the Acme bug tracking forms

1. Establish the forms and servers to be mapped:
Object to map
From
To
Server
sanfrancisco
chicago
Form
Acme West Bug Tracking
Acme East Bug Tracking
2. In Developer Studio, log on to the sanfrancisco server.

3. Open the Acme West Bug Tracking form.
5. In the Add Distributed Fields dialog box, select Basic, and click OK.
6. (Optional) Rearrange the distributed fields added to the form in step 5.
7. Save the form.
8. Repeat step 2 through step 7 for the chicago server and its Acme East Bug Tracking form.
Create distributed mappings for the Acme bug tracking forms

Distributed mappings specify which fields on the From form (Acme West Bug Tracking) supply data
to which fields on the To form (Acme East Bug Tracking).
For overview information, see Distributed mapping.
To create distributed mappings for the Acme bug tracking forms

1. In Developer Studio, select File > New > Distributed Mapping.
2. Select the sanfrancisco server, and click Finish.
3. In the Distributed Mapping editor, fill in the Basic and Options panels as shown below:
Distributed Mapping editor Basic panel for sanfrancisco server
Page 1908 of 4705
Home
Distributed Mapping editor Options panel
4. In the Transfer to Target panel, click Auto Map,

select Match IDs, and click OK.
5. In the Return from Target panel, click Auto Map,
select Match IDs, click OK, then select File > Save.
6. In the Save Distributed Mapping As dialog box, enter Acme W to E Bug Track , then click
OK.
7. Select File > New > Distributed Mapping.
8. Select the chicago server, and click Finish.
9. In the Distributed Mapping editor, fill in the Basic and the Options panels as shown below:
Distributed Mapping editor Basic panel for chicago server
Page 1909 of 4705
Home
10. Configure the Transfer to Target panel, Auto Map dialog box, and Return from Target
panel as described in step 4 and step 5.
11. In the Save Distributed Mapping As dialog box, enter Acme E to W Bug Track , then click
OK.
Create a filter with a DSO Transfer action on the From server

To transfer data from a form on the sanfrancisco server to a form on the chicago server, you must
create a filter with a DSO Transfer action on the sanfrancisco server.
For overview information, see Creating workflow to perform DSO operations.
To create a filter with a DSO Transfer action on the From server

1. In Developer Studio, select File > New > Filter.
2. Select the From (sanfrancisco) server, and click Finish.
3. In the Associated Forms panel of the Filter editor, click Add.
4. In the Form Selector, select the Acme West Bug Tracking form, and click OK.
5. In the Execution Options panel, set the options shown in the following figure:
Filter editor Execution Options panel
Page 1910 of 4705
5.
Home
6. In the Run If Qualification panel, click the ellipsis button.

7. In the Expression editor, enter the following qualification, and then click OK:
NOT 'Product' LIKE "P%"
The qualification states that the filter action should be executed when the product name
does not begin with the letter P.
Thus, when a request is created in the form associated with this filter (the Acme West Bug
Tracking form) for a Choice Desk Chair or a Superior Side Chair, the action associated with
this filter is executed.
9. In the Type list in the DSO panel, select Transfer.
10. To use the default mapping, leave the other fields blank, then select File > Save.
11. In the Save Filter As dialog box, enter a name for the filter, such as Acme W to E Bug Track,
then click OK.
Test the distributed mapping

To test the mapping in this example, open the Acme West Bug Tracking form in a browser, and
create some requests for each of the Acme products. All requests submitted for products the
Choice Desk Chair and Superior Side Chair products should be immediately transferred with
ownership to the Acme East Bug Tracking form. The original request on the sanfrancisco server
becomes a data-only request (see Types of distributed transfers).
Distributed update scenario

The distributed mappings created in the preceding section can be configured so that when a
request transferred with ownership to the Acme East Bug Tracking form is modified, the original
copy in the Acme West Bug Tracking form is updated. (The Acme East form retains ownership of
the request.)
Notes
Distributed updates require compatible distributed mappings on the source and

target servers.
Requests transferred without ownership cannot be modified on the target server, so
this topic is not applicable to them.
Page 1911 of 4705
Home
For overview information, see Distributed updates.
To configure a distributed update for the Acme bug tracking forms

1. If you have not created a distributed mapping for both bug tracking forms, do so.
See To create distributed mappings for the Acme bug tracking forms .
2. In Developer Studio, open the distributed mapping used by the Acme West Bug Tracking
form on the sanfrancisco server.
3. In the Options panel, select the appropriate option from the When to Update list.
Distributed Mapping editor When to Update list in Options panel
Distributed return scenario

The following procedure configures the distributed mappings used by the Acme West and Acme
East bug tracking forms so that requests transferred to the Acme East form with ownership are
returned with ownership to the Acme West form after they are fixed. (To create the mapping, see
To create distributed mappings for the Acme bug tracking forms .)
To perform a distributed return operation, you must have these items:
A distributed mapping plus a filter or escalation with a DSO Transfer action on the source
server
A compatible distributed mapping plus a filter or escalation with a DSO Return action on the
target server
For more information, see Distributed returns.
To configure a distributed return operation on the To server

2. Select the To (chicago) server, and click Finish.
3.
Page 1912 of 4705
Home
3. In the Associated Forms panel of the Filter editor, click Add, select the Acme East Bug
Tracking form, and click OK.
5. In the Run If Qualification panel, click the ellipsis button.

6. In the Expression editor, enter the following qualification, and then click OK:
'Status' = "Fixed"
The qualification states that the filter action should be executed when the status for the bug
is fixed.
Thus, when the status of a request in the form associated with this filter (the Acme East Bug
Tracking form) is changed to Fixed, the action associated with this filter is executed.
8. In the Type list in the DSO panel, select Return, then select File > Save.
9. In the Save Filter As dialog box, enter a name for the filter, such as Acme E to W Bug Track,
then click OK.
Test the distributed mapping

To test the mapping in this example, open the Acme East Bug Tracking form in a browser, and
change the status to Fixed on requests transferred from the Acme West Bug Tracking form. The
requests should be returned with ownership to the Acme West form.
You should be able to modify the returned requests on the sanfrancisco server. The
corresponding requests on the chicago server become independent data-only copies (see Types
of distributed transfers).
Distributed delete scenario

When the master copy of a distributed request is deleted, all copies in the active ownership chain
are also deleted.
For example, suppose a request created in the Acme West Bug Tracking form is transferred with
ownership to the Acme East Bug Tracking form. If you delete the copy of the request in the Acme
East form, the original copy in the Acme West form is also deleted. (AR System does not delete
copies of the request in either form that are not in the active ownership chain.)
For more information, see Request ownership chains.
Page 1913 of 4705
Home
To configure a distributed delete operation on the To server

2. Select the To (chicago ) server, and click Finish.
3. In the Associated Forms panel of the Filter editor, click Add.
4. In the Form Selector, select the Acme East Bug Tracking form, and click OK.
7. In the Type list in the DSO panel, select Delete.
8. Fill in the other fields as shown in the following figure, then select File > Save.
Filter editor DSO Delete action
9. In the Save Filter As dialog box, enter a name for the filter, such as Acme Bug Distributed
Delete, then click OK.
Now, when a request is deleted from the Acme West Bug Tracking form, this DSO action
deletes the request with the same Request ID in the Acme East Bug Tracking form on the
chicago server.
Chained and broadcast distributed transfers

Both chained and broadcast distributed transfers involve multiple servers. For example:
Page 1914 of 4705
Home
A chained distributed transfer occurs when the sanfrancisco server transfers a request to
the chicago server, and then the chicago server transfers the request to the toronto server
.
A broadcast distributed transfer occurs when the sanfrancisco server transfers the same
request to two servers, chicago and toronto.
Consider the overhead that might be involved in the implementation and maintenance of these
features. When data is distributed among more than two sites, your troubleshooting effort might
increase exponentially.
The examples in this section assume that you are an administrator at Acme Industries (see
Distributed operations scenarios). You are mapping forms among three servers located in San
Francisco, Chicago, and Toronto. All the servers have DSO licenses.
The procedures in this section build on procedures in Distributed operations scenarios.

Testing chained distributed mappings
Creating mapping chains
Managing chained distributed transfers
You can set up a distributed environment involving more than two locations in which the servers are
"chained," creating a staggered distribution effect.
For example, in this section, you create a distributed transfer on the sanfrancisco server that
sends a request from the Acme West Bug Tracking form to the Acme East Bug Tracking form on
the chicago server whenever someone creates or modifies a bug request for Choice Desk Chairs
or Superior Side Chairs in the Acme West form.
You then create a distributed transfer on the chicago server that sends any bug request for
Superior Side Chairs that is transferred into the Acme East Bug Tracking form to the Acme Canada
Bug Tracking form on the toronto server.
The following figure shows an example of a chained distributed transfer.
Chained distributed transfer example
Page 1915 of 4705
Home
To set up a chained distributed transfer

1. Perform these tasks:
Create the Acme West Bug Tracking form on the sanfrancisco server.
Create the Acme East Bug Tracking form on the chicago server.
Create the Acme Canada Bug Tracking form on the toronto server.
Add basic distributed fields to the forms.
See Adding distributed fields to forms.
Add distributed mappings and filters to the sanfrancisco and chicago servers
according to the procedures in Distributed operations scenarios.
2. Create a distributed mapping between the chicago and toronto servers to transfer bug
requests for Superior Side Chairs from the Acme West Bug Tracking form to the Acme
Canada Bug Tracking form with ownership:
a. In Developer Studio, select File > New > Distributed Mapping.
b. Select the From (chicago ) server, and click Finish.
c. In the Distributed Mapping editor, fill in the Basic panel as shown below:
Distributed Mapping editor Basic panel for chicago server
Page 1916 of 4705
Home
d. Fill in the Options panel as shown below:

e. In the Transfer to Target panel, click Auto Map.

f. In the Auto Map dialog box, select Match IDs, and click OK.
g. In the Return from Target panel, click Auto Map.
h. In the Auto Map dialog box, select Match IDs, click OK, then select File > Save.
i. In the Save Distributed Mapping As dialog box, enter Acme E to C Bug Track , then
click OK.
3. Create a filter with a DSO Transfer action on the From server:
a. In Developer Studio, select File > New > Filter.
b. Select the From (chicago ) server, and click Finish.
c. In the Associated Forms panel of the Filter editor, click Add.
d. In the Form Selector, select the Acme East Bug Tracking form, and click OK.
e. In the Execution Options panel, set the options shown in the following figure:
Page 1917 of 4705
Home
f. In the Run If Qualification panel, click the ellipsis button.

g. In the Expression editor, enter the following qualification, then click OK:
'Product' LIKE "S%"
The qualification states that the filter action should be executed when the product
name on the Acme East Bug Tracking form begins with the letter S.
h. Right-click the If Actions panel, and select Add Action > DSO.
i. In the Type list in the DSO panel, select Transfer.
j. Select Override Loop Detection, then select File > Save.
See Avoiding infinite loops.
k. In the Save Filter As dialog box, enter a name for the filter, such as Acme E to C Bug
Track, then click OK.
Testing chained distributed mappings

Test the chained distributed mapping by creating some requests for Prize Desks, Choice Desk
Chairs, and Superior Side Chairs in the Acme West Bug Tracking form ( sanfrancisco ).
Requests for both types of chairs should be transferred to the Acme East Bug Tracking form (
chicago ). Requests for Superior Side Chairs should then be transferred to the Acme Canada Bug
Tracking form (toronto ).

If the Duplicate Request ID Action specified in the mapping is Overwrite, do not transfer requests
with ownership.
Duplicate Request ID Action list Options panel of Distributed Mapping editor
Page 1918 of 4705
Home
The combination of transferring ownership and overwriting existing requests in a chained

environment can create an infinite loop.
By default, BMC Remedy AR System protects you against infinite loops by providing automatic loop
detection. If you need to update the original request, however, perform the following procedure to
override this protection.
To override loop detection

In Developer Studio, select the Override Loop Detection check box in DSO Transfer or DSO
Return subpanel on the If Actions panel in the filter or escalation editor.
Override Loop Detection check box If Actions panel of Filter editor
Page 1919 of 4705
Home
Warning
If you shut down loop protection, you risk creating infinite loops and overwriting the
original record in a distributed transfer or distributed return operation.
Creating mapping chains

Each distributed mapping lets you define two locations. To transfer requests among more than two
locations, you can chain mappings together. Mapping chains enable you to reduce the total number
of mappings in your system.
For example, suppose you have these mappings:
Mapping A transfers requests from toronto to sanfrancisco
Mapping B transfers requests from sanfrancisco to chicago
Mapping C transfers requests from chicago to toronto
To transfer requests from toronto to chicago, you can either create another mapping from toronto
to chicago or reuse existing mappings by chaining Mapping A to Mapping B.
Tip
Page 1920 of 4705
Home
Create a separate mapping chain each time you have a different starting and stopping
place. Doing so avoids the looping issue that might occur if you create one mapping chain
from sanfrancisco to chicago, chicago to toronto, and toronto to sanfrancisco to
transfer copies with ownership.
Managing chained distributed transfers

In this topic:
Controlling updates
Controlling returns
Deleting requests
This topic explains how to manage chained distributed transfers.
Controlling updates
To control updates, select a value other than No Update in the When to Update list in the Options
panel of the Distributed Mapping editor.
When to Update list Options panel of Distributed Mapping editor
Any changes made to a request in the To form of a mapping are sent back as updates to the From
form in the mapping.
Controlling returns
To control returns, you can create a filter that looks for a condition in which Data + Ownership is the
Transfer mode. This filter action takes the transferred request and executes another mapping
specified in the filter action. The filter action then returns the request to the From form defined in the
Transfer mapping.
Page 1921 of 4705
Home
Deleting requests
Users can delete only the master copy or independent copies of a request in an ownership chain.
When the master copy of a request is deleted, all other requests in the ownership chain are also
deleted.
You can use the DSO Delete filter action to delete requests that are outside the active ownership
chain, or you can use ardist to clear the Master Flag (see Distributed Server Administration
program).
For more information, see Distributed deletes.

In this topic:
Broadcasting distributed mappings and pools
You can set up a distributed environment involving more than two locations. In this environment,
one server "broadcasts" copies of a request to multiple recipients.
Broadcast distributions are typically used to propagate forms, such as remote knowledge bases,
from a central source. Ownership does not transfer with the requests, and when the distributed
copies are modified, the original request is not updated.
For example, if you define a mapping on the sanfrancisco server that sends a data-only copy of a
request to the chicago server, you must also define a mapping on the sanfrancisco server that
sends another data-only copy of the same request to the toronto server.
If you try to broadcast copies of requests with ownership, the system successfully executes the
transfer specified by the first filter action. All remaining transfers to other servers, specified by
subsequent filter actions, result in error messages because ownership was transferred off the From
server during the first filter action.
Tip
Use one or more distributed pools when performing broadcast distributed operations.
Doing so allows many of the transfers in the broadcast to occur simultaneously instead of
one at a time. See Distributed pools.
This section explains how to set up a broadcast distributed transfer that sends requests created in
the Acme Product Info Archive form on the sanfrancisco server to the Acme Product Info Archive
forms on the chicago and toronto servers. The following figure illustrates the flow of this example
Page 1922 of 4705
Home
broadcast distributed transfer.

Broadcast distributed transfer example
To set up a broadcast distributed transfer

1. Create a distributed mapping named*Acme ProdInfoArch W to E* between the Acme
Product Info Archive forms on the*sanfrancisco* and*chicago* servers.
In the Distributed Mapping editor, use these values in the Options tab:
Field
Value
When to Update
No Update
Transfer Mode
Data Only
See Creating distributed mappings and Distributed transfer scenario.

2. Create a distributed mapping named Acme ProdInfoArch W to T between the Acme
Product Info Archive forms on the sanfrancisco and toronto servers.
In the Distributed Mapping editor, use these values in the Optionstab:
Page 1923 of 4705
Home
Field
Value
When to Update
No Update
Transfer Mode
Data Only

3. Create a filter with two DSO Transfer actions.
Both actions should execute on Submit and Modify. Use the following action names. No
qualification is necessary.
Action 1
Acme ProdInfoArch W to E
Action 2
Acme ProdInfoArch W to T
Use the same filter to transfer requests from the sanfrancisco server to the chicago server
and from the sanfrancisco server to the toronto server. Define the transfers as separate
filter actions, which execute in order when the criteria on sanfrancisco is met.
4. Test the broadcast by creating some requests in the Acme Product Info Archive form on the
sanfrancisco server.
Data-only copies of the requests should appear in the Acme Product Info Archive forms on
the chicago and toronto servers.
Broadcasting distributed mappings and pools

To manage your DSO implementation from a central location, you can broadcast distributed
mappings and pools to other AR System servers that participate in distributed transfers and returns.
This helps ensure that the appropriate mappings are available where and when they need to be.
For example, on the sanfrancisco server, you can create distributed mappings for the Distributed
Mapping and Distributed Pool forms. Then, you can broadcast those mappings to the chicago and
toronto servers.
To broadcast distributed mappings

1. On the sanfrancisco server, create a distributed mapping named Distributed Mapping:
sanfrancisco to chicago between the Distributed Mapping forms on the sanfrancisco and
chicago servers. In the Distributed Mapping editor, use these values:
Panel
Item
Value
Basic
From Server Name field
sanfrancisco
From Form Name field
Distributed Mapping
To Server Name field
chicago
To Form Name field
Distributed Mapping
When to Update field
Immediately
Options
Page 1924 of 4705
Home
Transfer Mode field
Data Only
Transfer to Target
Auto Map dialog box
Match Names (select)
Return from Target
Auto Map dialog box
Match Names (select)

2. On the sanfrancisco server, create a distributed mapping named Distributed Mapping:
sanfrancisco to toronto between the Distributed Mapping forms on the sanfrancisco and
torontoservers. In the Distributed Mapping editor, use these values:
Panel
Item
Value
Basic
From Server Name field
sanfrancisco
From Form Name field
Distributed Mapping
To Server Name field
toronto
To Form Name field
Distributed Mapping
When to Update field
Immediately
Transfer Mode field
Data Only
Transfer to Target
Auto Map dialog box
Match IDs (select)
Return from target
Auto Map dialog box
Match IDs (select)
Options

3. Create a filter with two DSO Transfer actions.
Both actions should execute on Submit and Modify. Use the following action names. No
qualification is necessary.
Action 1
Distributed Mapping: sanfrancisco to chicago
Action 2
Distributed Mapping: sanfrancisco to toronto
Use the same filter to transfer requests from the sanfrancisco server to the chicago server
and from the sanfrancisco server to the toronto server. Define the transfers as separate
filter actions, which execute in order when the criteria on the sanfrancisco server is met.
4. Test the broadcast by creating or modifying a distributed mapping on
thesanfranciscoserver.Data-only copies of the requests should appear in the Distributed
Mapping forms on the chicago and toronto servers.
5. To broadcast distributed mappings for the Distributed Pool form from the sanfrancisco
server to the chicago and toronto servers, repeat step 1 through step 4 for the Distributed
Pool form.
Distributed Server Administration program

In this topic:
Overwriting distributed fields scenario
Page 1925 of 4705
Home
The data in many distributed fields is system-generated (DSO sets their values). You cannot
manually change the values of such fields in a request. The ardist program, however, enables you
to overwrite the values in these distributed fields:
From Form
From Mapping
From Pool
From Server
Master Flag
Warning
The ardist program simply edits field values in a specified request. It does not distribute
data between forms and should not be considered a command-line version of DSO.
The following table lists the ardist command-line arguments.
Note
If you use corresponding uppercase and lowercase arguments in the same command line,
such as*-m 1 -M*, the field value is set to NULL.
Command-line arguments for ardist

Argument
Description
Sets the From Form field to NULL. This is a flag; do not assign it a value.
-C
Sets the From Form field value. Use this to change the source form name.
-c
-d
Runs the program in Debug mode, printing debug information to the terminal. This is a flag; do not assign a value to
it.
Specifies the ID of the request to modify.

-e
Specifies the directory in which the AR System server is installed.

-i
Page 1926 of 4705
Home
Argument

Description
Sets the From Pool field to NULL. This is a flag; do not assign it a value.
-L
Sets the From Pool field value. Use this to change the source pool name.
-l
Sets the Master Flag field to NULL. This is a flag; do not assign it a value.
-M
-m
Sets the Master Flag field to the specified value (1 = Yes, 0 = No). Use this if your transfer gives you zero or multiple
requests with ownership.
Sets the From Mapping field to NULL. This is a flag; do not assign it a value.
-P
Sets the From Mapping field value. Use this to change the mapping name.
-p
Sets the From Server field to NULL. This is a flag; do not assign it a value.
-R
Sets the From Server field value. Use this to change the source server name.
-r
Specifies the name of the form containing the request to modify.

-s
Specifies the name of the server on which the form ( -s ) containing the request to modify resides.
-x
Overwriting distributed fields scenario

In the Acme Product Info Archive form on the chicago server, this example procedure sets the
following field values in request ID 1234567:
Field
Value set by ardist example command
From Form
Acme West Bug Tracking
Master Flag
NULL
From Mapping
Acme ProdInfoArch W to E
Page 1927 of 4705
Home
Field
Value set by ardist example command
From Server
sanfrancisco
To overwrite distributed fields in a specified request

1. Perform one of these actions:
In Windows, open a DOS session.
In UNIX, go to step 3.
2. Change to the ARSystemServerInstallDir directory containing ardist.
3. At the prompt, enter this command:
ardist -i <ARSystemServerInstallDir> -c "Acme West Bug Tracking"

-e 1234567 -M -p "Acme ProdInfoArch W to E"
-r sanfrancisco -s "Acme Product Info Archive" -x chicago
Managing request IDs in distributed environments

In this topic:
Preventing duplicate request IDs
Handling duplicate request IDs
Using qualifications to match requests
The request ID is the piece of data that you are most likely to use to identify and track requests. It
should be unique. In BMC Remedy AR System, requests generated on the same server have
unique IDs. But requests generated on different servers might have identical IDs. Such duplicate
request IDs create conflicts when requests are transferred or shared between servers in distributed
environments.
Preventing duplicate request IDs

The best way to avoid creating duplicate request IDs in a distributed environment is to assign
server-specific prefixes to request IDs. For example, you might add the prefix SAN to the IDs of all
requests created on the sanfrancisco server.
For information about assigning prefixes to request IDs, see Changing the Request ID field length
or prefix.
Handling duplicate request IDs

The Distributed Server Option performs one of these actions when it encounters duplicate request
IDs:
Generates an error message and does not perform the distributed operation
Generates a new request ID for the newer copy of the request
Page 1928 of 4705
Home
Overwrites the older copy of the request with the newer copy
By default, the overwrite action updates only the mapped fields on the target request, but
you can configure this action to update all the fields on the target request.
See Overwriting all fields in duplicate requests.
When you create a distributed mapping, you must specify how it handles duplicate request
IDs. If possible, treat all mappings the same. Using different strategies can cause
administrative problems when data is tracked.
Using qualifications to match requests

By default, DSO uses request IDs to match requests in source forms with requests in target forms.
You can, however, use qualifications based on fields in the source and target forms. See Creating
distributed mappings.
For example, matching qualifications are useful when you do not want to use request ID prefixes to
distinguish requests from one another. In this case, use a data field other than Request ID that
uniquely identifies each request. BMC Remedy AR System can use that field to match a request in
the target form (if one exists) with one in the source form.
Note
You should create a unique index on the data field used to distinguish one request from
another.
Overwriting all fields in duplicate requests

When you specify the Overwrite action for handling duplicate request IDs (see Duplicate Request
ID Action), the default behavior updates only the mapped fields on the target request. This section
explains how to configure the Overwrite action to overwrite all the fields in the target request. (
Mapped fields are updated and unmapped fields are set to NULL.)
For more information, see Request IDs in distributed environments.
To overwrite all fields in duplicate request IDs

1. Stop the BMC Remedy Action Request System Server serverName service.
2. Open the appropriate AR System server configuration file:
(Windows) ARSystemInstallDir\Conf\ar.cfg
(UNIX) ARSystemInstallDir/conf/ar.conf
3. Enter the following flag to update mapped fields and to set unmapped fields to NULL:
DSO-Merge-DupID-Overwrite:
Page 1929 of 4705
Home
4. Save the AR System server configuration file.

5. Restart the BMC Remedy Action Request System Server serverName service.
Capturing server events for workflow or API

calls
The Server Events form enables you to capture server-related activities and use them in workflow
and API programs. You can select the server events that you want to record, search and view the
returned entries, and create workflow to notify companion servers and interested clients of server
changes that might affect them. To access this form, in a browser, open the BMC Remedy AR
System Administration Console, and click System > General > Review Server Events.
Note
For information about setting Server Event options, see Setting server logging options.

Understanding the Server Events form
How the Server Events form is created
Types of events you can record
Viewing the server changes you recorded
Using server events in workflow
Understanding the Server Events form

The Server Events form captures the server changes that you record. To access this form in a
browser, open the BMC Remedy AR System Administration Console and click System > General >
Review Server Events.
You can use the Server Events form to notify other servers of cache changes if multiple servers are
sharing the same database. The form can also notify interested clients of cache changes and user
or group events. For more information, see Using server events in workflow.
Note
You might find server events especially helpful in a load-balanced environment. However,
with the server groups feature, you do not need to use server events as part of the
mechanism for communicating between servers in a load-balanced environment. For
more information, see Configuring a hardware load balancer with BMC Remedy AR
System.
Page 1930 of 4705
Home
With the options on the Server Events tab of the BMC Remedy AR System Administration: Server
Information form, you can specify which activities to record to the form. For more information about
selecting Server Events options, see Setting server logging options.
The Server Events form is similar to other BMC Remedy AR System forms. You can add fields and
workflow to it, but you cannot delete the reserved fields, which are discussed in the following
section.
How the Server Events form is created

The Server Events form is created automatically by the server and contains the following reserved
fields:
800 AR_RESERV_SVR_EVENT_TYPE
801 AR_RESERV_SVR_EVENT_CAUSE
802 AR_RESERV_SVR_EVENT_DETAILS_1
These fields distinguish the Server Events form from all other forms. Only one Server Events form
can exist in the AR System database; therefore, only one form contains these reserved fields.
The Server Events form can be created as follows:
Case 1: When the server starts, the server creates the Server Events form automatically if
the form does not already exist in the BMC Remedy AR System database. If you delete the
Server Events form, the server automatically regenerates the form the next time the server is
started.
Case 2: If you create your own Server Events form, you must supply default values with the
correct data type for the required core fields. If the Server Events form already exists and
you try to create a form with the reserved fields, the server returns an error when you try to
save the form. Error checking does not allow the existence of more than one Server Events
form.
You can modify the Server Events form by using BMC Remedy Developer Studio or a driver. You
can rename the Server Events form; however, if any of the reserved fields is removed, the form is
no longer a valid Server Events form.
Types of events you can record

The following table lists the types of server events you can record.
Events you can record
Page 1931 of 4705
Home
Object
Example
For more
information
Changes to server objects (such as forms, filters,
The AR System server records the API calls that
Viewing server object
active links, escalations, fields, VUIs, char menus,

and containers)
cause server object changes
changes
Changes to users, groups, applications, and roles

User added, modified, or deleted using the
User or Group form
User or group changes using the arcache
Viewing user, group,

application, and role
changes
utility
User or group changes using the
arreload utility Role added, modified, or
deleted using the Roles form
Application added, modified, or deleted
Changes to server settings
Alert users when server settings change
Viewing server setting

changes
Alert registration
Alert users who are registered or deregistered
Viewing alert
registration activity
Archive activity
Alert users of archive activity
Viewing archive
activity
Server group activity
A server in a server group fails and another

server takes over
Viewing server group

actions
Client Timeout
A client timed out before the server could respond

.
Viewing client timeout

server event details
Viewing the server changes you recorded

When you search for or view entries recorded in the Server Events form, you see numbers and raw
data in the fields. Only the numeric values for Event Type and Event Cause are returned, and only
a brief description is provided in the Event Details field. For example, if you recorded the server
events associated with adding a user, a search on the Server Events form looks similar to the
screen in the following figure.
Adding a user
Page 1932 of 4705
Home
The #define statements for the event types in ar.h are:

#define AR_SVR_EVENT_CHG_SCHEMA
#define AR_SVR_EVENT_CHG_FIELD
#define AR_SVR_EVENT_CHG_CHARMENU
#define AR_SVR_EVENT_CHG_FILTER
#define AR_SVR_EVENT_CHG_IMPORT
#define AR_SVR_EVENT_CHG_ACTLINK
#define AR_SVR_EVENT_CHG_ESCAL
#define AR_SVR_EVENT_CHG_VUI
#define AR_SVR_EVENT_CHG_CONTAINER
#define AR_SVR_EVENT_CHG_USERS
10
#define AR_SVR_EVENT_CHG_GROUPS
11
#define AR_SVR_EVENT_CHG_SVR_SETTINGS
12
#define AR_SVR_EVENT_CHG_ALERT_USERS
13
#define AR_SVR_EVENT_ARCHIVE_DONE
14
#define AR_SVR_EVENT_SERVGROUP_ACTION
15
#define AR_SVR_EVENT_CHG_LICENSES
16
#define AR_SVR_EVENT_DYNAMIC_PERM
17
#define AR_SVR_EVENT_CHG_IMAGE
18
Page 1933 of 4705
Home
Use the tables in the following topics to look up the description that corresponds to the type number
and cause number of the server event for which you need information.
Viewing server object changes
Viewing user, group, application, and role changes
Viewing server setting changes
Datatypes values
Viewing alert registration activity
Viewing archive activity
Viewing server group actions
Viewing hierarchical group actions
Viewing client timeout server event details
Viewing server object changes

The following information appears in the fields on the Server Events form when an object change is
recorded:
Event Type: 1 to 9 (depending on the type of object change being recorded)
Event Cause: RPC call number of the API call
Event Details 1: Contents depend on the server object being recorded
Request ID: The unique number assigned to identify the entry
Event Date: Time and date that the event occurred
Submitter: User who caused the server object event
In the Event Details 1 field, the object names recorded for the Set calls are the names of the
objects before the Set operation. Therefore, if an ARSetSchema call renames the form from AA to
BB, AA is the form name recorded in the Event Details field for the server event.
For "Set" API calls, if the name of the object is changed, the Event Details 2 field contains the old
name of the object, and the Event Details 1 field contains the new name. If the name is not
changed by the Set call, the Event Details 2 field contains a NULL datatype.
In the Event Details fields, semicolons separate multiple items. No spaces follow the semicolon.
The string recorded in the Event Details fields can have maximum lengths of 255 bytes (
AR_MAX_SVR_EVENT_DETAILS ), not including the NULL. If the value to record in the Event
Details fields exceed the maximum, the value is truncated.
Note
In the following table, Causes 0 and 1 refer to the import operation.
Page 1934 of 4705
Home
Server object changes

Type
Cause
Cause Description
Event Details 1
Event Details 2
0 or 8
ARSetSchema
form name
1 or 9
ARCreateSchema
form name
10
ARDeleteSchema
form name
0 or 13
ARSetField
field ID; field name
form name
1 or 14
ARCreateField
form name
43
ARDeleteField
form name
56
ARDeleteMultipleFields
field ID; field ID; ...; field ID
form name
151
ARCreateMultipleFields
field ID; field ID; ...; field ID
form name
152
ARSetMultiple Fields
field ID;field ID;...;field ID
form name
0 or 17
ARSetCharMenu
menu name
1 or 18
ARCreateCharMenu
menu name
19
ARDeleteCharMenu
menu name
0 or 22
ARSetFilter
filter name
1 or 23
ARCreateFilter
filter name
24
ARDeleteFilter
filter name
35
ARImport
0 or 39
ARSetActiveLink
active link name
1 or 40
ARCreateActiveLink
active link name
41
ARDeleteActiveLink
active link name
0 or 49
ARSetEscalation
escalation name
1 or 50
ARCreateEscalation
escalation name
51
ARDeleteEscalation
escalation name
0 or 63
ARSetVUI
vui ID;vui name
form name
1 or 64
ARCreateVUI
vui ID;vui name
form name
65
ARDeleteVUI
vui ID;vui name
form name
0 or 75
ARSetContainer
container name
1 or 76
ARCreateContainer
container name
77
ARDeleteContainer
container name
Event Details 3
old form name
old form name
old menu name
old filter name
old active link name
old escalation name
old vui name
old container name
Viewing user, group, application, and role changes

The following information appears in the fields on the Server Events form when a user change is
recorded:
Page 1935 of 4705
Home
Event Type: 10
Event Cause: User added (0), modified (1), or deleted (2)
Event Details 1: Entry ID of the user and the user login name
Event Details 2: Unused
Request ID: The unique number assigned to identify a particular request
Submitter: User who caused the user change event
The following information appears in the fields on the Server Events form when a group, application
, or role change is recorded:
Event Type: 11
Event Cause: Group, application, or role that was added (0), modified(1), or deleted(2)
Event Details 1: Entry ID of the group and the group name; or application name; or entry ID
of the role
Request ID: The unique number assigned to the entry in the Server Events form
Submitter: User who caused the group change event
On the User form, the value in the Event Details 1 field for the user login name is the value in
reserved Field 101. For the Group form, the value for the group name is the value in reserved Field
105.
When a user login name or group name is modified, the name recorded in the Event Details 1 field
is the name after it is modified. For example, if an ARSetEntry is called to change the user's login
name from YY to ZZ, ZZ is recorded as the user's login name in the Event Details 1 field.
User and group, application, and role changes
Type
Cause
Cause Description
Event Details 1
10
User added
entry ID;user login name
10
User modified
10
User deleted
11
Group added
entry ID;group name
11
Group modified
entry ID;group name
11
Group deleted
entry ID;group name
11
Computed Group added
entry ID;group name
Page 1936 of 4705
Home
Type
Cause
Cause Description
Event Details 1
11
Computed Group modified
entry ID;group name
11
Computed Group deleted
entry ID;group name
11
Application added
application name
11
Application modified
application name
11
Application deleted
application name
11
Role added
entry ID
11
10
Role modified
entry ID
11
11
Role deleted
entry ID
Viewing server setting changes

The following information appears in the fields on the Server Events form when a server setting
change is recorded:
Event Type: 12
Event Cause: The numeric value of the server option AR_SVR_INFO_XX
Event Details 1: The input datatype and input value to the SetServerInfo call (For more
information, see Datatypes values.)
Submitter: User who called SetServerInfo
For the following server options, the input password is replaced with an arbitrary number of
asterisks before storing it in the Event Details 1 field:
AR_SERVER_INFO_DB_PASSWORD
AR_SERVER_INFO_DSO_USER_PASSWD
AR_SERVER_INFO_DSO_TARGET_PASSWD
AR_SERVER_INFO_APP_SERVICE_PASSWD
AR_SERVER_INFO_MID_TIER_PASSWD
AR_SERVER_INFO_REM_WKFLW_PASSWD
AR_SERVER_INFO_REM_WKFLW_TARGET_PASSWD
AR_SERVER_INFO_PLUGIN_PASSWD
AR_SERVER_INFO_PLUGIN_TARGET_PASSWD
The datatype is included in the Event Details 1 field because AR_DATA_TYPE_NULL does not
have a value, only the datatype.
Page 1937 of 4705
Home
An ARImport API call can result in many server object changes, but this event is recorded as one
server event. Therefore, even though one Import call can add or modify several forms, filters, and
active links, the server records these changes as an Import object change event, and the Cause
field contains the RPC call number of ARImport.
Server setting changes
Type
Cause
Cause Description
Event Details 1
12
AR_SERVER_INFO_ALLOW_GUESTS
datatype;value
12
AR_SERVER_INFO_USE_ETC_PASSWD
datatype;value
12
AR_SERVER_INFO_XREF_PASSWORDS
datatype;value
12
AR_SERVER_INFO_DEBUG_MODE
datatype;value
12
10
AR_SERVER_INFO_DB_PASSWORD
datatype;value
12
15
AR_SERVER_INFO_SET_PROC_TIME
datatype;value
12
16
AR_SERVER_INFO_EMAIL_FROM
datatype;value
12
17
AR_SERVER_INFO_SQL_LOG_FILE
datatype;value
12
19
AR_SERVER_INFO_FLOAT_TIMEOUT
datatype;value
12
20
AR_SERVER_INFO_UNQUAL_QUERIES
datatype;value
12
21
AR_SERVER_INFO_FILTER_LOG_FILE
datatype;value
12
22
AR_SERVER_INFO_USER_LOG_FILE
datatype;value
12
28
AR_SERVER_INFO_MAX_ENTRIES
datatype;value
12
31
AR_SERVER_INFO_ESCALATION_LOG_FILE
datatype;value
12
33
AR_SERVER_INFO_SUBMITTER_MODE
datatype;value
12
34
AR_SERVER_INFO_API_LOG_FILE
datatype;value
12
37
AR_SERVER_INFO_FTEXT_TIMEOUT
datatype;value
12
45
AR_SERVER_INFO_DS_RPC_SOCKET
datatype;value
12
46
AR_SERVER_INFO_DS_LOG_FILE
datatype;value
12
47
AR_SERVER_INFO_SUPPRESS_WARN
datatype;value
12
50
AR_SERVER_INFO_SAVE_LOGIN
datatype;value
12
56
AR_SERVER_INFO_ADMIN_ONLY
datatype;value
12
57
AR_SERVER_INFO_CACHE_LOG_FILE
datatype;value
12
59
AR_SERVER_INFO_THREAD_LOG_FILE
datatype;value
12
65
AR_SERVER_INFO_TCD_TCP_PORT
datatype;value
12
66
AR_SERVER_INFO_DSO_DEST_PORT
datatype;value
12
78
AR_SERVER_INFO_NFY_TCP_PORT
datatype;value
Page 1938 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
79
AR_SERVER_INFO_FILT_MAX_TOTAL
datatype;value
12
80
AR_SERVER_INFO_FILT_MAX_STACK
datatype;value
12
81
AR_SERVER_INFO_DEFAULT_ORDER_BY
datatype;value
12
82
AR_SERVER_INFO_DELAYED_CACHE
datatype;value
12
83
AR_SERVER_INFO_DSO_MERGE_STYLE
datatype;value
12
84
AR_SERVER_INFO_EMAIL_LINE_LEN
datatype;value
12
85
AR_SERVER_INFO_EMAIL_SYSTEM
datatype;value
12
86
AR_SERVER_INFO_INFORMIX_RELAY_MOD
datatype;value
12
87
AR_SERVER_INFO_PS_RPC_SOCKET
datatype;value
12
88
AR_SERVER_INFO_REGISTER_PORTMAPPER
datatype;value
12
89
AR_SERVER_INFO_SERVER_NAME
datatype;value
12
90
AR_SERVER_INFO_DBCONF
datatype;value
12
92
AR_SERVER_INFO_AP_RPC_SOCKET
datatype;value
12
93
AR_SERVER_INFO_AP_LOG_FILE
datatype;value
12
94
AR_SERVER_INFO_AP_DEFN_CHECK
datatype;value
12
95
AR_SERVER_INFO_MAX_LOG_FILE_SIZE
datatype;value
12
96
AR_SERVER_INFO_CLUSTERED_INDEX
datatype;value
12
97
AR_SERVER_INFO_ACTLINK_DIR
datatype;value
12
98
AR_SERVER_INFO_ACTLINK_SHELL
datatype;value
12
99
AR_SERVER_INFO_USER_CACHE_UTILS
datatype;value
12
100
AR_SERVER_INFO_EMAIL_TIMEOUT
datatype;value
12
102
AR_SERVER_INFO_ENCRYPT_AL_SQL
datatype;value
12
103
AR_SERVER_INFO_SCC_ENABLED
datatype;value
12
104
AR_SERVER_INFO_SCC_PROVIDER_NAME
datatype;value
12
105
AR_SERVER_INFO_SCC_TARGET_DIR
datatype;value
12
106
AR_SERVER_INFO_SCC_COMMENT_CHECKIN
datatype;value
12
107
AR_SERVER_INFO_SCC_COMMENT_CHECKOUT
datatype;value
12
108
AR_SERVER_INFO_SCC_INTEGRATION_MODE
datatype;value
12
109
AR_SERVER_INFO_EA_RPC_SOCKET
datatype;value
12
110
AR_SERVER_INFO_EA_RPC_TIMEOUT
datatype;value
12
111
AR_SERVER_INFO_USER_INFO_LISTS
datatype;value
12
112
AR_SERVER_INFO_USER_INST_TIMEOUT
datatype;value
12
113
AR_SERVER_INFO_DEBUG_GROUPID
datatype;value
Page 1939 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
114
AR_SERVER_INFO_APPLICATION_AUDIT
datatype;value
12
115
AR_SERVER_INFO_EA_SYNC_TIMEOUT
datatype;value
12
117
AR_SERVER_INFO_SVR_SEC_CACHE
datatype;value
12
118
AR_SERVER_INFO_LOGFILE_APPEND
datatype;value
12
119
AR_SERVER_INFO_MINIMUM_API_VER
datatype;value
12
120
AR_SERVER_INFO_MAX_AUDIT_LOG_FILE_SIZE
datatype;value
12
121
AR_SERVER_INFO_CANCEL_QUERY
datatype;value
12
122
AR_SERVER_INFO_MULT_ASSIGN_GROUPS
datatype;value
12
123
AR_SERVER_INFO_ARFORK_LOG_FILE
datatype;value
12
124
AR_SERVER_INFO_DSO_PLACEHOLDER_MODE
datatype;value
12
125
AR_SERVER_INFO_DSO_POLLING_INTERVAL
datatype;value
12
126
AR_SERVER_INFO_DSO_SOURCE_SERVER
datatype;value
12
128
AR_SERVER_INFO_DSO_TIMEOUT_NORMAL
datatype;value
12
130
AR_SERVER_INFO_ENC_DATA_KEY_EXP
datatype;value
12
131
AR_SERVER_INFO_ENC_PUB_KEY_EXP
datatype;value
12
132
AR_SERVER_INFO_ENC_DATA_ENCR_ALG
datatype;value
12
133
AR_SERVER_INFO_ENC_SEC_POLICY
datatype;value
12
134
AR_SERVER_INFO_ENC_SESS_H_ENTRIES
datatype;value
12
135
AR_SERVER_INFO_DSO_TARGET_CONNECTION
datatype;value
12
136
AR_SERVER_INFO_PREFERENCE_PRIORITY
datatype;value
12
137
AR_SERVER_INFO_ORACLE_QUERY_ON_CLOB
datatype;value
12
140
AR_SERVER_INFO_LOCALIZED_SERVER
datatype;value
12
141
AR_SERVER_INFO_SVR_EVENT_LIST
datatype;value
12
142
AR_SERVER_INFO_DISABLE_ADMIN_OPERATIONS
datatype;value
12
143
AR_SERVER_INFO_DISABLE_ESCALATIONS
datatype;value
12
144
AR_SERVER_INFO_ALERT_LOG_FILE
datatype;value
12
145
AR_SERVER_INFO_DISABLE_ALERTS
datatype;value
12
146
AR_SERVER_INFO_CHECK_ALERT_USERS
datatype;value
12
147
AR_SERVER_INFO_ALERT_SEND_TIMEOUT
datatype;value
12
148
AR_SERVER_INFO_ALERT_OUTBOUND_PORT
datatype;value
12
151
AR_SERVER_INFO_DSO_USER_PASSW
datatype;value
12
152
AR_SERVER_INFO_DSO_TARGET_PASSWD
datatype;value
12
153
AR_SERVER_INFO_APP_SERVICE_PASSWD
datatype;value
Page 1940 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
154
AR_SERVER_INFO_MID_TIER_PASSWD
datatype;value
12
155
AR_SERVER_INFO_PLUGIN_LOG_FILE
datatype;value
12
156
AR_SERVER_INFO_SVR_STATS_REC_MOD
datatype;value
12
157
AR_SERVER_INFO_SVR_STATS_REC_INTERVAL
datatype;value
12
158
AR_SERVER_INFO_DEFAULT_WEB_PATH
datatype;value
12
159
AR_SERVER_INFO_FILTER_API_RPC_TIMEOUT
datatype;value
12
160
AR_SERVER_INFO_DISABLED_CLIENT
datatype;value
12
161
AR_SERVER_INFO_PLUGIN_PASSWD
datatype;value
12
162
AR_SERVER_INFO_PLUGIN_ALIAS
datatype;value
12
163
AR_SERVER_INFO_PLUGIN_TARGET_PASSWD
datatype;value
12
164
AR_SERVER_INFO_REM_WKFLW_PASSWD
datatype;value
12
165
AR_SERVER_INFO_REM_WKFLW_TARGET_PASSWD
datatype;value
12
166
AR_SERVER_INFO_EXPORT_SVR_OPS
datatype;value
12
167
AR_SERVER_INFO_INIT_FORM
datatype;value
12
168
AR_SERVER_INFO_ENC_PUB_KEY_ALG
datatype;value
12
169
AR_SERVER_INFO_IP_NAMES
datatype;value
12
170
AR_SERVER_INFO_DSO_CACHE_CHK_INTERVAL
datatype;value
12
171
AR_SERVER_INFO_DSO_MARK_PENDING_RETRY
datatype;value
12
172
AR_SERVER_INFO_DSO_RPCPROG_NUM
datatype;value
12
173
AR_SERVER_INFO_DELAY_RECACHE_TIME
datatype;value
12
174
AR_SERVER_INFO_DFLT_ALLOW_CURRENCIES
datatype;value
12
175
AR_SERVER_INFO_CURRENCY_INTERVAL
datatype;value
12
176
AR_SERVER_INFO_ORACLE_CURSOR_SHARE
datatype;value
12
179
AR_SERVER_INFO_DFLT_FUNC_CURRENCIES
datatype;value
12
180
AR_SERVER_INFO_EMAIL_IMPORT_FORM
datatype;value
12
181
AR_SERVER_INFO_EMAIL_AIX_USE_OLD_EMAIL
datatype;value
12
182
AR_SERVER_INFO_TWO_DIGIT_YEAR_CUTOFF
datatype;value
12
183
AR_SERVER_INFO_ALLOW_BACKQUOTE_IN_PROCESS
datatype;value
12
184
AR_SERVER_INFO_DB_CONNECTION_RETRIES
datatype;value
12
189
AR_SERVER_INFO_HOMEPAGE_FORM
datatype;value
12
190
AR_SERVER_INFO_DISABLE_FTS_INDEXER
datatype;value
12
191
AR_SERVER_INFO_DISABLE_ARCHIVE
datatype;value
12
192
AR_SERVER_INFO_SERVERGROUP_MEMBER
datatype;value
Page 1941 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
193
AR_SERVER_INFO_SERVERGROUP_LOG_FILE
datatype;value
12
194
AR_SERVER_INFO_FLUSH_LOG_LINES
datatype;value
12
195
AR_SERVER_INFO_SERVERGROUP_INTERVAL
datatype;value
12
196
AR_SERVER_INFO_JAVA_VM_OPTIONS
datatype;value
12
197
AR_SERVER_INFO_PER_THREAD_LOGS
datatype;value
12
199
AR_SERVER_INFO_SSTABLE_CHUNK_SIZE
datatype;value
12
202
AR_SERVER_INFO_SERVERGROUP_NAME
datatype;value
12
204
AR_SERVER_INFO_LOCKED_WKFLW_LOG_MODE
datatype;value
12
207
AR_SERVER_INFO_PLUGIN_LOOPBACK_RPC
datatype;value
12
208
AR_SERVER_INFO_CACHE_MODE
datatype;value
12
210
AR_SERVER_INFO_GENERAL_AUTH_ERR
datatype;value
12
211
AR_SERVER_INFO_AUTH_CHAINING_MODE
datatype;value
12
212
AR_SERVER_INFO_RPC_NON_BLOCKING_IO
datatype;value
12
213
AR_SERVER_INFO_SYS_LOGGING_OPTIONS
datatype;value
12
214
AR_SERVER_INFO_EXT_AUTH_CAPABILITIES
datatype;value
12
215
AR_SERVER_INFO_DSO_ERROR_RETRY
datatype;value
12
216
AR_SERVER_INFO_PREF_SERVER_OPTION
datatype;value
12
217
AR_SERVER_INFO_FTINDEXER_LOG_FILE
datatype;value
12
218
AR_SERVER_INFO_EXCEPTION_OPTION
datatype;value
12
219
AR_SERVER_INFO_ERROR_EXCEPTION_LIST
datatype;value
12
220
AR_SERVER_INFO_DSO_MAX_QUERY_SIZE
datatype;value
12
221
AR_SERVER_INFO_ADMIN_OP_TRACKING
datatype;value
12
223
AR_SERVER_INFO_PLUGIN_DEFAULT_TIMEOUT
datatype;value
12
224
AR_SERVER_INFO_EA_IGNORE_EXCESS_GROUPS
datatype;value
12
225
AR_SERVER_INFO_EA_GROUP_MAPPING
datatype;value
12
226
AR_SERVER_INFO_PLUGIN_LOG_LEVEL
datatype;value
12
227
AR_SERVER_INFO_FT_THRESHOLD_LOW
datatype;value
12
228
AR_SERVER_INFO_FT_THRESHOLD_HIGH
datatype;value
12
229
AR_SERVER_INFO_NOTIFY_WEB_PATH
datatype;value
12
230
AR_SERVER_INFO_DISABLE_NON_UNICODE_CLIENTS
datatype;value
12
231
AR_SERVER_INFO_FT_COLLECTION_DIR
datatype;value
12
232
AR_SERVER_INFO_FT_CONFIGURATION_DIR
datatype;value
12
233
AR_SERVER_INFO_FT_TEMP_DIR
datatype;value
Page 1942 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
234
AR_SERVER_INFO_FT_REINDEX
datatype;value
12
235
AR_SERVER_INFO_FT_DISABLE_SEARCH
datatype;value
12
236
AR_SERVER_INFO_FT_CASE_SENSITIVITY
datatype;value
12
237
AR_SERVER_INFO_FT_SEARCH_MATCH_OP
datatype;value
12
238
AR_SERVER_INFO_FT_STOP_WORDS
datatype;value
12
239
AR_SERVER_INFO_FT_RECOVERY_INTERVAL
datatype;value
12
240
AR_SERVER_INFO_FT_OPTIMIZE_THRESHOLD
datatype;value
12
241
AR_SERVER_INFO_MAX_PASSWORD_ATTEMPTS
datatype;value
12
242
AR_SERVER_INFO_GUESTS_RESTRICT_READ
datatype;value
12
243
AR_SERVER_INFO_ORACLE_CLOB_STORE_INROW
datatype;value
12
244
AR_SERVER_INFO_NEXT_ID_BLOCK_SIZE
datatype;value
12
245
AR_SERVER_INFO_NEXT_ID_COMMIT
datatype;value
12
246
AR_SERVER_INFO_RPC_CLIENT_XDR_LIMIT
datatype;value
12
247
AR_SERVER_INFO_CACHE_DISP_PROP
datatype;value
12
248
AR_SERVER_INFO_USE_CON_NAME_IN_STATS
datatype;value
12
249
AR_SERVER_INFO_DB_MAX_ATTACH_SIZE
datatype;value
12
250
AR_SERVER_INFO_DB_MAX_TEXT_SIZE
datatype;value
12
251
AR_SERVER_INFO_GUID_PREFIX
datatype;value
12
252
AR_SERVER_INFO_MULTIPLE_ARSYSTEM_SERVERS
datatype;value
12
253
AR_SERVER_INFO_ORACLE_BULK_FETCH_COUNT
datatype;value
12
254
AR_SERVER_INFO_MINIMUM_CMDB_API_VER
datatype;value
12
255
AR_SERVER_INFO_PLUGIN_PORT
datatype;value
12
256
AR_SERVER_INFO_PLUGIN_LIST
datatype;value
12
257
AR_SERVER_INFO_PLUGIN_PATH_LIST
datatype;value
12
258
AR_SERVER_INFO_SHARED_LIB
datatype;value
12
259
AR_SERVER_INFO_SHARED_LIB_PATH
datatype;value
12
260
AR_SERVER_INFO_CMDB_INSTALL_DIR
datatype;value
12
261
AR_SERVER_INFO_RE_LOG_DIR
datatype;value
12
262
AR_SERVER_INFO_LOG_TO_FORM
datatype;value
12
272
AR_SERVER_INFO_FIPS_SERVER_MODE
datatype;value
12
273
AR_SERVER_INFO_FIPS_CLIENT_MODE
datatype;value
12
275
AR_SERVER_INFO_ENC_LEVEL
datatype;value
12
277
AR_SERVER_INFO_FIPS_MODE_INDEX
datatype;value
Page 1943 of 4705
Home
Type
Cause
Cause Description
Event Details 1
12
278
AR_SERVER_INFO_FIPS_DUAL_MODE_INDEX
datatype;value
12
279
AR_SERVER_INFO_ENC_LEVEL_INDEX
datatype;value
12
280
AR_SERVER_INFO_DSO_MAIN_POLL_INTERVAL
datatype;value
12
281
AR_SERVER_INFO_RECORD_OBJECT_RELS
datatype;value
12
282
AR_SERVER_INFO_LICENSE_USAGE
datatype;value
12
284
AR_SERVER_INFO_LOG_FORM_SELECTED
datatype;value
12
285
AR_SERVER_INFO_MAX_CLIENT_MANAGED_TRANSACTIONS
datatype;value
12
286
AR_SERVER_INFO_CLIENT_MANAGED_TRANSACTION_TIMEOUT
datatype;value
12
287
AR_SERVER_INFO_OBJ_RESERVATION_MODE
datatype;value
12
288
AR_SERVER_INFO_NEW_ENC_PUB_KEY_EXP
datatype;value
12
289
AR_SERVER_INFO_NEW_ENC_DATA_KEY_EXP
datatype;value
12
290
AR_SERVER_INFO_NEW_ENC_DATA_ALG
datatype;value
12
291
AR_SERVER_INFO_NEW_ENC_SEC_POLICY
datatype;value
12
292
AR_SERVER_INFO_NEW_FIPS_SERVER_MODE
datatype;value
12
293
AR_SERVER_INFO_NEW_ENC_LEVEL
datatype;value
12
294
AR_SERVER_INFO_NEW_ENC_ALGORITHM
datatype;value
12
295
AR_SERVER_INFO_NEW_FIPS_MODE_INDEX
datatype;value
12
296
AR_SERVER_INFO_NEW_ENC_LEVEL_INDEX
datatype;value
12
297
AR_SERVER_INFO_NEW_ENC_PUB_KEY
datatype;value
12
298
AR_SERVER_INFO_CUR_ENC_PUB_KEY
datatype;value
12
299
AR_SERVER_INFO_NEW_ENC_PUB_KEY_INDEX
datatype;value
12
300
AR_SERVER_INFO_CURRENT_ENC_SEC_POLICY
datatype;value
12
301
AR_SERVER_INFO_ENC_LIBRARY_LEVEL
datatype;value
12
302
AR_SERVER_INFO_NEW_FIPS_ALG
datatype;value
12
303
AR_SERVER_INFO_FIPS_ALG
datatype;value
12
304
AR_SERVER_INFO_FIPS_PUB_KEY
datatype;value
12
305
AR_SERVER_INFO_WFD_QUEUES
datatype;value
12
306
AR_SERVER_INFO_VERCNTL_OBJ_MOD_LOG_MODE
datatype;value
12
307
AR_SERVER_INFO_MAX_RECURSION_LEVEL
datatype;value
Datatypes values
For server setting changes, the Event Details 1 field records the datatype and value. The datatype
is recorded as 0, 2, and 4, corresponding to the datatypes in the following table.
Page 1944 of 4705
Home
Datatype
Description
#define in ar.h
NULL
AR_DATA_TYPE_NULL
Integer
AR_DATA_TYPE_INTEGER
Character String
AR_DATA_TYPE_CHAR
Viewing alert registration activity

The following information appears in the fields on the Server Events form when an alert change is
recorded:
Event Type: 13
Event Cause: User registered for alerts (102), user deregistered for alerts (103)
Event Details 1: User login name, IP address of computer user logs into, and other details.
Submitter: User who caused the alert change event
Alert registration activity
Type
Cause
Cause
Description
Event Details 1
13
102
User logs in
to alert
Operation type tag (R);byte length of user name;user name;registration time;IP address of client;
client port;actual client IP address;server IP address that client expected;registration flag;client
client
version;client codeset
User logs
out from
alert client
Operation type tag (U);byte length of user name;user name;IP address of client;client port;client
version
13
103
Viewing archive activity

The following information appears in the fields on the Server Events form when an archive change
is recorded:
Event Type: 14
Event Cause: Copy to archive only (1), delete from source only (2), copy to archive and
delete from source (3)
Event Details 1: Source form name
Event Details 2: Details of the activity
Event Details 3: Destination form name
Page 1945 of 4705
Home

Submitter: User who caused the archive change event
Archive activity
Type
Cause
Cause Description
Event
Details 1
Event Details 2
Event
Details 3
14
Copy to archive only
Source
<Actual number of entries copied to archive> of <Total

number of matches>
Destination
form
name
form name
14
Delete from source

only
Source
form
name
<Actual number of entries deleted from source> of <Total

number of matches>
Destination
form name
14
Copy to archive and

delete from source
Source
form
name
<Actual number of entries copied to archive and deleted

from source> of <Total number of matches>
Destination
form name
Viewing server group actions

The following information appears in the fields on the Server Events form when a server group
activity is recorded:
Event Type: 15
Event Cause: Failover (1), relinquish (2), takeover (3)
Event Details 1: Server performing action
Event Details 2: Name of operation
Event Details 3: Other server
Submitter: User who caused the server group action event
The following table describes specific details of server group actions.
Server group actions
Type
Cause
Cause Description
Event Details 1
Event Details 2
Event Details 3
15
Server in group fails over an

operation
Server that an operation

is failing over to.
Name of the
operation involved
.
Server that an operation is

failing over from.
15
Server in group is
relinquishing an operation
Server relinquishing an
operation.
Name of the
operation involved
Server expected to take over a

relinquished operation.
.
15
Server in group takes over an

unowned operation.
Server taking over an

unowned operation.
Name of the
operation involved
.
Null
Page 1946 of 4705
Home
Viewing hierarchical group actions

The following information appears in the fields on the Server Events form when an event is
associated with hierarchical groups:
Event Type: 17
Event Cause: Start (1), end (2)
Event Details 1: Schema for which the groups are being updated
Event Details 2: Null
Event Details 3: Null
Submitter: User who caused the hierarchical group event
The following table describes specific details of hierarchical groups.
Server group actions
Type
Cause
Cause Description
Event Details 1
Event Details
2
Event Details
3
17
A group command is
initiated
Schema for which the groups are being

initiated
Null
Null
17
A group command is
completed
Schema for which the groups are being

completed
Null
Null
Viewing client timeout server event details

The information provided in the Server Event form is tailored to notifications, with fields that can be
easily used in the qualification and as substitution parameters in the notification text. The following
table shows Server Event form field mapping for the client timeout event:
Field Name
Value
Submitter
User who experienced the timeout
Event Type
19 (#define AR_SVR_EVENT_CLIENT_TIMEOUT 19)
Event Cause
Result code of the API call (0 for no error)
Event Details 1
API call name (for example, ArGetListEntryWithFields)
Event Details 2
Read-only call indicator (0 for API call that updates, 1 for read-only API, in character format)
Event Details 3
Form name if the API call involves a form; otherwise, NULL
Using server events in workflow

Recording server events enables you to communicate internal (non-data) server changes to
processes outside the server and to use workflow to notify companion servers or interested clients
of changes that affect them.
Page 1947 of 4705
Home
You can create workflow that is triggered when a server event is recorded. For example, you might
want to create a filter that fires when an entry is submitted to the Server Events form, indicating that
an object change occurred. The filter should execute a Run Process action that runs the arsignal
program to force a companion AR System server to reload its cache. The filter should have one
such action for each companion server.
To make the machine1 server reload its cache, construct the filter run process action as follows:
arsignal -g machine1
If machine1 was running on specific port 2033, the action would be as follows:
arsignal -g machine1:2033
For more information about arsignal, see arsignal.exe or arsignal.
Managing data
This section contains information about managing your data in BMC Remedy AR System, including
exporting and importing data and definitions, and the AR System database.
Auditing data
Archiving data
File types used in migrations
Importing and exporting Flashboards objects
Exporting and importing data and definitions
Using the Request ID to improve performance or security
SQL definitions of the data dictionary tables
Auditing data
The following topics provide information about auditing:
Auditing changes to data
Supporting compliance audits with BMC Remedy Approval Server
Auditing changes to data

Through auditing, you can keep track of changes to data in any form (except display-only forms).
If you have at least one field configured for auditing on a form, you can record data in a main form
in an audit form or log form when any of the following actions occur:
Page 1948 of 4705
Home
A new entry is created on the form.

An entry is deleted on the form.
Any audit field on the form is modified.
Data is merged into a form.
Auditing requires configuration at the following levels:
Form level Enable auditing for a form, specify an audit style, and specify the name of the
form that will contain the audited data. If the audit form does not exist, BMC Remedy AR
System creates it.
Field level Specify whether a field should be:
Audited A change to this field triggers audit processing.
Copied The field value is copied to the corresponding field in the audit form if the
audit field is triggered. Audit fields that have not changed are not copied.
Audited and copied The field triggers an audit if the field is changed. If it is not
changed, it is still copied.
When you configure a main form for auditing, you specify whether to perform a form-style audit or a
log-style audit. Because BMC Remedy AR System updates the audit forms for both styles, a
special user named AR_AUDITOR performs the audits. This name is displayed in the Last
Modified By field for all audits.
You can selectively audit entries by providing an audit qualification. If the audit qualification fails,
the audit does not occur (even if the values of audit fields have changed).
Form-style audits
Log-style audits
Configuring auditing
Considerations for auditing forms
Assignee Group and other dynamic group fields
Using flag fields to view changes to an individual field
Audit processing and filters
Form-style audits
A form-style audit records data from the main form to an audit form. The audit form:
Is a regular form that serves as the destination for data audited in the main form.
Resides on the same server as the main form.
Contains the same fields as the main form.
Contains several audit-specific fields.
Page 1949 of 4705
Home
When you configure a main form for a form-style audit, you specify a name for the audit form. When
the form is audited, data from the main-form fields configured for auditing is copied to
corresponding fields on the audit form. If there are fields in the main form not configured for auditing
, the corresponding fields on the audit form are left blank.
In this topic:
Audit form characteristics
Audit form fields
Deleting an audit form using an API call
Audit form characteristics

Audit forms have the following characteristics.
General
Any changes to the definitions in the main form (such as adding or deleting a data field) are
applied to the audit form.
You can change the form and view properties of the audit form.
Only an administrator can delete entries.
If the main form belongs to a deployable application, the audit form also belongs to the same
application.
If the main form is made "licensable," then the audit form is also made licensable.
An audit form cannot be further audited, but it can be archived.
Archive forms cannot be audited.
Fields
Data fields, attachment pools, and panel holders cannot be modified or added to an audit
form. All other field types, such as trim, or table, can be added or modified.
Limit information of the fields must be the same as the corresponding fields in the main form.
The permissions for fields on the Audit forms is read access.
Workflow
When an audit form is created, the workflow from the main form is not copied to the audit
form. You can add workflow to an audit form, but workflow cannot modify data in an audit
form.
Import and export

Data can be exported from an audit form, and data can be imported into an audit form, but
existing entries in an audit form cannot be overwritten.
While audited main forms are imported, if the main form is audited Copy style and the audit
form is not found, audit for the main form is disabled and a warning (Form not Found.
ARError 303 ) is returned.
Page 1950 of 4705
Home
During an import in place, if the main form has fields added or deleted, those fields are also
added to the audit form.
If the main form is part of a lock block from an exported definition, the audit form is part of
the same lock block. If a field in the main form is audited after locking the form, the
corresponding flag field is not created. (For more information, see Using flag fields to view
changes to an individual field.)
Audit forms created by BMC Remedy AR System

If BMC Remedy AR System creates an audit form, it has the following additional characteristics:
Any uniqueness constraints (indexes) that exist on the main form are removed from the audit
form. You can add indexes to the audit form.
When the audit form is created, the entry points are cleared. The administrator can add entry
points.
When the audit form is created, the disable status history form property is not copied from
the main form to the audit form. The audit form has status history disabled by default.
All other form properties are copied from the main form to the audit form. However, after the
audit form is created, subsequent changes to the main form properties are not copied to it.
The audit form by itself cannot be imported. Either the main form by itself or both the main
and audit forms can be imported.
When the audit form is created for the first time, all fields (including non-data fields) are
created. After that, if non-data fields are added to the main form, they are not added to the
audit form.
Audit form fields

The data fields in the main form and the audit form have identical field permissions and field limits.
However, you cannot modify field permissions and limits on the audit form.
Important
When you delete multiple fields from the main form, BMC Remedy AR System attempts to
delete those fields from the audit form as well. If any of those fields contains data, none of
them are deleted from the audit form. If the fields are deleted one by one from the main
form, the fields that do not contain data are deleted from the audit form.
Each audit form contains the following audit-specific fields.

Audit form fields
Field name
Description
Action
The actions that triggered the audit. The options are:

2 Set
Page 1951 of 4705
Home
Field name
Description
4 Create
8 Delete
16 Merge
Fields Changed
The database names of the audit fields that changed. The syntax for the list is as follows:
;databaseName;databaseName;databaseName;
User
The user that modified the entry in the main form.
Original Request
ID
The Request ID of the entry being audited.
Audit Date
The date and time when the audit occurred.
Last Modified By
The user who created the entry in the audit form last. ( AR_AUDITOR is always the user who creates the
entries.)
Audit Join Key
Used for join form auditing. BMC Remedy AR System maintains this field.
BMC Remedy AR System does not create these fields as part of any view in the audit form, so you
must add them to the view to use them. (In BMC Remedy Developer Studio, open the audit form,
and choose Form > Add/Remove Fields On View .)
Note
The owner of the non-core fields on the audit form (form style) is set to the owner of the
audit form, not the original form.
Deleting an audit form using an API call

To delete an audit form regardless of whether the main form has auditing turned off or on, or when
deleting an audit form that is part of a Lock block, use the AR_SCHEMA_SHADOW_DELETE
option with the ARDeleteSchema API call.
If the audit form has data, use the ARDeleteSchema API call with both
AR_SCHEMA_DATA_DELETE and AR_SCHEMA_SHADOW_DELETE options. This deletes the
audit form with data.
Log-style audits
A log-style audit records data from the main form into a log form. The log form:
Is a regular form that serves as the destination for data audited in the main form.
Resides on the same server as the main form.
Contains only audit-specific fields. (See Log form fields.)
Page 1952 of 4705
Home
When you configure a main form for a log-style audit, you specify a name for the log form. When a
main form is audited, BMC Remedy AR System copies values from the main form to a text field in
the log form.
Important
A log-style audit form can contain data from multiple main forms.
In this topic:
Log form fields
Log keys
Log form characteristics
Log form fields

The log form does not contain the same fields as the main form. In addition to the core fields, the
log form contains the following fields.
Log form fields
Field name
Description
Action
The actions that triggered the audit. The options are:

2 Set
4 Create
8 Delete
16 Merge
Fields Changed
The database names of the audit fields that changed. The syntax for the list is as follows:
;databaseName;databaseName;databaseName;
User
The user that modified the entry in the main form.
Original Request
ID
The Request ID of the form being audited.
GUID
This field is set if the main form contains a field with ID 179.
Log
A list of field-value pairs that represent the changes to the main form. The syntax is as follows:
fieldName1:fieldValue1
fieldName2:fieldValue2
Form name
The name of the main form.

Fields that help in searching of log entries. See Log keys for more information.
Page 1953 of 4705
Home
Field name
Description
Log Key 1
Log Key 2
Log Key 3
Audit Date
The date and time when the audit occurred.
Last Modified By
The user who created the entry in the audit form last. ( AR_AUDITOR is always be the user who creates the
entries.)
Log keys
When a log form is created, it contains special character fields named Log Key 1, Log Key 2, and
Log Key 3. These fields can help in searching of log entries.
In BMC Remedy Developer Studio, you can set a field to any of these Log Key fields. During an
audit, the value of this field goes to the key that was selected.
Only three keys are available, and you cannot set two fields to the same log key. Also, you cannot
set log keys for diary and attachment fields.
Log form characteristics

Log forms have the following characteristics:
Have a fixed set of fields. (See #Log form fields.)
Do not belong to any application when they are created.
Do not belong to any lock block when they are created.
While audited main forms are imported, if the main form is audited Log style and the Log form is not
found, audit for the main form is turned off and a warning ( Form not Found. ARError 303) is
returned.
Configuring auditing
This section contains information about configuring auditing:
Configuring a form for auditing
Specifying fields to be audited
Table fields in audit forms
Changing character field properties on the main form
Configuring a form for auditing

The following procedure describes how to enable auditing for a form.
Note
Page 1954 of 4705
Home
Do not audit system forms (such as User, Group, Server Statistics, and Server Events)
because these forms use reserved fields that should exist only on the one form in BMC
Remedy AR System.
To enable auditing for a form

1. In BMC Remedy Developer Studio, open the form you want to audit.
2. Click the Definitions tab, and expand the Other Definitions panel and then the Audit panel
.
3. From the Audit Style list, select the type of audit you want to perform:
None No auditing is performed.
Form A snapshot of the audited form is saved to the audit form you specify. Only
the audit and copy fields in the audit form contain values.
Log Whenever a form is saved after an audit field or set of fields changes values,
an entry is created in the log form you specify.
4. From the Audit State field, select Enable.
You can select Disable to disable audit functionality temporarily. Any other audit
configuration values you have specified remain intact.
5. From the Audit Only Changed Fields field, select how the audit function operates when no
field is changed:
Default Use the setting defined in the Configuration tab of the BMC Remedy AR
Yes Auditing occurs only when at least one field value changes as the result of an
operation.
No Auditing occurs whenever there is an operation on the form. Before BMC
Remedy AR System 7.5.00, the server always audited every operation.
6. If you specified a form audit, enter an audit form name in the Audit Form field.
7. If you specified a log audit, enter a log form name in the Log Form field.
The audit or log form you specify is created when you save the main form.
8. (Optional) Specify a qualification.
The incoming entry is audited only if it satisfies this qualification.
9. Click OK.
In the audit form's Audit panel, the name of the main form is displayed next to the Audit
From Form label.
In the log form's Audit panel, the number of forms using the log form is displayed next to the
Audit From Ref Count label.
Specifying fields to be audited

On a form configured for auditing, you specify which fields should be audit fields, which should be
copy fields, and which should be audit and copy. Audit field values and copy field values are copied
from the main form to the audit or log form, but only changes to audit fields trigger audit processing.
Page 1955 of 4705
Home
Audit fields are copied only if their value changes. For copy fields, either the value in the current
transaction is taken (if present) or the value is taken from the database. If an entry is created and
no value is entered for a copy field, nothing is copied. Fields specified as audit and copy trigger an
audit and are copied if changed. If not changed, they behave like copy fields.
Note
System fields, including Create Date and Last Modified By, cannot be audited.
To specify fields to be audited

1. In BMC Remedy Developer Studio, open a form for which auditing is enabled.
See Configuring a form for auditing for more information.
2. Select the fields you want to audit.
3. In the Properties tab, set the value for the Audit Option property.
The options are:
None Changes to this field are not recorded by any audit processing.
Audit Changes to this field trigger audit processing and its new value is recorded in
the audit form or log form, depending on the audit style you specified at the form level.
If the value does not change, its value is not recorded.
Copy The database value or the value in the current transaction if present is
recorded during an audit, but does not trigger audit processing.
Audit and Copy-Changes to this field trigger audit processing. If the value has not
changed, the value from the database is recorded (similar to the behavior of the Copy
option).
4. (For log-form audits only) In the Properties tab, set the values for the Audit Log Key
property:
Key 1 The value of this field appears in the Log Key 1 field in the log form.
5. Save the form.
Table fields in audit forms

If a form is enabled but has auditing disabled and has no audit form, the BMC Remedy AR System
server tries to create an audit form for it. If the main form has a table field, the BMC Remedy AR
System server tries to create the table field in the audit form while creating it. If the table field's form
is missing, the audit form is not created, and you receive the following errors:
Could not create the Archive or Audit Form specified. Archive/Audit for this form has
been disabled. (ARWARN 8992)
Form does not exist on server Form1: (ARWARN 303).
Page 1956 of 4705
Home
The problem is that the BMC Remedy AR System server is attempting to create the table field in
the audit form, but because the table field's form is missing, it cannot pass the validation.
To resolve this problem, create the table field's form, or delete the table field from the main form.
Changing character field properties on the main form

When you modify the following properties of character fields on the main form, the BMC Remedy
AR System server updates the audit form:
Attributes
Field limits
Display properties
Help text
When you modify the following properties, the audit form is unchanged:
Entry mode
Index for FTS
Permissions
Fields on audit forms are always read-only.
Considerations for auditing forms

View and vendor forms
When vendor or view forms have form-style auditing, the audit form created is a regular form, which
includes core fields. Therefore, you might have to provide default values for the Short Description
and Submitter fields because they are required fields (for example, if you have workflow configured
for the audit form).
Join forms
Both form-style and log-style auditing are available for join forms. An audit of a join form is triggered
if the join form contains audit fields from the base forms and the audit qualification (if present) is
TRUE.
Form style
For a form-style audit, the join forms' underlying forms must also be configured for form-style audit
and must be enabled. BMC Remedy AR System creates the join forms' audit form as a join form of
the underlying forms' audit forms and use the Audit Join Key fields in the join criteria, as shown in
How a join audit form is created
Page 1957 of 4705
Home
After BMC Remedy AR System creates the audit join form, you can modify the join criteria for the
audit form to add more qualifications.
The following figure illustrates how join-form audits work in join forms. If Join Form 2 satisfies the
join audit criteria, an audit occurs for Forms A, B, and C (irrespective of A, B, and C's audit
qualification), and audit records are visible by way of Audit Join Form 2.
If Join Form 2 fails the join audit criteria but Join Form 1 satisfies the audit criteria, an audit occurs
for Forms A and B, and audit records are visible by way of Audit Join Form 1, but not Audit Join
Form 2. If Form C has audit enabled, Form C is audited, and Audit Form C has entries, but audit
data cannot be viewed from Audit Join Form 2.
In summary, for the first audited join form that passes the join audit criteria, BMC Remedy AR
System generates a unique GUID and uses this GUID to update the Audit Join Key fields in this join
form's underlying audit forms. Because the audit join form has a join criteria based on the Audit Join
Key, the audit join form displays only data entered or modified in the corresponding audited join
form. If the base forms of the join are modified directly, these base forms are audited, but the audit
join form does not display the modifications because the value of the Audit Join Key fields is empty.
How a join form audit-style works with joins
Page 1958 of 4705
Home
Log style
For a log-style audit, a regular form is created and contains the special log-style audit fields.
Important
Data entered in the join form is copied to the log form regardless of whether any of that
data is pushed to the underlying base forms. This means that the data captured in a
log-style audit form might not reflect the content of the main form or its underlying base
forms.
Changing field properties on the main form

AR System server updates the audit form:
Attributes
Field limits
Help text
When you modify the following properties, the audit form is unchanged:
Entry mode
Display properties
Index for FTS
Permissions
Fields on audit forms are always read-only.
Page 1959 of 4705
Home
Distributed Server Option and audit forms

Distributed Server Option (DSO) works on audit and log forms, but the Transfer and Update flags
are not updated.
Assignee Group and other dynamic group fields

For a form-style audit, if the audited form contains an Assignee Group (ID 112) field or any other
dynamic group fields (IDs 60000 to 60999), the server creates these fields on the audit form. The
values of these fields are always copied to the audit form, even if the Audit Option for the field is
set to None.
For a log-style audit, if the audited form contains an Assignee Group field or any other dynamic
group fields, the server does not create these fields on the log form. If you add these fields to the
log form, the values of the fields are always copied to the log form, even if the Audit Option for the
field is set to None.
Using flag fields to view changes to an individual field

For every audit field in a form, BMC Remedy AR System creates a "flag field" on the audit form.
This field contains the database name and remains on the audit form until the main field is deleted.
(If a field in the main form is not audited or is a copy field, the flag field is not created.)
Flag fields are not in any view, and they are created with the field ID in the name, for example, F_
fieldIDC, where _fieldID is the field ID of the audited field. (If a join form is audited, fieldID is the
field ID of the audit field in the join form.)
Note
In the base form of a join, if a field is set to audit after the audit join form is created, the
flag field is created in the base form's audit form and in the audit join form.
When auditing is triggered, and if the audit field changes value, the corresponding flag field
contains a "1" to indicate that the field changed; otherwise, it remains empty.
By using a flag field, you can refine your search and view changes to an individual field.
To view changes to an individual field

1. Enable form-style auditing on a form.
2. Select the fields for which you want auditing, and set the audit attribute to Audit or Audit
and Copy for those fields.
3. Perform a search on the audit form with the following qualification included:
Page 1960 of 4705
Home
F_fieldID_C
where fieldID is the ID of the field for which you want to view the audit. This field must be one of the
fields that have the Audit or Audit and Copy attribute enabled.
For example, Form A has fields A, B and C, and audit is turned on for A and B. To view the
changes to A, search Form A with the following qualification:
'F_536870913_C' = "1"
where 536870913 is the field ID of field A. This query displays all of the records where field A has
changed.
Audit processing and filters

Both audit forms and main forms can have filters; however, filters cannot modify data on the audit
form. For all forms that are audited (either by Form Style or Log Style), auditing occurs at the end of
Filter Phase 2. For example, if Form A has Set Fields and Push Fields filter actions and Form A has
auditing enabled, the audit occurs after the Set Fields and Push Fields actions are executed.
The exception is a join form that is audited by Log Style. For these forms, auditing occurs at the
end of Filter Phase 1. For example, if Join Form AB has Set Fields filter actions and has auditing
enabled, the audit occurs after all the Set Field actions are executed.
If an error occurs in the transaction (including errors while auditing), the entire transaction is rolled
back.
Note
Phase 3 filter actions (such as Run Process, Notify, and DSO) are not audited.
For information about filter processing, see Filter processing in BMC Remedy AR System server .
Supporting compliance audits with BMC Remedy Approval Server

You can use the audit and logging capabilities of BMC Remedy AR System with BMC Remedy
Approval Server to support any compliance audit that requires proof of signatures by responsible
parties. This section describes the key BMC Remedy AR System functionality that can help support
audits.
Page 1961 of 4705
Home
BMC Remedy Approval Server is a self-contained, shared module that can be attached to any BMC
Remedy AR System application. It is a flexible solution for automating any approval or signature
process in any organization. Several BMC Remedy solutions use BMC Remedy Approval Server to
automate approvals, including BMC Change Management, BMC Service Request Management,
and BMC Asset Management. You can also write custom applications that use BMC Remedy
Approval Server.
Note
BMC Software does not advise customers about policies and procedures, but can provide
information about recommendations for using BMC Software products to support an
organization's policies and procedures.
BMC Remedy Approval Server is a software tool that helps implement business processes. It can
support compliance audits by providing an audit trail and proof of authenticity associated with an
approval, such as US FDA 21 CFR (Code of Federal Regulations) Part 11.
For more information about implementing processes and integrating applications with BMC
Remedy Approval Server, see Configuring the BMC Remedy Approval Server .
The following topics provide information about how BMC Remedy Approval Server supports
compliance audits:
Enforcing business rules with approval processes
Electronic signatures
Elements of auditable processes
Enforcing business rules with approval processes

An approval indicates agreement or rejection of a request or a decision. In business, approvals
represent the signature or acknowledgment of individuals in a business process. Approvals often
must be recorded to provide an audit trail and proof of authenticity associated with an approval or
signature.
Using well-defined processes and rules consistently is one key to a successful compliance audit.
Because BMC Remedy Approval Server uses defined processes and rules to gather approvals (
signatures) from the appropriate decision-makers, you can ensure that the processes and rules of
the business are always followed when gathering signatures.
By using BMC Remedy Approval Server and applications based on it to implement business
processes, you can create operational checks to ensure that approval steps take place in the order
and according to the conditions specified by your business rules.
Page 1962 of 4705
Home
Electronic signatures
In general, an electronic signature is stored data that reflects the intent of the individual to indicate
his or her signature. It must include the name of the signer, the date and time the signature was
executed, and the meaning of the signature.
BMC Remedy Approval Server provides this functionality for BMC Remedy AR System based
applications. Any application that uses BMC Remedy Approval Server to generate signatures, such
as BMC Change Management or a custom approval application, automatically uses the BMC
Remedy Approval Server functionality to permanently store each electronic signature along with a
set of related information.
Important
Many national and state governments have enacted laws that specifically define the term "
electronic signature". Companies using BMC Remedy Approval Server to support
compliance audits, where this term carries a specific meaning, should use the information
in this section together with appropriate legal advice.
Many audit guidelines also require that the approver's identity be verified at the time the signature is
entered. With BMC Remedy Approval Server, you can apply several types of control to ensure that
the approver has signature authority and to verify the approver's identity.
The approver's signature authority can be controlled by maintaining a list of authorized
approvers, and configuring the application to verify the approver.
The approver's identity and authentication is verified by BMC Remedy AR System access
control at the time the user logs on. BMC Remedy AR System access control is robust, and
administrators can configure the system to restrict access at many levels, including access
to records, field contents, and application functionality. Access is controlled based on the
user, user groups, and roles.
Finally, you can make approvers re-enter their password at the time of approval, so that an
unauthorized user cannot execute an approval by using an unattended console. For more
information about configuring the system to re-enter the password for approval, see
AP-Process Definition form.
For more information about access control in BMC Remedy AR System, see Access control.
Note
A digital signature is not same as an electronic signature. A digital signature is a specific
type of electronic signature that uses cryptographic methods to ensure both the content of
a message and the authenticity of the signer. BMC Remedy AR System provides
electronic signatures but not digital signatures.
Page 1963 of 4705
Home
Elements of auditable processes

An auditable process must contain a written log (physical or electronic) of the process actions, and
the physical or electronic signatures of the decision-makers or approvers.
The following topics provide information about the elements of an auditable process:
Written logs
Signatures of approvers
Written logs
To support a process audit, a log of the process actions must contain information sufficient to
answer the following questions:
What was the action taken or decision made (the meaning of the signature)?
When was the action taken or decision made (the date and time of the signature)?
Who took the action or made the decision (the signature)?
In a manual system, this information is kept by storing the relevant paper documents in a filing
system. When you use BMC Remedy Approval Server to implement a process, BMC Remedy AR
System stores the answers to these three questions in the Approval Audit Trail field, which is
associated with every request. For information about how BMC Remedy Approval Server uses the
Audit Trail Field, see AP-Detail form.
You can also use the Audit form property to track changes to data in any form. If this property is
configured, BMC Remedy AR System tracks changes to audited fields in the form according to
settings you specify. You can selectively audit entries by providing an audit qualification, or audit all
changes to the specified fields. For information about using BMC Remedy AR System form auditing
, see Using audit records.
You can also track supporting data in the BMC Remedy Approval Server and BMC Remedy AR
System log files. For information about using these log files, see Working with logs.
Signatures of approvers
In a manual system for approving requests, such as expense or change requests, the approver's
signature is a physical signature on a document that signifies approval of the decision, expenditure,
or change. The document must describe the request, and the signer must also date the request.
The approver's physical signature is verified by human recognition of the approver's handwritten
signature.
In an automated process implemented by BMC Remedy Approval Server, the approver selects an
option to Approve or Reject a request. This action records the decision as the approver's
electronic signature in the Signature form, along with the date, time, and all information contained in
the request.
Page 1964 of 4705
Home
For more information about BMC Remedy Approval Server signatures, forms, and handling
approval requests, see Configuring the BMC Remedy Approval Server .
Archiving data
The archive feature of BMC Remedy AR System provides a convenient way to periodically store
data (not definitions) from a form to an archive form; this reduces the amount of data accessed
during searches on the main form, thus improving system performance. Archiving applies to all
types of forms, except display-only and join forms. The main form is the form on which archive is
set (data is read from this form), and the archive form is the form to which data is copied.
The archive form is a regular form with special behaviors. It must be on the same server as the
main form.
When configuring a form for archiving, you can designate an existing form as the archive form if it
has the characteristics of an archive form. (See Characteristics of archive forms.) If you do not
enter the name of an existing form, BMC Remedy AR System creates the form.
The following archive types are available:
Copy to Archive and Delete from Source The entries you choose from the main form
are copied to the archive form and deleted from the main form.
Delete from Source The entries you choose from the main form are deleted; no archive
form is involved.
None Select this option to delete the archive settings for the form. The form is not
archived.
This section provides the following topics:
Configuring data archiving for a form
Configuring data archiving for a server
Defining associations to follow
Setting global archive interval for forms
Exporting and deleting archive data
Deleting an archive form
Performing data operations with an AR_ARCHIVER user
Changes to the main form that affect the archive form
Characteristics of archive forms
Managing the archiving process
Related topic
Archiving concepts
Configuring data archiving for a form

You can use the data archiving feature to back up and delete data from forms.
Page 1965 of 4705
Home
Notes
Do not archive system forms (such as User, Group, Server Statistics, and Server
Events) because these forms use reserved fields that should exist only on the one
form in BMC Remedy AR System.
You cannot archive join forms and vendor forms. Any existing archive defined for
join form and vendor form is ignored for archiving.
To configure data archiving for a form

1. Open the form to configure it for data archiving.
2. Click the Definitions tab.
3. Expand the Other Definitions panel and then the Archive panel.
Archive panel
4. Select an Archive Type option:

Copy to Archive and Delete from Source
Delete from Source
None
For more information on Archive Types, see Archiving data.
Note
In version 9.0, archives must be of type copy and delete or delete. Any
archives that are of type copy at the time of upgrade will be converted to
copy and delete. This ensures that records in the archive form are unique.
5. Select the Enable option to enable archiving of the form.
6.
Page 1966 of 4705
Home
6. Enter the name of the archive form to send the archive data. If the form does not exist, BMC
Remedy AR System creates the form.
7. If you selected Copy to Archive and Delete from Source , enter a name for the archive
form.
For example, if you are archiving data on the Application Statistics form, you might name the
archive form Application Statistics - Archive.
If the form that you entered does not exist, BMC Remedy AR System creates the form. If the
form exists, it must have these required properties of an archive form, as described in
Characteristics of archive forms.
8. To include the form in the archive policy, select the Include In Archive Policy option. When
you select this option, your form is archived as per your configuration based on the global
policy set in the Server Configuration form. For more information, see Archive policy in
archiving concepts.
9. (optional ) If you selected Copy to Archive and Delete from Source , select the following
options to exclude them from the archive form:
No Attachments
No Diary Fields
Selecting these options saves space in the archive form if the main form has large
attachments or a large amount of data in diary fields.
Warning
If you select Copy to Archive and Delete from Source , and select the No
Attachments and No Diary Fields options, the data in the attachments and
diary fields are deleted from the main form and are not copied to the archive
form.
10. To identify the data on the form to archive, enter a qualification.

For example, to archive statistics for a particular server from Application Statistics form,
enter:
'Server Name' = server name
11. To specify the age criteria for archiving records, enter the number of days and age
qualification field. The default qualification field is Modified Date. This is a new parameter
added in the archive definition, which specifies that the records should be archived when
they have reached a specific age. For information about understanding age qualification, see
Age qualification in archiving concepts.
For example, to archive statistics that were last modified before 30 days from the current
date in the Application Statistics form, enter:
Number of Days: 30
Qualification Field: Modified Date
12.
Page 1967 of 4705
Home
12. The description fields in the archive policy form and Archive Manager Console show the
description from the archive definition. Write the description in such a way that even an
administrator less familiar with the application is able to understand the effects of the policy.
13. Save the form.
After the data is archived according to your qualification criteria at the time specified, you
can open your archive form and view archived data using a browser.
Important
When a view form is archived, the archive form is created as a regular form
containing core fields that are not in the source form. You must supply default
values for the required Submitter and Short Description core fields in the archive
form.
Where to go from here

You must now choose which association you want your archiving process to include along with
your form. For more information, see Defining associations to follow.
Configuring data archiving for a server

The data archiving feature is enabled by default on an BMC Remedy AR System server. To disable
archiving for all forms on a server, select the Disable Archive option on the Configuration tab of the
AR System Administration: Server Information form.
If multiple BMC Remedy AR System servers use a single database, you can disable archiving on
all the servers except one if you want archiving to take place on only one server. If the server is a
member of a server group, configure the server group in the BMC Remedy AR System Server
Group Operation Ranking form to make sure that only one server performs the archiving operation.
For more information, Configuring server groups.
Errors are logged in the arerror.log file. Because there is no API, there is no entry in the API log
file.
Server events and logging

To create an entry for archiving in the Server Events form, select the Archive option on the Server
Events tab of the AR System Administration: Server Information form.
Server Events tab in the AR System Administration: Server Information form
Page 1968 of 4705
Home
If you select the Archive check box, every archive event is logged into the Server Events form.
Server Events form
The entries are as follows:

Event Type: (14) AR_SVR_EVENT_ARCHIVE_DONE.
Event Cause: One of the following entries:
(1) AR_SVR_EVENT_ARCHIVE_FORM (Copy to archive only).
(2) AR_SVR_EVENT_ARCHIVE_DELETE (Delete from source only).
Page 1969 of 4705
Home
(3) AR_SVR_EVENT_ARCHIVE_FORM_DELETE (Copy to archive and delete from

source).
Event Date: Date and time of the end of the archive operation.
Event Details 1: Source form name.
Event Details 2: One of the following entries:
Copy to archive and Copy to archive and delete from source
numberOfRecordsTransferred: totalNumberOfEntriesAttempted
Delete from source
numberOfRecordsDeleted: totalNumberOfEntriesAttempted
Event Details 3: Destination form name.
Defining associations to follow

Associations help you in archiving related forms together. When you set archive on a form, defining
associations to follow allows you to archive all or specific related forms. For more information
about using associations, see Associations overview.
Before you begin
To define associations that need to follow during form archive
Association to follow example
Before you begin

You must create all the relationships between the forms using associations object. For
information about creating associations, see Creating associations.
You must have configured your archive from the Archive panel in the Definitions tab of that
form. For information about configuring data archiving, see Configuring data archiving for a
form.
Note
Indirect associations having Many to Many cardinality cannot be followed for archiving.
Even if you select those associations, they will be ignored during the archiving process.
To define associations that need to follow during form archive

1. Open the form with which you want to archive.
3. Expand the Associations to Follow for Archive panel.
Note
Page 1970 of 4705
Home
You can only create Additive overlay type for the Association to follow for Archive
panel.
4. Select the option for defining associations that needs to be archived with the form. The list
displays the associations to follow options as per level of precedence . For information about
understanding associations to follow, see Archiving concepts.
Follow Parent This option inherits parent settings. If you select this option, the
option specified for the parent form is applied to the child form. For example, if All
Enforced option is selected for the parent form, the child form also follows All
Enforced associations. For more information, see Association to follow example.
None No associations are selected to follow for archiving with this form. No related
forms will be archived.
Selected Only the selected associations are archived. When you choose this
option, you can select the associations and the related forms that you want to archive.
All Enforced All enforced associations are followed for archiving. After you choose
this option, all enforced associations are automatically marked as selected in the
associations list. If required, unenforced associations can also be selected from the
associations list.
All All the associations for this form are archived. Generally, this option is not used
for archiving. If you select this option, associations not meant for archiving are also
included.
Note
In the Best Practice Customization mode, you can overlay Associations to
Follow for Archive. However, you will only be able to select the association
to follow option which includes higher level option than Base Development
mode. For example, if you have defined Selected option in Base
Development mode, you can only choose All Enforced or All option in Best
Practice Customization mode.
5. Save the form.
Note
You can also view a list of associations which are not available for following as they
do not exist on the server which the form is defined.
Page 1971 of 4705
Home
You can also view a list of forms which should be archived along with this form.
However, as no archive is defined and enabled, these forms will not be archived.
You can double click any such form and configure data archiving on it. For
information about archiving steps, see Configuring data archiving for a form.
Association to follow example

The following image displays an example which will help you understand how associations are
followed during archiving.
Following table illustrates associations that will be followed and the forms that will be archived
depending on the Associations to follow for Archive setting defined for each form.
Form A
Form B
Form C
All Enforced
Follow
Follow Parent
Associations that will be followed

for archiving
Forms that will be

archived
A, B, D
AB
Parent
BD
All Enforced
All Enforced (with AC

selected)
Selected (
BE)
Follow Parent
Follow
Parent
All Enforced or Follow

Parent
A, B, E
AB
BE
A, B, C, D, F
AB
Page 1972 of 4705
Home
Form A
Form B
Form C
Associations that will be followed

for archiving
Forms that will be

archived
AC
BD
CF
Selected (AB, AC)
None
All Enforced
A, B, C, F
AB
AC
CF
Selected (AC)
All
All
A, C, F, G
AC
CF
CG
All
Follow
Selected (CG)
A, B, C, D, E, G
AB
AC
Parent
BD
BE
CG
All
None
Follow Parent
All
All Enforced (with CG

selected)
All
A, B, C, F, G
AB
AC
CF
CG
Setting global archive interval for forms

To set global schedule for archiving on the forms to be archived, you must configure archiving
interval on your server. Starting this release, you will not be able to set archive schedule for
individual forms using BMC Remedy Developer Studio. For more information about understanding
how archive interval works, see Archiving concepts.
To set the global archive interval

Server Information.
2. Click the Configuration tab, and perform the following step:
a. Enter the Archive Interval value in hours. For example, if you enter value 2, all the
forms where you have enabled archiving, are archived after every two hours.
Note
The default value for Archive Interval is 24 hours.
Page 1973 of 4705
Home
3. Click Apply to confirm the changes.

Related topics
Archiving overview
Archiving concepts

You can manage your production system efficiently by periodically extracting archive data (for
example, archive data which is more than 5 years old). Using this feature, you can efficiently
manage the production system and optimally utilize the available infrastructure and resources. You
can reduce the database size by periodically extracting archived data.
After the data is archived, you can remove a specific range of archive data permanently from your
system. Exporting and deleting of old archive data is to be carried out to align with your data
retention and records management life cycle policies.
Warning
Do not perform the export operation during peak hours or while doing upgrades. After you
start the export operation, you cannot cancel it.
Archive data management operations

You can perform any one of the following archive operations:
Export and Delete exports and deletes data in the archive forms
Export only exports the data in the archive forms
Delete only deletes data in the archive forms
To export and delete archive data

1. Log on to the mid tier.
2. Access the AR System Archived Data Management form by typing the URL in the given
format:
http://<serverName>:<portNumber>/arsys/forms/<serverName>/AR+System+Archived+Data
+Management
3. In the Archived Data Management dialog box, click New request.
4. From the Operation drop-down, select Export and Delete.
5. In the Age in Days field, enter the age of the archive.
6. Ensure that the CSV export format is selected.
7. Click Save.
8.
Page 1974 of 4705
Home
8. Click New search to search for the record that you was exported.
9. Enter the age of the archive as the search criteria.
10. Click Search.
11. The Status field displays the status of the operation.
12. Upon completion of the operation, the Result field displays the result of this operation, which
is a directory containing the exported archive having the <
AGGAA5V0HGXU0ANJECBEAAAFI4HFYR> format. If the operation failed, the Result field
displays an error message with information about why it failed. You can see detailed error
logs in the arextension.log file located in the <ARInstallationDirectory>/ARServer/Db
directory.
Result of the archive Export and Delete operation
Notes
You can export/delete all the archived forms present in the system. For each
exported archive form, a new CSV file is created in a directory located under the <
ARInstallationDirectory>/ARServer/Db directory.
Errors, if any, are logged in the arextension.log file located in the <
Exporting and deleting archive data is an asynchronous operation. When you
create an entry in the system form, AR System Archived Data Management,
workflow defined on this form runs in the background.
In a server group environment, the export and delete operation runs on the server
on which the entry was created. However, if the mid tier is connected to a load
balancer, then create entry operation could be sent to any of the servers in the
group that are behind the load balancer. If you need the export and delete
operation to run on a specific server in the group, then you must specify the server
before you create entry into AR System Archived Data Management form.
You can also perform a export and delete operation from the Archiving console,
which provides a more wizard-like experience. For information about using the
Archiving console, see Managing the archiving process.
Page 1975 of 4705
Home
Limitation
Only CSV format is supported for exporting.
Deleting an archive form

You can delete an archive form by using BMC Remedy Developer Studio or by using an API call.
When an archive form is deleted, archive settings are cleared for the main form. The Archive Type
field is reset to None in the Archive page of the Form Properties dialog box.
To delete an archive form using BMC Remedy Developer Studio

1. Make sure that the main form in BMC Remedy Developer Studio is closed.
If the main form is not closed, your archive form might be regenerated and the archive
settings might not be cleared.
2. In BMC Remedy AR System Navigator, expand serverName > All Objects.
4. In the Forms list, right-click the form name, and choose Delete.
5. In the Confirm Deletion dialog box, click OK.
6. In the Confirm dialog box, click OK.
Deleting an archive form using an API call

To delete an archive form regardless of whether the main form has archiving turned off or on, or
when deleting an archive form that is part of a lock block, use the
AR_SCHEMA_SHADOW_DELETE option with the ARDeleteSchema API call.
If the archive form has data, use the ARDeleteSchema API call with both
AR_SCHEMA_DATA_DELETE and AR_SCHEMA_SHADOW_DELETE options. This deletes the
archive form with data.
Performing data operations with an AR_ARCHIVER user

The BMC Remedy AR System server has a special user called AR_ARCHIVER to perform data
operations such as copying data to the Archive form and deleting data from the source form. If you
run a filter log file, you can see this entry in the log file. The BMC Remedy AR System server also
reserves an internal thread for archiving.
Changes to the main form that affect the archive form

Saving the main form to a different form name
If you save a main form in BMC Remedy Developer Studio using the Save As function, the
archived settings are not saved to your new form.
Page 1976 of 4705
Home
Configuring the Archive Type

On the Archive page of the Form Properties dialog box of the main form, if you select None from
the Archive Type list, the connection between the archive form and the main form is broken. All
archive information is lost, and the archive form is treated as a regular form.
Instead of losing the archive information, clear the Enable check box, and the archiving information
is preserved. To resume archiving, select Enable again.
Qualifications
You can select the data to be archived based on a qualification. If you do not specify a qualification,
all the data in the form is archived. Consider the effect on performance when using this option.
Licensing
When you license an application and license the main form, the archive form is also licensed.
Changing field properties on the main form

AR System server updates the archive form:
Attributes
Entry mode
Field limits
Help text
When you modify the following properties, the archive form is unchanged:
Display properties
Index for FTS
Permissions
Fields on archive forms are always read-only.
Deleting archive fields from the main form

When you delete multiple fields from the main form, the BMC Remedy AR System server attempts
to delete those fields from the archive form. If any of those fields contains data, none of them are
deleted from the archive form.
However, if the fields are deleted one by one from the main form, the fields that do not contain data
are deleted from the archive form.
Characteristics of archive forms

In this topic:
All archive forms
Page 1977 of 4705
Home
Archive forms created by BMC Remedy AR System

Distributed Server Option (DSO) and archive forms
All archive forms

All archive forms have the following characteristics.
General
The archive form is a regular form. The detail view in the BMC Remedy Developer Studio
forms list shows its Type as Archive.
Changes to the definitions of the main form (such as adding or deleting a field) are also
applied to the archive form. For example, if you add a data field, the same field is added on
the archive form. If data exists on the form, the respective data field cannot be deleted from
the archive form.
Trim and Button fields are not created automatically. You can manually add Trim and Button
fields to an archive form.
View changes are not a part of the form definition. Hence, changes made to them are not
applied to the archive form. You can change the form properties and the view properties of
the archive form explicitly.
If the main form belongs to a deployable application, the archive form also belongs to the
same application.
If the main form is made "licensable", the archive form is also made licensable.
The archive form cannot be audited or further archived.
Fields
When the BMC Remedy AR System creates a new archive form, the following two fields are
included on the form:
Original Request ID (ID 450)
Original Create Date (ID 451)
These fields contain the Request ID and Create Date from the main form. These
fields are not placed in the view. To add them, open the archive form in BMC Remedy
Developer Studio, and choose Form > Add/Remove Fields On View . Then, move
the fields to the Fields in View table.
You can use the Create Date of the archive form as the archive date. The remaining
core fields on the archive form contain the same values as the main form.
Data fields, attachment pools, and panel holder cannot be modified or added to an archive
form. All other field types, such as trim or table, can be added or modified.
The data fields in the main and archive form have identical field limits. The permissions on
archive forms are always read access.
Workflow
Workflow from the main form is not attached to the archive form when it is created. You can
add workflow to an archive form, but workflow cannot modify data in an archive form.
Page 1978 of 4705
Home
Filters that execute on Delete execute when archiving deletes data.
Import and export

Data can be exported from an archive form and imported into an archive form, but existing
entries in an archive form cannot be overwritten.
During import, if only the main form is present, archiving is disabled for that form, and a
warning is returned. When archive is enabled for that form, BMC Remedy AR System
checks to see if the archive form is present. If no form is found, BMC Remedy AR System
creates the archive form. If the archive form is found, it is used only if it is a valid archive
form.
If the main form is part of a lock block from an exported definition, the archive form is part of
the same lock block.
Archive forms created by BMC Remedy AR System

When BMC Remedy AR System creates archive forms, they have the following characteristics in
addition to those listed in #All archive forms:
Any unique index on the main form is created as a non-unique index on the archive form. As
the Entry ID and Create Date fields are duplicated on the archive form in the new fields, any
index on those fields is applied to the new fields instead.
When an archive form is created, the entry points are cleared, but you can add entry points.
All other form properties are copied from the main form to the archive form. However, after
the archive form is created, subsequent changes to the main form properties are not copied
to the archive form.
The owner of the non-core fields on the archive form is set to the owner of the archive form,
not the original form.
Distributed Server Option (DSO) and archive forms

When a form used in a distributed operation is archived, the distributed fields are copied to the
archive form but are not updated. You cannot add distributed fields to an archive form.
Managing the archiving process

The AR System Archive Manager console is where you manage the archiving process. You can
perform the following tasks from the Archive Manager console:
AR System Archive Manager console overview
Opening the AR System Archive Manager Console
Turning archiving on and off
Changing how often the archiving process runs
Changing when a record is ready for archiving
Disabling individual archiving policies
Running an on-demand archive process
Page 1979 of 4705
Home
Stopping an archive run after it has started
Notes
To access the AR System Archive Manager console, you must have the role of Archive
Admin.
When entering values in console fields, you must type numbers that are positive, whole
numbers, equal to or greater than 1.
AR System Archive Manager console overview

A video walk through of the console is available in the online version of this documentation or here,
on YouTube.
View video on YouTube
You can also connect with other users for related discussions on the BMC Community .
Opening the AR System Archive Manager Console

1. In a browser, go to the following URL address: http://<hostName>:<portNumber>/
arsys/
2. Log on.
3. Select AR System Administration > AR System Archive Manager Console.
Turning archiving on and off

The archiving process is turned on by default. However, if your organization does not use archiving
or if you need to temporarily disable the feature (for example, if you need to prevent the Archive
Process from running during system maintenance), you can turn off the feature from the AR
System Archive Manager console.
Even if you turn off the archiving process, you can still perform an on-demand archive run against
selected records. Click here for information about running an archiving process on demand.
If you turn off archiving, you can turn it on again by reversing the following procedure.
Turn off Continuous Archiving

At the top of the AR System Archive Manager console, clear the Enable Server Group
Archive check box.
Page 1980 of 4705
Home
Changing how often the archiving process runs

By default, the system runs an archive process every 24 hours. If this timing is inappropriate for the
needs of your organization, you can change the frequency with which the archiving process runs.
For example, if your organization archives a large volume of records every day, you might want to
increase the frequency of the archiving run from every 24 hours to every 12 hours. By running the
Archiving process more frequently, smaller numbers of records are archived in any given run, which
reduces the impact of the archive run on overall system performance.
To control the frequency of archiving

1. At the top of the AR System Archive Manager console, type a new value in the Run Every (
hours) field.
2. Click Apply.
Changing when a record is ready for archiving

The archiving process uses archiving policies to determine whether a record is ready for archiving.
Each record type has its own archiving policy. The archiving policy defines:
Which record types are archived (Incident request, Change requests, and so on)
The required record status (Closed, Retired, Cancelled, and so on)
Note
The archiving process does not consider when the record was closed, retired, or
cancelled. So, for example, an incident request that was submitted 548 days ago,
but was closed only yesterday, is archived during the same archiving run as an
incident request that was submitted 548 days ago and closed on the same day. If
an incident request was submitted 600 days ago, but closed only yesterday, it is
archived in the first archiving run after it is closed.
When to archive a record, according to the Age in Days value (a reference to how long ago
a record either was submitted or was last modified, depending on the record type)
The following list describes each of the archiving policies.
Click here to open the list of archiving policy descriptions.

By default, the Archiving process archives BMC Change Management records according to the
following criteria (all of the conditions must be true):
Page 1981 of 4705
Home
The record status must be Closed (in some cases, however, child records such as Task,
which are still open, will be archived; click here for more information about child records).
The Do Not Archive flag value for the record must be null (that is, the flag is not selected).
The number of days elapsed since the record's Submit Date must be at least 548 (18
months). This value represents the default value and is configurable for each main form by
changing the Age in days value.

By default, the Archiving process archives the following BMC Knowledge Management record types
:
Knowledge Management
Search History
Search History Company
Search History Operational Categorization
Search History Organizational Department
Search History Product Categorization
Search History Service
Search History Site Region
Search History Source
Search History Visibility Group
The Archive policy archives BMC Knowledge Management records according to the following
criteria (all of the conditions must be true):
The record status must equal one of the following values (depending on the record type):
Retired
Cancelled
Closed Version
The number of days elapsed since the record's last modified date must be at least 90 (3
BMC Service Desk

By default, the Archiving process archives the following BMC Service Desk record types:
Incident Management
Problem Management
Solution Database
Known Error
The Archive policy archives Service Desk records according to the following criteria (all of the
conditions must be true):
Page 1982 of 4705
Home
The record status must be Closed (in some cases, however, child records such as Task,
which are still open, will be archived; click here for more information about child records).

By default, the Archiving process archives the following BMC Service Request Management record
types:
Service requests
Work orders
The Archive policy archives BMC Service Request Management records according to the following
criteria (all of the conditions must be true):
The record status must equal one of the following values:
Cancelled
Closed
months). This value represents the default value and is configurable for each main form.
Using the AR System Archive Manger console you can change the Age in Days value. Changing
this value allows you to control how long each record type remains in the production database
based on the needs of your organization.
For example, if your help desk generates 30 incident requests for every change request, you might
need to archive incident requests more frequently than change requests.
To change the age in days

1. From the Archive Policies table, select the policy that you want to edit.
2. In the Age in Days field, type the new value.
Tip
If the Age in Days field is not visible in the UI, the policy that you selected is
disabled. To enable the policy, make sure the policy is selected in the table, and
then click Enable Policy.
3.
Page 1983 of 4705
Home
3. Click Apply.
Notice the value that you typed now appears in the Custom Specified Age In Days column.
When a value is present in both the Default Policy Age In Days column and the Custom
Specified Age In Days column, the system uses the custom age in days to qualify records
for archiving .
4. If necessary, run an on-demand archive process.
You might need to run an on-demand archive process if, for example, you reduced the
number days after which a record type is archived. In this case, you might not want to wait
for the next archive process to move the newly qualified records out of the production
database.
To resume using the default Number of Days value

To resume using the value specified in the Default Policy Age in Days column, highlight the
applicable policy in the Archive Policies table and then click Use system default of x days.
Notice that the system removes the value from the Custom Specified Age in Days column and
leaves the corresponding table cell blank. When the cell is blank, the archiving process uses the
value in the Default Policy Age In Days value to determine when to run the selected archive policy
.
Disabling individual archiving policies

You can prevent a specific record type from being archived by disabling its archiving policy. When
an archiving policy is disabled, the archiving process ignores records of the related type when the
process runs. When you are ready to start archiving the record type again, you re-enable the
archiving policy.
To disable an archiving policy

1. From the Archive Policies table, select the policy that you want to disable.
2. Click Disable Policy.
Notice that the associated cell in the Custom Specified Age In Days column changes to a
negative number. A negative number in this cell disables the policy.
Re-enabling disabled archiving policies

1. From the Archive Policies table, select the policy that you want to enable.
2. Click Enable Policy.
Notice that the associated cell in the Custom Specified Age In Days column is now blank,
which tells the archiving process to resume using the value in the Default Policy Age In
Days column.
Note
Page 1984 of 4705
Home
If you disabled an archiving policy that had used a Custom Specified Age In Days
value, the system changed the custom value to a negative integer to indicate that
the policy was disabled. When you re-enable the policy, the system clears the
negative integer from the associated table cell, but leaves it empty. The system
does not restore the previous custom Age in Days value. If you still need the
archiving policy to reference the custom Age in Days value, you must re-enter the
value.
Running an on-demand archive process

If you need to run an archive process outside of the archiving schedule, you can run an on-demand
archive process. On-demand archive processes let you move data to the archive database by
record type; that is, you can run on-demand archive processes against incident requests, change
requests, and so on.
1. From the Archive Policies table, select the record type for which you want to run the
on-demand archiving process.
2. Click Run Selected Policy Now.
Tip
If the Run Selected Policy Now button is not visible in the UI, the policy that you
selected is disabled. To enable the policy so that you can run an on-demand
archive process, make sure the policy is selected in the table, and then click
Enable Policy.

Over time, your archive forms will become large as they continue to accumulate archived records.
To help you manage the size of these forms, you can:
Move the older archived data from the archive forms to a set of .csv files in your system
database folder (a separate .csv file is created for each archive form)
Delete the older archived data.
You perform these actions by selecting one of the following export operations:
Export and Delete Copies archived data the same age or older than the Age in Days
value to a set of .csv files and then deletes the exported data from the archive form.
Delete Deletes archived data equal to or older than the Age in Days value from the
archive forms.
Export Copies archived data equal to or older than the Age in Days value to the .csv
files, but leaves the data on the archive form.
Page 1985 of 4705
Home
The Age in Days field in the AR System Archive Manager console controls which records are
moved or deleted. For example, if you type 180 in the Age in Days field, all records that were
archived 180 days ago, or longer, are either moved or deleted. How often you perform an export
depends on the data retention policies of your organization, on the the capacity of your system to
store archived data, or both.
Notes
Do not perform the export operation during peak hours or while doing upgrades. Although
you can cancel an archiving run after it starts, you cannot cancel and export operation.
Exporting and deleting archive data is an asynchronous operation. To trigger the
operation, the AR System Archive Manager console creates an entry in the back end
system form AR System Archived Data Management. Workflow defined on this form
hands off the job to an internal plug-in that runs in the background.
In a server group environment, the export and delete operation runs on the server on
which the operation was created. However, if the mid tier is connected to a load balancer,
the job could be sent to any of the servers in the group that are behind the load balancer.
If you need the export and delete operation to run on a specific server in the group, you
must point the mid tier directly at that server before you start the operation.
To export archived data

1. From the Operation menu, select the type of operation that you want the export to perform.
2. Review and, if necessary, change the value in the Age in Days field.
3. Click Export.
The Export function creates a directory under the following path and writes the exported .csv
files to that directory: <ARInstallationDirectory>/ARServer/Db
Notes
When you see the message Export Successfully, the console is telling you
that the export job was successfully submitted to the backend AR System form,
Archived Data Management. You can monitor the status of the archive job by
opening the Archive Data Management form and looking at the Status value.
To open the Archived Data Management form, type the form's URL in the following
format: http://<serverName>:<portNumber>/arsys/forms/<serverName>/AR+
System+Archived+Data+Management
Errors, if any, are logged in the arextension.log file located in the <
Page 1986 of 4705
Home
Stopping an archive run after it has started

If you need to stop the archive run after it has stared, there are a couple of ways to do that,
depending on the type of archiving run you need to stop:
Scheduled, full archive runTo stop an entire, scheduled archive run in mid-process, from
the AR System Archive Manager console, turn archiving off.
Individual archiving policyTo stop an individual archiving policy in mid-process when it is
part of a scheduled archiving run, disable the policy in the AR System Archive Manager
console. When you disable an individual policy that is part of a regular archiving run, the
archiving run skips the remainder of the qualified records covered by the disabled policy and
moves on to the next archive policy.
On-demand archiveTo stop an on-demand archive, disable the applicable policy in the AR
System Archive Manager console.
Note
When you turn off archiving or disable an archiving policy as mentioned here, the
archiving process finishes archiving the record currently being processed and then
either stops or moves on to the next archiving policy. All of the records that the
archiving run processed before you disabled it remain committed to the Archive
form.
File types used in migrations

You can work with definition files (.def ), and XML (.xml ) files, and BMC Remedy Migrator files ( .
migrator ).
BMC Remedy AR System .def and .xml files are text-based and the .migrator file is binary-based.
All three types of files contain one or more BMC Remedy AR System object definitions. Similar to
the .def and .xml file, the .migrator file stores the actual support file, along with the object
definitions.
You can work with object definitions in the following ways:
Export object definitions to BMC Remedy AR System .def and .xml formats, which BMC
Remedy Migrator exports as server independent. See Exporting object definitions on a
server.
Convert .def and .xml files to the .migrator format, which can be launched independently.
The files are displayed in their own server windows. See
Migrate objects from a server to a .migrator file, a .migrator file to a server, or between*.
migrator* files.
Page 1987 of 4705
Home
Note
When converting a .def or .xml file to a .migrator file, the original .def or .xml file remains
intact. The newly converted .migrator file is stored within the same directory where the .
def or*.xml* file is stored.
Exporting object definitions on a server

Use the following procedures to export objects on a server (including locked objects) to .def or .xml
files. These procedures are useful if you want to generate BMC Remedy AR System definition or
XML files from within BMC Remedy Migrator.
To export objects to .def or .xml files

1. In the left pane of the server window, under BMC Remedy AR System Objects, click an
object type.
2. In the right pane, select the objects you want to export.
3. Select Tools > Export Definitions.
4. In the Save As dialog box, enter a file name, including the .def or .xml extension, and click
Save.
If the definition file already exists, you can append the existing file.
To export locked object definitions

1. In the left pane of the server window, under BMC Remedy AR System Objects, click an
object type.
2. In the right pane, select the objects you want to export.
3. Select Tools > Export Locked Definitions.
4. In the Lock Key field of the Object Lock dialog box, enter a lock key of up to 27 characters.
You must enter a valid lock key consisting of alphanumeric characters (for example, 123456
or abcxyz or abc789 ). You cannot use double-byte characters. Objects with the same lock
key are encrypted as a group in the definition file.
5. In the Verify Lock Key field, enter the lock key again.
6. Select a lock type, either Hidden or Read Only.
Filters, filter guides, and escalations can be hidden. For more information about lock types,
see Types of object details.
7. Click OK.
During the export, locked objects can exist in the same definition file with unlocked objects.
Because lock information is encrypted, no one can remove a lock or change the lock type in
the definition file.
8. In the Save As dialog box, enter a file name, including the .def or .xml extension, then click
Save.
If the definition file already exists, you can append the existing file.
Page 1988 of 4705
Home
To export deployable applications

1. Select Tools > Export Application.
2. In the Select Application dialog box, select a deployable application from the list, and click
OK.
3. In the Save As dialog box, enter a file name for the application.
The default file type is .def. To export as an .xml file, select .xml from the File Type field.
4. Click OK.
The application is exported to the .def or .xml format.
Converting definition files to .migrator format

You can convert object .def and .xml files to the .migrator format for viewing files in BMC Remedy
Migrator, or for exporting .def and .xml files within BMC Remedy Migrator.
You can convert a .def or .xml file in two ways:
Select Tools > Convert Definition Files. When the Open dialog box appears, select a .def or .
xml file, and click Open. A progress bar appears as the file is being converted to the .
migrator file format.
Select File > Open, select a .def or .xml file, and click Open. BMC Remedy Migrator
converts the .def or .xml file to a .migrator file with the same name.

This section contains information about importing data into BMC Remedy AR System forms:
The import process
Supported mapping file types
Defining Data Import preferences
Creating mapping files
Importing data
Using a saved mapping file

This section explains how to start and log in to Data Import. You can log in to a AR System server
from any computer on the network that has access to the server.
Also in this topic:
Changing the current login
To start Data Import and log in to AR System servers

1. Select Start > Programs > BMC Software > Data Import .
2.
Page 1989 of 4705
Home
2. In the User Name field, enter your user name.

3. Enter the password of the AR System user.
4. (Optional) If you are required to specify an authentication string or a preference server, click
Options.
a. (Optional)
Enter an authentication string.
Whether you need an authentication string depends on how your server validates
users. For most situations, this field is not used. See Setting up an authentication
alias.
You can also configure an External Authentication (AREA) plug-in. See Configuring
the AREA LDAP plug-in and AREA plug-in API functions.
b. In the Preference Server field, type the name of your preference server.
A preference server is the AR System server on which the AR System preference
forms are installed. This server stores your administrator and user preferences in a
central location where they can be accessed from any client computer. You define a
server as a preference server during or after installation.
If you always log in from the same computer, leave this field blank to store your
preferences locally in the workspace directory.
For more information, see Setting user preferences.
c. If you use a preference server and it does not use the default TCP port or RPC port,
enter the TCP and RPC port numbers.
5. If you have already configured AR System servers to connect to, click Login (and skip the
rest of this procedure).
6. Click Edit Server List.
7. In the Server List dialog box, click Add.
8. Highlight Enter a server name in the Servers column, and type the server name.
To prevent Data Import from connecting to a server, clear the server's check box.
9. If the server does not use the default TCP port, click in the TCP column and type the port
number.
10. If the server does not use the default RCP port, click in the RCP column and type the port
number.
11. Repeat steps 7 through 9 for each server Data Import must connect to.
12. Click OK.
13. In the Login dialog box, click Login.
Changing the current login

To log in to a different server or as a different user, you must change your login.
To change the current login

1. Select File > Relogin.
2. In the Login dialog box, change the server list, user name, password, and other information
as described in To start Data Import and log in to AR System servers .
3.
Page 1990 of 4705
Home
3. Click Login.
The import process

BMC Remedy Data Import loads data from a source file into an AR System form. A command-line
interface (CLI) is also available for both Windows and UNIX. See Enabling the Data Import utility.
For information about exporting and importing object definitions, see Importing and exporting object
definitions and locking objects.
Follow this process to import data into a form:
1. Complete all edits on the data file before you start Data Import. Do not edit the data file
between the time you open Data Import and the time you start the actual import operation.
2. Export the source data to a file compatible with Data Import. (See Supported mapping file
types.)
3. Define Data Import preferences. (See Defining Data Import preferences.)
4. Make sure that adequate space exists where the import log file will reside.
Data Import writes error messages and failed records to a log, which can become quite large
.
5. Make sure that the database has adequate space to store the imported records. Contact
your database administrator for assistance.
6. Create a mapping file. (See Creating mapping files.)
7. Import the file. (See Importing data.)
Supported mapping file types

Data Import can map the following file types:
AR Export (.arx ) Default AR System data file type.
AR XML (.xml ) XML file conforming to the AR XML data specification. This file type
contains several elements required for AR System use. See XML formats.
CSV(.csv ) Comma-separated value file. In this file, carriage returns are treated as the
end of a record.
ASCII (.asc ) Generic ASCII file.
You can create .arx, .xml, and .csv files with the artext utility, which is designed primarily for
localization. For information about artext, see Localizing message components of a form view .
To use ASCII data obtained from a source outside of BMC Remedy AR System, remember these
rules:
Save the data with a unique separator string of up to 32 characters in length.
Use \t for tab, \b for backspace, and two backslashes for carriage returns are treated as the
end of the record.
Page 1991 of 4705
Home
You cannot import .asc data that uses special characters as column separators. Unique
separator strings should not appear in any of the field names or the data. This prevents
problems with incorrect numbers of fields when importing.
Note
When attachments are exported in AR Export format from a browser, a .zip file is created
that includes the .arx file and the attachments.
Defining Data Import preferences

Preferences determine tool behavior such as how Data Import handles duplicate records and how it
resolves conflicts during an import operation.
Default preferences are set in the Preference window of Data Import. They are stored locally or in
the AR System Administrator Preference form (if you logged into a preference server).
When you create a mapping file (choose File > New Mapping), the preferences in the Preferences
window are used by default. To change the preferences, click the Options tab in the mapping file in
Data Import, and save the mapping.
Note
The preferences in the Preferences window affect only new mapping files. For example, if
you create an EmployeeRecords mapping file and save the file, the current preferences
from the Preferences window are used. If you later update the preferences in the
Preferences window, the preferences for EmployeeRecords remain unchanged. To
change the preferences for EmployeeRecords, use the Options tab.
To update the preferences for Data Import

1. In Data Import, choose File > Preferences.
The Preferences dialog box appears.
Data Import Preferences dialog box
Page 1992 of 4705
Home
2. Set the preferences, which are defined in the following table.

Data Import preferences
Group
name
Field
Function
General
Log File
Identifies the directory and file name of the BMC Remedy Import log file, which is workspaceDir\
dataimport.log by default.
Note: Only one log file is used, so each time you import data, the log file is overwritten. To keep a log
file, rename it.
Number of
Records
Per
Transaction
Uses transactions to import data (if the server supports transactions). For example, if you enter a
value of 100, the server performs only one commit to the database every 100 records, which
significantly improves performance.
Page 1993 of 4705
Home
Note: Specify the -b option in Data Import command line to use the bulk mode for record transfer.
Bulk mode is an atomic transactional mode. If any record failed to import in bulk then Data Import rolls
back the entire bulk of records.
Duplicates
Handle
Duplicate
Request
IDs By
Defines how to handle duplicate request IDs. The options are

Generate New ID for All Records Assigns new request IDs to all requests in the data file,
whether or not any IDs are duplicates. Generates request IDs for records that do not already
have them, for example, in a CSV file created outside AR System.
Reject Duplicate Records Entries are imported using their existing IDs. If an ID is already
in use, an error is generated. The error is processed according to your preferences. See
Defining Data Import preferences for more information.
Generate New ID for Duplicate Records Entries 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.
Replace Old Record with New Record Entries are imported using their existing IDs. If a
duplicate ID exists, the entire database record is overwritten with the record being imported.
You must map the required core fields with this option; otherwise, the server rejects the records
. See Importing data for more information about mapping.
Update Old Record with New Record's Data Entries are imported using their existing IDs.
If a duplicate ID exists, only the fields being imported are replaced, merging the record. If you
choose this option, Data Import actually deletes the record and reinserts it to perform the "
update." This setting also automatically makes all non-core required fields optional. See Data
Handling for more information about preferences related to required fields.
If Multiple
Requests
Match
Defines what happens when multiple requests match. The options are
Skip Record Skips the record in the data file and does not import anything for that record.
Use First Matching Request Updates the first request with the data from the data file.
Update All Requests Updates all the requests with the one from the data file.
Data
Handling
Make
Non-Core
Required
Fields
Specifies that noncore required fields are optional during the import. By default, the check box is
cleared, and all required fields are treated as required. If a required field has a NULL value, an error is
generated. The error is processed according to what you enter in the Bad Records field under the "
Error Handling" section.
Optional *
Disable
Pattern
Matching *
Specifies that records are imported, even if the data in a field does not match the specified pattern. By
default, the check box is cleared, and the server rejects records if data in the field does not match the
specified pattern. The error is processed according to what you enter in the Bad Records field under
the "Error Handling" section.
Suppress
Filters
Suppresses (turns off) any filters that execute on Merge.
Suppress
Field
Default
Values
Suppresses the default values of the fields. If the field has a default value and the data you are
Remove
Specifies that all leading white space is removed from each field imported. By default, the check box is
cleared, and values are imported exactly as they appear in the data file.
Leading
Spaces and
importing for the field is empty, the import process does not use the default value for that field.
Tabs *
Specifies that all trailing white space is removed from each field imported. By default, the check box is
cleared, and values are imported exactly as they appear in the data file.
Page 1994 of 4705
Home
Remove
Trailing
Spaces and
Tabs *
Truncate
Strings
Exceeding
Field Limit
Specifies that fields that are too long are truncated. By default, the check box is cleared, and fields
whose contents are too long generate an error. The error is processed according to what you enter in
the Bad Records field under the "Error Handling" section.
*
Import
Records
with Too
Few Fields
Import
Records
with Too
Many
Fields
Date
Format
Short Date
Format
Specifies how BMC Remedy AR System imports records that contain fewer fields than described by
the field titles in the data file. Problem records are imported with NULL values in the missing fields. By
default, the check box is cleared, and the problem records are not imported and an error is generated.
The error is processed according to what you enter in the Bad Records field under the "Error Handling
" section.
Specifies how BMC Remedy AR System imports records that contain more fields than described by
the field titles in the data file. By default, this option is selected. The problem records are imported,
and the extra fields are ignored. If you clear the check box, the problem records are not imported, and
an error is generated. The error is processed according to what you enter in the Bad Records field
under the "Error Handling" section.
Defines the short-date format. The options are
M/d/yy
d/M/yy
yy/M/d
The component order is based on the Locale settings as defined by Oracle Java.
Short Date
Separator
Defines the separator character between the month, day, and year. Slash
is the default. You can
use any character that is not part of the field separator string for the data file.
Long Date
Defines the long-date format. The options are
Format
dddd, MMMM d, yyyy
dddd, d MMMM, yyyy
dddd, yyyy MMMM d
The component order is based on the Locale settings as defined by Java.
Time
Format
Hour Mode
Defines the hour mode. The options are

12 Hour Tracks in the 12-hour clock (default).
24 Hour Tracks in universal time.
Separator (
Time
Format)
Defines the time format separator between the hours, minutes, and seconds. A colon (:) is the default.
AM/PM
Position
Specifies where the symbol is positioned if you select 12 Hour for the Hour Mode. The options are
You can use any character that is not part of the field separator string for the data file.
Prefix The symbol is positioned before the time string (for example, AM 10:23:47 ).
Suffix (default) The symbol is positioned after the time string (for example, 10:23:47 AM ).
AM Symbol
Defines the symbol that indicate mornings if you select 12 Hour for the Hour Mode.
PM Symbol
Defines the symbol that indicates afternoon if you select 12 Hour for the Hour Mode.
Page 1995 of 4705
Home
Real
Number
Digit Group
Separator
Defines the separator for groups of real numbers in .arm and .armx files.
Decimal
Separator
Defines the decimal separator for real numbers in .arm and .armx files.
Bad
Records
Defines what happens when the import process encounters a bad record. The options are
Handling
Error
Handling
Alert User with Popup Dialog Interrupts the import and displays an error message (default)
. The message contains these choices:
Yes Skips the problem record, writes the error and the record data to the import log,
and continues to import remaining records.
Yes to All Skips all problem records that generate the same error, writes the error
and the records to the import log, and continues to import remaining records.
Stop Import Stops the import and prompts you to copy all remaining data to the
import log.
Skip Bad Records Skips problem records without displaying an error message, and
continues with the import.
Try Fallback Mapping Before Alerting User If a mapping generates an error, BMC
Remedy Import uses the fallback mapping specified in the Fallback Mapping preferences. If the
fallback mapping also generates an error, a message is displayed. The error is generated
against the original mapping error. Errors are not generated against fallback mappings.
* These settings are affected by field attributes set when fields are defined. See Fields overview
and Creating and managing fields.
Creating mapping files

Creating a mapping file
Tips for mapping all data file fields
A mapping file determines which pieces of data to import into the fields on the target form (mapping
) during the import process. You can map all fields in a data file to all fields in a form, or you can
map fields individually.
How data fields are matched to form fields

Data Import matches data fields to form fields as follows:
AR Export or AR XML Field IDs are matched first, and then field names are matched for
fields without matching IDs.
CSV or ASCII Only field names are matched.
Defining default mappings

You can define fallback mappings, which are default mappings that direct the Data Import response
if a data mapping problem occurs during an import. Fallback mappings are used when the data
value is invalid for the destination form field type. For example, if a problem occurs while a value is
mapped, the fallback mapping for the field is used if one is defined. If no fallback mapping exists,
an error is generated. If a fallback mapping fails, errors are generated on the original failed
Page 1996 of 4705
Home
mapping, not the fallback mapping.

When only the AR System server can detect the error (such as when the data is not an acceptable
value), the fallback mapping is not used. For example, the data value is outside the range set for
the form field, or a required field has a NULL value.
To create a mapping file

1. Log in to Data Import.
2. Choose File > New Mapping.
3. In the Mapping File Editor, complete the following fields in the Data File and Server section:
New Mapping dialog box fields
Field
Description
Source
Export file that contains the data to import. The file must be in .arx, .csv, .xml, or .asc format.
Data File
Contains
Field
Titles
(CSV and ASCII format only) Determines whether BMC Remedy Import converts the field titles into data.
If the first line of data contains field titles, select the File Contains Field Titles check box so that the
titles are converted to data.
If the first line of data does not contain titles, clear the check box.
Field
Separator
(ASCII format only) The field separator used in the .asc file.
Source
Form
Name
Form from which you exported data.
Target
Server
Server that contains the form to which to import data.
Target
Form
Form to which to import data.
Name
Custom
(Optional) The custom_options.xml file, which used to specify date and time formats, the separators to be
Options
File
used, and other information. This field appears only if the source data file selected is a CSV or ASCII file.
Note: During installation, a sample empty custom_options.xml file is installed in the installation folders for
BMC Remedy Developer Studio and Data Import. You can change the name and store it anywhere.
4. Map the fields in the Field Value Mappings section using either of the following methods.
a. Click Auto Map to add all fields and map fields to fields of the same name. For more
information, see Tips for mapping all data file fields .
Or
b. Click Add.
c. In the Add Mapping dialog box, select a Field Name.
d. Use the Keyword or Field buttons to add a value to the Value field.
You can also type field names, keywords, or any constant string into the Mapping
Value field.
For example, suppose you select the Create Date field, and you want each record in
Page 1997 of 4705
d.
Home
the destination form to have today's date as the value in the Create Date field.
Choose $DATE$ in the Keyword list. The resulting value in the destination form is the
date of the import. See Keywords.
e. Repeat this step for all the fields that you want to map.
Note
If the data file contains duplicate field titles, an error is generated. If the data
is*.arx* or .xml format, the field titles appears as their field IDs. If the data
file is .csv or .asc format, the fields appear with an appended number (for
example, fieldTitle1, fieldTitle2, and so on).
5. (Optional) Define fallback mappings for fields.

For more information, see Defining default mappings.
6. To edit a field value mapping or fallback mapping, select the field, and click Edit.
7. (Optional) Click the Options tab, and change the preferences as needed.
See Defining Data Import preferencesfor a description of most of the options. The
differences are
The Options tab does not include a Log File field, but it is included in the Preferences
window.
The Options tab includes the following fields, which are not included in the
Preferences window.
Additional Data Handling field on the Options tab
Page 1998 of 4705
Home
Group
Field
Function
Data
Disable
Setting this flag causes the server to suspend enforcement of associations on entries
Handling
Enforced
Associations
getting imported. Associations are still enforced on other entries affected by workflow
that might be triggered by entries getting imported. The server will only honor this flag
name
if the user of the import tool is an administrator.
8. (
Optional) Save the mapping.
9. Import the data as described in Importing data.
Tips for mapping all data file fields

Keep the following tips in mind when mapping all data file fields:
Make sure that all fields map correctly. If necessary, resolve unmatched or incorrectly
matched fields by mapping those fields individually.
If the matching is partially successful, all possible matches are added. To complete the
mapping, map remaining fields individually.
If no matches are found and no entries are in the Form Fields list, an error is generated. You
can delete mappings and map fields individually or start the import with the partial mapping.
If no fields are mapped, an error is generated, and you must load a mapping or map fields
manually.
Importing data
Importing data into a form involves loading a data file and a target form, defining preferences for the
import, and mapping data. To import data into a form, you must have Change permissions for the
fields to which you want to import data. For system fields such as Create-date, you must be the
administrator or subadministrator of the form.
To import data
1. In Data Import, create or open a mapping file.
2. Choose Import > Start Import.
If errors occur, the type of messages you receive depends on what you enter in the Bad
Records field, as described in Defining Data Import preferences.
After the import ends, a results message appears and the import log is updated. You can
use your imported data.
Stopping an import
You can stop an import before it ends. You are prompted to copy unprocessed records to the log.
There must be enough disk space in the import log partition to copy the records.
Page 1999 of 4705
Home
Using a saved mapping file

If you regularly perform a particular import, saving the mapping saves time and reduces errors
because you load the mapping file instead of reentering the mapping values. When you save a
mapping, this import information is saved:
The form name
The server that contains the form
The data file name
Mappings and fallback mappings
Options
Mapping files have an .armx extension. You can use .arm files from previous AR System releases,
but if you modify them, they are saved with an .armx extension.
Data Import reads and writes mappings in PC format, with CR LF at the end of each line.
To load a saved mapping file

1. Choose File > Open Mapping.
2. Select the mapping file.
3. Click Open.
The mapping is displayed under a tab. The mapping file name appears on the tab.
Importing and exporting Flashboards objects

You can import and export Flashboards data and definitions like other objects in BMC Remedy AR
System. See Exporting object definitions, views, and applications .
Notes
When exporting Flashboards, separately export the form, Flashboards variable,

and Flashboards. While exporting, if you select the All Related option, Flashboards
objects do not get exported.
When importing Flashboards, ensure that you import the Form first, followed by
Flashboards variable, and then Flashboards. If you do not follow this sequence,
Flashboards objects are not imported correctly.
If your objects are not displayed correctly after you import, see Troubleshooting BMC Remedy
Flashboards.
Page 2000 of 4705
Home
Exporting and importing data and definitions

You can export and import definitions and data in various ways in BMC Remedy AR System.
Definitions are descriptions of the structure in which objects, views, and applications in AR System
are organized, identified, and manipulated in the AR System server. Object definitions contain no
user data or entries. Data is extracted from requests in AR System.
To export and import definitions, use any of the following options:
Developer Studio menu options (See Using menu options in BMC Remedy Developer
Studio.)
The DefinitionImport.bat and DefinitionExport.bat command-line utilities (See
Enabling the import-export command-line utility.)
The C and Java APIs (See Developing an API program.)
To export data, use the command-line utility described below:
The runmacro command-line utility (See Enabling the runmacro command-line utility.
)
To import data, use the command-line utility described below:
The Data Import command-line utility (See Enabling the Data Import utility.)
This section describes the command line interfaces for importing and exporting data
and definitions.
Exporting objects and data to XML format
Enabling the import-export command-line utility
Enabling the runmacro command-line utility
Enabling the Data Import utility
Exporting data by using the AR Export command-line utility
Exporting objects and data to XML format

In this topic:
Exporting BMC Remedy AR System objects in XML
Exporting BMC Remedy AR System data in XML
Using XML with the BMC Remedy AR System API
To prepare to import objects or data, you can export them to an XML file.
Exporting BMC Remedy AR System objects in XML

Choosing the AR System XML format ( ARXML ) for exported objects produces an XML document
that is comparable to the BMC Remedy AR System definition file format. It is designed to follow the
syntax of the XML specification 1.0.
Specifically, every AR System object type has an associated structure definition in XML, which is
Page 2001 of 4705
Home
specified by the XML Schema Definition (* .xsd ) file. The *.xsd files reside on the AR System
server and are used to validate the AR System object definitions as valid XML.
Exported objects in XML format comprise an XML document, which might also be referred to as an
instance of a particular XML schema definition for that object. If the XML schema definitions are
loaded into an XML editor, someone who is knowledgeable about AR System objects and XML can
edit the XML document.
The XML schema definitions are designed to be similar to the definitions in the * .def files. For more
information about the XML Schema definitions of BMC Remedy AR System objects, see the data
structure information in the C API Reference .
AR System XML definition files are used the same way as the classic .def (definition) files. When
exporting objects in Developer Studio, you can choose AR XML Definition Files (* .xml ) in the Save
as type field of the Export File dialog box. The Import File dialog box works in the same way,
allowing you to bring in XML definitions to your BMC Remedy AR System server.
Exporting BMC Remedy AR System data in XML

To export in XML, create a report in BMC Remedy Mid Tier as you normally do. When you run the
report or save it to a file, select ARXML as the file type. The data is now ready to be manipulated
with your XML editor or imported into your XML-compatible applications.
To import XML data, run Data Import. Open your XML data file by selecting AR XML Files (* .xml )
in the Files of Type field. The other mapping and import steps are the same as previous versions of
BMC Remedy AR System Import tool.
Using XML with the BMC Remedy AR System API

BMC Remedy AR System includes XML schema definitions and API calls that you can use to
transform XML and AR System objects. The AR System API calls involving XML are divided into
two categories:
ARGet calls, which transform XML objects into AR System structures.
ARSet calls, which transform AR System structures into XML objects.
These calls use the AR System API structures that are described in the ar.h file. For more
information about the XML API calls, see the Developing an API program.
Enabling the import-export command-line utility

This section contains information about using the import/export command-line utility to import and
export definitions.
Import-export utility guidelines
DefinitionImport and DefinitionExport options
Import-export scenarios
Page 2002 of 4705
Home
Warning
If the AR System server has Record Object Relationships enabled, the relationships are
recorded as the 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.
Import-export utility guidelines

Use the following guidelines to run commands from the import/export command-line utility.
Commands and options are listed in DefinitionImport and DefinitionExport options.
On a computer with Developer Studio installed locally, set the current directory to the
directory that contains the Developer Studio executable (by default, *C:\Program Files\BMC
Software\ARSystem\developerstudio* ). The commands must be run in this directory. File
arguments without a directory path are created in the current directory.
Command-line import and export are provided by the DefinitionImport and
DefinitionExport commands. These commands are implemented as Windows batch ( .bat )
files.
Every command executed opens a separate AR System session, executes the command,
and logs out.
DefinitionImport and DefinitionExport parse options in the order they are listed in
DefinitionImport and DefinitionExport options. Options are interpreted in a predictable order
and might not be executed in the order you enter them.
You cannot perform an action against two servers with one command. For example, you
must issue two commands to export object definitions from one server and import them into
another server.
Enclose arguments that contain blank spaces or symbols in quotation marks.
DefinitionImport and DefinitionExport options

The options in the following table are optional unless the description states they are required.
Options that can be repeated are marked in the Repeat column.
Option
Parameter
Description
Repeat
Writes the version to standard output and exits without executing other options.
-version
-u
userName
Uses the account to connect to the server. Required.
-p
password
Uses the password to connect to the server. Required if the account has a
password.
-x
server
Connects to the server to import or export. Required.
-w
authentication
Uses external authentication string or Windows domain to connect to the server.
Page 2003 of 4705
Home
Option
Parameter
Description
portnum
portNumber
Uses the TCP port number to connect to the server. Required if the server does not
use the default port and there is no port mapper.
-e
fileName
Import from or export to the file. Required.
-o
logFileName
Write log and error output to the file. If not specified, the output is written to the
standard error output.
Import in place. Overwrite each existing object without deleting the object first.
DefinitionImport only.
-inplace
-lock
Repeat
lockType lockKey
Export the objects locked. Valid lockType values are

1 --Read only.
2 --Hidden.
The lockKey is a string used to enforce locking. DefinitionExport only.
-a
activeLinkName
-A
-b
DSOPoolname
DSOMappingname
formName
activeLinkGuideName
filterGuideName
Import or export the form.
Import or export the active link guide.
Import or export the filter guide.
Import or export all filter guides. Any -h options are ignored.
packingListName
Import or export the packing list.
Import or export all packing lists. Any -k options are ignored.
-K
-l
Import or export all active link guides. Any -g options are ignored.
-H
-k
Import or export the DSO mapping.
Import or export all forms. Any -f options are ignored.
-G
-h
Import or export all DSO mappings. Any -d options are ignored.
-F
-g
Import or export the DSO pool.

Import or export all DSO pools. Any -b options are ignored.
-D
-f
Import or export all active links. Any -a options are ignored.
-B
-d
Import or export the active link.
commandFileName
Import or export the objects specified by the XML command file.

To create an XML import/export command file from a working list or a packing list,
use the Save as Import/Export Commands pop-up menu command for packing lists
or working lists in Developer Studio. See the Introduction to Application
Development with BMC Remedy Developer Studio .
You can also use an XML file created from a packing list in an earlier release using
the Generate XML command in BMC Remedy Administrator. (This product is no
longer available.)
Any other object type options are ignored.
-m
menuName
Import or export the menu.
Page 2004 of 4705
Home
Option
Parameter
applicationName
escalationName
filerName
-T
-z
Import or export the escalation.
Import or export all escalations. Any -Q options are ignored.
-Q
-t
Import or export the application.

Import or export all applications. Any -n options are ignored.
-N
-q
Repeat
Import or export all menus. Any -m options are ignored.
-M
-n
Description
Import or export the filer.
Import or export all filters. Any -t options are ignored.
webServiceName
Import or export the web service.
Import or export all web services. Any -z options are ignored.
-Z
Import-export scenarios
The following are examples of common tasks you might perform with DefinitionExport and
DefinitionImport.
Exporting objects from a AR System server scenario

When you export objects from the server, you export objects to a target file. You can export all
objects for all forms by using the following command format:
DefinitionExport -u <userName> [-p <password>] -x <serverName>

-e <targetFileName> -F
To export objects from a single form, use the following command format:

-e <targetFileName> -f <formName>
To parse an XML packing list, and export all objects defined in that packing list, use the following
command format:

-e <targetFileName> -l <packingList.xml>
Note
You cannot export server objects that include a percent sign (%) in their name.
Page 2005 of 4705
Home
Importing objects into a AR System server scenario

When you import objects into the server, you import objects from a source file. You can import all
objects for all forms by using the following command format:
DefinitionImport -u <userName> [-p <password>] -x <serverName>

-e <sourceFile> -F
To import specific objects from a source file, use the following command format:

-e <sourceFile> -f <formName> -a <activeLinkName>
To parse an XML packing list, and import all objects defined in that packing list, use the following
command format:

-e <sourceFile> -l <packingListName>.xml
The -l option parses the XML packing list and imports all objects defined in the packing list. This
option overrides other options in the same command.
Enabling the runmacro command-line utility

The AR System server includes the runmacro utility, which can run a macro or export data as a
background process without a GUI. The runmacro utility can be run from filter or escalation
workflow or as a standalone process (that is, a Windows batch file or a UNIX script). Third-party
applications can use the runmacro utility to run AR System macros. Because runmacro
functionality provides no GUI support, it can execute processes that run in the background, but it
cannot perform tasks such as displaying a results list.
To run the runmacro utility, you must set the library path to the directory where the runmacro
executable resides. To do so, use these commands:
Solaris and Linux
LD_LIBRARY_PATH=<runmacroDir>
HP-UX
SHLIB=<runmacroDir>
AIX
Page 2006 of 4705
Home
LIBPATH=<runmacroDir>
The runmacro command has the following formats. Items between square brackets are optional.
Enclose arguments that contain blank spaces or symbols in double quotation marks.
You can use the original version of runmacro without the output file option ( -o):
runmacro [-h <homeDir>] [-d <macroDir>]

[{-x <serverName>} ...] { -e | -i } <macroName>
[-p <parameter>=<value> ...] \[\-U <userName>] [-P <password>]
[-Q <internalQualificationFormat>]
[-q <clientToolQualificationFormat>]
[-Z <internalFormatQualificationFileName>]
[-z <clientToolFormatQualificationFileName>]
[{-w | -W } <externalAuthenticationString>] [-a <portNumber>]
[-O]
You can use runmacro with the -o option to use the arcopy syntax, which copies the
output to a file:
runmacro -o <outputFileName> [{-x <server>} ...] -U <user>]

[-P <password>] [{ -f | -s} <form>] [-t {arx|csv|xml}]
[-Q <internalQualificationFormat>]
[-q <clientToolQualificationFormat>]
[-Z <internalFormatQualificationFileName>]
[-z <clientToolFormatQualificationFileName>]
[{-w | -W } <externalAuthenticationString>] [-a <portNumber>]
When you use the -o option to export data with attachments, the attachments folder is created in
the same directory as the export file. The attachments folder name uses an integer time stamp (for
example, 917732184), and the folder location is specified in the output file name of the runmacro
command.
When creating macros, you can record a login with the proper permissions if you perform actions
that require those permissions (for example, an administrator deleting records). If your macro does
not record a login, you must specify login information using the -U option and the -P option (if
necessary).
This table lists the runmacro options, which can appear in any order in the command line:
Option
Description
-o
Output file name Name of the file in which to store the data. The file is initially truncated, and then all the data is
written to the file (one data set after another).
Page 2007 of 4705
Home
Option
Description
-h
Home directory Path to the ARSystemHomeDir directory. If you do not specify the -d option, runmacro also looks
in this directory for the arcmds directory that contains the macro to run.
-d
Macro directory Directory that contains the macro if your macro is not in the ARSystemHomeDir\arcmds directory or
if you do not have an ARSystemHomeDir directory.
-x
Server name Name of a server to connect to. This option might be included more than once to connect to multiple
servers. Use the following format: -x serverName
-e (or
Macro name Specifies the macro to run.
-i )
-p
Parameter Value for a parameter. There might be more than one -p option in a command line. If the macro specified
(using the -e or -i options) has a parameter, a value can be supplied by naming that parameter and assigning a value.
If the parameter name or value includes a space or other special character, the data must be enclosed in quotation
marks to cause proper interpretation of the special characters. Use the following format for each parameter specified: -p
parameter = value
-U
User name Required login parameter that identifies the user account. The -U option must be in uppercase.
-P
Password Optional login parameter that identifies the user account. Omit the -P if the user account has no password.
The -P option must be in uppercase.
-Q
Internal qualification format Query in AR System internal format.
-q
Client tool qualification format this is a regular query.

Within the query string, double quotation marks must be preceded by a backslash (), which functions as an escape
character. For example:
runmacro.exe -o <outputFileName>-x <serverName>
-U <userName> -P <password> -f <form> -t {arx|csv|xml}
-q "'Submitter'=\"tester\" AND ('Create Date' >|
\"5/9/2007\" AND 'Create Date' < \"5/16/2007\")"
-Z
Internal format qualification file name File name containing the query in Remedy internal format.
-z
Client tool format qualification file name File name containing a regular query.
-w (or
-W)
Authenticator Name of the external authentication string or Windows NT domain. This is related to the Login window's
Authentication field. See Authentication String Alias introduction.
-a
Port number Port number to which to connect the server.
-f (or
Form name Form that is exported. The -f (or -s) option can be repeated multiple times if there are several forms to
-s)
export. If multiple servers are selected, each server is searched for the form, and the first one found is all that is
exported. To control this, specify only one server environment for the operation. If the -f (or -s) option is not specified,
the system exports all available regular data forms. It does not export join or external forms.
-t
Type of file to write File type for the output file: arx, csv, or xml. If not specified, the default of arx is used.
-O
Forces override If the user has already logged in as this same user from a different IP address, this option tells the
server to use the new IP address of the runmacro client and invalidates the old IP address.
Note: This option does not apply to users with administrator permissions.
Enabling the Data Import utility

Page 2008 of 4705
Home
Localization tips for importing

Importing with a mapping file
Importing without a mapping file
Importing in a multithreaded environment
Data Import command-line utility options
Data Import utility scenarios
Use the Data Import command-line utility (a Java utility) to automate importing data in a multi- or
single-threaded environment. (See Importing in a multithreaded environment.)
You can import with or without a mapping file. See Importing with a mapping file and Importing
without a mapping file.
To use the Data Import utility on Windows

1. Open the DataImport.bat file in ARSystemInstallDir/dataimporttool.
2. Edit the batch file to set the following environment variables:
APIDROP The location where arapiextvers.jar and arapivers.jar are installed.
JAVA_HOME The location of your JDK (for example, C:\Program Files\Java\
jdk1.5.0_07 ).
Path
For example:
set APIDROP=.\plugins\com.bmc.arsys.studio.api_7.6.04\lib
if not exist "%JAVA_HOME%" set JAVA_HOME=jdkPath
set PATH=%JAVA_HOME%\bin;%PATH%;%APIDROP%
3. Add the appropriate options to the command line in the batch file. Make sure the .jar file
names in the classpath reflect the appropriate release of BMC Remedy AR System, for
example:
java -classpath %APIDROP%arapi7604.jar;%APIDROP%arapiext8100.jar;

com.bmc.arsys.apiext.data.DataImport [options]
For a list of available options, see Data Import command-line utility options.
4. At the command line, run the batch file.
To use the Data Import utility on UNIX

1. Navigate to the ARSystemHome/api/lib directory and make sure that the following .jar files,
required to run the Data Import Utility, are present in the lib folder:
arapivers.jar
arapiextvers.jar
Page 2009 of 4705
1.
Home
log4j-1.2.14.jar
For example:
arap i7604.jar
arapiext 7604*.jar*
log4j-1.2.14.jar
2. Create a DataImport.sh file in the ARSystemHome/api/lib directory.
3. Set the following environment variables in the DataImport.sh file:
APIDROP The location where arapiextvers.jar and arapivers.jar are installed.
JAVA_HOME The location of your JDK (for example, /usr/Java/jdk1.5.0_14 ).
Path
For example:
#!/bin/sh
APIDROP=ARSystemHome/api/lib
JAVA_HOME=${JAVA_HOME:-jdkPath}
export JAVA_HOME
PATH=$JAVA_HOME/bin:$PATH:$APIDROP
export PATH
Note
Either execute the following command from the ARSystemHome/api/lib
directory or set the Library Path and the Path variable using the following
command: export LD_LIBRARY_PATH=$ARINSTALL/api/lib:$
ARINSTALL/bin:$LD_LIBRARY_PATH export PATH=$ARINSTALL/api/
lib:$ARINSTALL/bin:$PATH
4. Enter the following command to use the Data Import utility on UNIX:
exec java -cp $APIDROP/arapi7604.jar:$APIDROP/log4j-1.2.14.jar:$APIDROP/

arapiext7604.jar
com.bmc.arsys.apiext.data.DataImport${1+"$@"}
The use of ${1+"$@"} option allows the command to accept inputs when the script is called.
Note
For a list of available options, see Data Import command-line utility options.
Page 2010 of 4705
Home
Localization tips for importing

On Chinese UNIX systems, CSV and ASCII files cannot be imported if they contain Date/Time
fields.
When using the Data Import utility on Japanese UNIX systems, convert the data and .armx
mapping files to EUC format before the files are moved to the UNIX server. (The .arx and .xml data
files are already in EUC format when they are generated in the client tool, but the .csv file is not.
Therefore, the .armx and .csv files must be converted.) Make sure that all of the data file names
and a mapping file names are in English.

You can import data through the Data Import utility by using a mapping file created in Data Import.
You can use the mapping file on any platform. For more information about Data Import mapping,
see Creating mapping files.
Specifying the -M or -m option in the command line determines whether you use a mapping file.
Note
If you are copying the mapping file between different operating systems (such as
Windows to UNIX), make sure that the file is converted properly so that the operating
system can read the file.
You can override specific settings saved in the mapping file by using additional options. In this way,
you can use the data mappings you created for one data file and destination form for imports with a
different data file and form combination.

Importing without a mapping refers to running the Data Import command-line utility with no mapping
definition to instruct the system how to map fields.
BMC recommends that you use AR Export ( .arx ) and AR XML (.xml ) file formats when importing
without a mapping file. In these file formats, field values are mapped by matching field IDs, which
are both included in the file. For CSV files, field values are mapped by matching the field labels (if
present in the file) to the field names (database names of the fields) retrieved from the server.
When a browser exports data into a CSV file, the field labels and the field names are not
necessarily the same. Only fields with names and labels that match are auto-mapped.
Consequently, if CSV files do not include field labels, the field values cannot be mapped.
Without a mapping file, include the server name, form name, and data file name in the command
line. Mappings are built by querying the server and the data file.
Page 2011 of 4705
Home
Importing in a multithreaded environment

To import data on multiple threads, configure the following options to specify multithreaded
functionality:
-o
-z
-filelist
-threads
For information about these options, see Data Import command-line utility options.
Tips for running the Data Import Utility in a multithreaded environment

When running the Data Import utility in a multithreaded environment, remember these tips:
You must include a form name in the Data Import utility command. (If a mapping file is
provided and includes a form name, the form name is optional.)
If any data files in the specified data directory contain data from a different form, the Data
Import utility cannot resolve the difference. The utility imports the data in specified form only.
If a mapping file is specified and if the specified form uses the same mapping file for all data
files, the Data Import utility imports all file types ( .arx, .csv, .xml, and .ascii ).
For .arx and .xml files, if you run the Data Import utility without including a form name and a
mapping file, data from the individual file is imported to their respective forms, so make sure
that data files are not interdependent. For example, when importing Group form and User
form data, users belong to groups. The User form data is dependant on Group form data,
and the Data Import utility cannot resolve this dependency.
For CSV and ASCII files, you must include a form name in the command because these files
do not include form information.
The Data Import utility does not validate workflow on forms where data is imported.
For AR System 7.1.00 and later versions, the Data Import utility uses bulk APIs (unless the e option is used). When a bulk API fails in its first attempt, it rolls back the entire operation
and retries up to the last completed entries again with bulk API. The remaining records are
imported it by using individual APIs.
Options that you specify to handle duplicate records ( -D ), bad records, and multiple
matches (-t ) are common to all of the threads.
There is no explicit command-line option for bad-records handling. By default, the Data
Import utility skips the bad records.
In an .armx mapping file, you can specify bad-records handling as follows:
<datahandling *badrecords="SKIP"*
duplicaterecords="GEN_NEW_ID"
stripleading="false" striptrailing="false" transactionSize="0"
truncate="false"/>
In an .arm mapping file, you can specify:

Page 2012 of 4705
Home
"Bad-Record-Handling: 1"
Data Import command-line utility options

Using the custom_options.xml file
Using the options.xml file
Use the following format in the command line. Items between square brackets are optional.
com.bmc.arsys.apiext.data.DataImport -u userName -p password

-x serverName [-w externalAuthenticationString] [-r rpcNumber]
[-a portNumber] [-custom custom_optionsFilePath]
[-f destinationFormName] -o dataFilePath
[-filelist listOfFiles] [-z options.xmlFilePath]
[-threads numberOfThreads] [-l logFilePath]
[-e duplicateField] [-b bulk size] [-g activateBulkMode]
[-n suppressFilters][-s suppressassociations] [-t multiMatchOption] [-v] [-i]
[-D duplicateIDOption] [-q option] [-c option] [-h
[-charset name] [-M fullyQualifiedMappingFileName]
option]
Note
[-m mappingFileName ] [-d directoryWithMappingFile ] Enclose arguments that contain
blank spaces or symbols in double quotation marks.
The following table describes available options.

Option
Option name
Description
-u
User name
Required login parameter that identifies the user account.

Note: Every cross-platform CLI command opens a separate Data Import session, executes the
command, and logs out. Therefore, you must log in with every command. If Data Import does
not find the user name, Data Import prints the usage messages and exits.
-p
Password
Password for the user account. If the user account has no password, omit the -p option.
-x
Server name
The server to log in to. If you do not specify the -x option, the server name in the mapping file is
used.
-w
Authentication string
Name of an external authentication string or Windows NT domain. This is related to the Login
window's Authentication field, which is discussed in Setting up an authentication alias.
-r
RPC program
number
Private server, for example, if a dedicated import server is available. If you do not specify the -r
option, the default administrator server's RPC program number (390600) is used.
-a
TCP port number
Page 2013 of 4705
Home
Option
Option name
Description
Port number for the server. This value is especially important in a multiple server environment.
The option also identifies a TCD specific port, if chosen.
custom
Path to
custom_options.xml
Specifies the path to the custom_options.xml file, which is used to specify date and time
formats, the separators to be used, and other information. You can use this option if the source
data file is in CSV or ASCII format. See Using the custom_options.xml file.
Note: During installation, a sample empty custom_options.xml file is installed in the
installation folders for Developer Studio and Data Import. You can change the name and store
it anywhere.
-f
Destination form
name

Destination form name Name of the form to import data into. If you do not specify the -f
option, the form specified in the mapping file is used.
Destination form name or pair. A single name indicates that the form name in the source data
file matches the form name on the server. To specify a pair of names, separate the form names
with an equal sign, without any spaces around the equal sign: " destinationForm" =" fileForm".
The destination form is the form on the server into which data is imported. The file form is the
form specified in the data file. Specifying pairs maps data from one form (specified in the data
file) to a different form (identified on the server). You can specify multiple pairs by using this
option multiple times, for example:
-f "Target_form_a"="File_form_b" -f "Target_form_c"="File_form_d"
If the -f option is not specified, Data Import tries to import all data sets in the source data file.
For each data set, if a matching destination form is found on the server, the data is imported. If
no matching form is found, the data set is ignored.
-o
Data File Path

Path to a directory of data files For multithreaded environments, the -o option
specifies the path to the directory that contains the data files to import.
Path to data file For single-threaded environments, the -o option specifies the file that
contains the data files to import.
If you do not specify the -o option, the data file specified in the mapping file is used.
-z
Path to the
options.xml file
Specifies the path to the options.xml file, which contains the data import commands and the
import parameters for individual files and directories for multithreaded import. The Data Import
command-line utility uses the -z option to identify the location of the options.xml file. See
Using the options.xml file.
Note: The -z option cannot be used in the options.xml file; if used, the Data Import
command-line utility disregards this option.
-filelist
threads
(For multithreaded
environments only)
List of data files to
import
The data files can be of any type (for example, ARX, CSV, XML, and ASC ). All of the data is
imported into the form designated with the -f or -M option. If you do not specify the -filelist
(For multithreaded
environments only)
If you do not specify the -threads option, the default of 50 threads is used. If the number of
Number of threads in
the pool.
threads value or the default value (50), the number of threads used is equal to the number of
option, the command imports all the data files in the directory specified with the -o option,
regardless of file type.
files in the data directory or number of files you specify in the -filelist option is less than the files in the data directory or number of files specified in -filelist option.
Note: Make sure that your hardware configuration can handle the number of threads that you
enter.
Page 2014 of 4705
Home
Option
Option name
Description
-l
Full path name of the

log file
Use this option to log details of the import execution.

If you do not specify this option, the logs will appear on the console instead of displaying an
error message that a log file path was not specified.
-ca
Specifies where log

files appear
The options are:

0 (the default) Logs appear on the console.
1 Logs do not appear on the console. They appear in the log file specified with the -l
option. If the -l option is not used, the logs will not be created.
-e
Duplicate field
Field ID of the field to check for duplicate data. For example, for the Short Description field,
enter 8. To specify multiple values for a single schema, separate them with commas and
double quotation marks (for example, "2,4,8" ). The maximum number of IDs you can specify
is 6. From this release of BMC Remedy AR System, you can now specify multiple values for
multiple schemas. For this, separate the schema names (and their values) by a semi-colon and
the values by commas (For example, SchemaName=1,2,3; SchemaName=4,7,8 ). The
maximum number of IDs you can specify is 6. Make sure that the source data file includes
values for all the fields that are being used for checking duplicate data. When -e option is
omitted, then Request ID field (field ID 1) is used. Additionally, if the -e option is not used for
importing records, the Data Import utility uses bulk mode to import records. (See the -b option
for more information about the bulk size.)
-b
Bulk size
Specifies the number of records to process in bulk simultaneously. For AR System 7.1.00 and
later versions, the default size is 100.
Note: If the -e option is used, records are imported individually. If the value of the -b option is
set to 0, bulk mode will not be used.
-g
Activate Bulk Mode
If the -e option is used, the bulk transaction mode is switched off by default. In this case, you
can still activate the bulk transaction mode using the -g option.
Note: The bulk transaction mode is purposefully switched off with -e option as it gives different
results than sequential import when there are duplicate records within the data file itself. To
forcefully use bulk mode when the -e option is used, you can use the -g option. You can decide
whether you want to use the -g option when there are duplicate records in your data files. For
example, you must use the "-g 1 " value in the Java Import command line to use the bulk mode
. If any value other than "-g 1 " is used, the force bulk mode is not activated.
-n
Suppress filters
Suppresses the merge filters during merging of entries on forms.
-s
Suppress
Setting this flag causes the server to suspend enforcement of associations on entries getting
associations
imported. Associations are still enforced on other entries affected by workflow that might be
triggered by entries getting imported. The server will only honor this flag if the user of the
import tool is an administrator.
Multiple match
Use when more than one entry matches. Enter a value of 3 to affect the first match, and a
options
value of 5 to affect all matches.
-v
Forces override
If the user has logged in from a different IP address, this option tells the server to use the new
IP address of the Data Import client and invalidates the old IP address.
-i
Suppress default
values
If specified, this option will ignore the default values of fields if the value in the data file is null or
not supplied.
-t
0 Do not suppress default values for mapped fields, but ignore non-mapped fields.
1 Suppress default values for mapped fields, but ignore non-mapped fields.
2 Suppress default values for mapped fields, suppress default values for non-mapped
fields by explicitly putting NULL value.
Page 2015 of 4705
Home
Option
Option name
Description
3 Do not suppress default values for mapped fields, suppress default values for
non-mapped fields by explicitly putting NULL value.
Note: If the value of D is set to 4 (update option), then the Data Import utility does not
suppress the default values while creating new records.
Duplicate ID
-D
Defines how to process records that contain request IDs that duplicate those already in the
form. Include one of the following numbers with this option:
0 Generate new ID for all records.
1 Reject duplicate records.
2 Generate new IDs for duplicate records.
3 Replace old records with new records.
4 Update old records with new records' data (the default).
5 Reject duplicate records silently.
Note: The Reject duplicate records silently mode (parameter value 5) is available in the BMC
Remedy Data Import command-line utility only.
-q
Suppresses the field

property for non-core
fields.
Suppresses the required field property for non-core fields. The options are 1 (on) and 0 (off) .
-c
Truncates character
values
Truncates character values that are longer than the field length for character fields. The options
-h
Suppresses pattern
matching for fields
If supplied, the $PATTERN$ field limit is ignored. The options are 1 (on) and 0 (off) .
Specifies the
character set used in
the data file
The character set name must be supplied as listed in the IANA Charset Registry.
charset
-debug
Sets the log level
The log levels are:
are 1 (on) and 0 (off) .
0: OFF
1: ERROR
2: WARN
3: INFO
4: DEBUG
5: TRACE
6: ALL
OFF does not log any information, and ALL is the maximum log level, which logs detailed log
information. The default log level is 3.
To import data with a mapping file, use either -M or a combination of -m and -d to specify the
mapping file to use. (You cannot use both the combination of -m and -d with -M ; they are mutually
exclusive.)
Note
The combination of -m and -d options is supported for the legacy .arm mapping file types
only. If the mapping file is .armx, only -M is valid.
Page 2016 of 4705
Home
The following table describes the mapping file options. For more information, see Importing with a
mapping file.
Option
Description
-M
Fully qualified path name of the mapping file to use.
-m
Name of the mapping file to use. You can verify the required name by opening the mapping file and using the string
contained in the first line of the file.
-d
Directory that contains the mapping file being referenced with the -m option.
Using the custom_options.xml file

If the source data file is in CSV or ASCII format, you can use the custom_options.xml file to
specify date and time formats, the separators to be used, and other information.
Data Import searches for formats (date and time, separators, and so on) as follows:
1. It searches the mapping file, if specified by the user.
2. In the absence of a mapping file, it searches for custom_options.xml, if the -custom
command-line parameter is used.
3. If neither the mapping file nor custom_options.xml is specified, it searches for the formats
defined by the Sun JDK for the default system locale.
Note
You can use the mapping file and the custom_options.xml file simultaneously. In
such cases, the a.m. and p.m. symbol settings and the separator settings of the
mapping file take precedence. However, the date and time formats in
custom_options.xml are considered with the formats in the mapping file for
parsing date and time values. In such cases, custom_options.xml provides
additional date and time formats (the mapping file can have only one), which is
helpful for parsing data files that contain date and time strings of different locales.
Using the options.xml file

The options.xml file contains the data import commands and import parameters for single or
multithreaded import. For all the data import commands included in this file, the Data Import
command-line utility starts as a new JVM only once.
The Data Import command-line utility uses the options.xml file as the input. The utility identifies the
location of the options.xml file using the new command line parameter, -z.
Consider the following important points before using the options.xml file:
Page 2017 of 4705
Home
The Data Import command-line utility follows the sequence of the data import commands
defined in the options.xml file.
Each command tag listed in the options.xml file will be executed. If the same command tag
occurs multiple times, the Data Import command-line utility executes the command tags as
many number of times as listed.
Important
The Data Import command-line utility invocation command must have -x, -u, -p, and -z
parameters to start importing the data files using the options.xml file.
The parameters that are included in the options.xml file override all the parameters passed
through command line.
If any error occurs during the command execution in the options.xml file, the Data Import
command-line utility continues to execute the further commands listed in file.
The Data Import command-line utility allows sequential and parallel importing of data in a
single JVM invocation instance. This is done through the options.xml file using the isSerial
attribute. If the value of the isSerial attribute is 'False' (default) or the attribute is not
specified, the Data Import command-line utility imports the data by using the parallel mode.
During parallel importing, the utility imports multiple data files simultaneously.
The options.xml file has a global tag (optional) for global parameters. The global
parameters can be overridden by individual command tags (local parameters specified in
individual commands), except for the threads and the debug parameters. These global
parameters cannot be overridden by local parameters.
Note
The threads and the debug parameters are not considered if they are specified as local
parameters in a command tag format.
If the -o and -z parameters are combined, the Data Import command-line utility treats the
paths specified for the -z parameter as relative. The tool thus combines the paths specified
in the -o and -z parameters and then continues importing the files listed in options.xml file.
If only the -z parameter value is specified, the path specified for the -z parameter is
considered as the absolute path.
For example, if the following values are specified:
-o "c:\temp" -z "opt\FileName.arx"
The final path (relative path) is "c:\temp\opt\FileName.arx"
And if the following values are specified:
Page 2018 of 4705
Home
-z " c:\opt\FileName.arx"
The final path (absolute path) is "c:\opt\FileName.arx"
Note
The preceding rule is true only for the data file's path specified in the -o
parameter; all the remaining parameters that take the file path as an input
are used as absolute paths or as relative paths with respect to the current
invocation directory.
The -z parameter cannot be used with the pattern and filelist parameters through the
command line. These parameters can only be used independently or with the -o parameter (
as a directory).
The data import invocation using the -z parameter generates a summary file containing the
results of all the data import commands defined in the options.xml file. This summary file
has the same name as the options.xml file. For example, if the options.xml file has the
name, option_fnd.xml, the Data Import command-line utility generates a summary file
named option_fnd_summary.log.
If the -l parameter (full path name of the log file) is specified for every command in the
options.xml file, the Data Import command-line utility creates separate log files for every
command tag. If the log file is the same for multiple command tags in the options.xml file,
all the logging details for these command tags are written in that one log file. If the -l
parameter is not specified in the command and in the options.xml file, the Data Import
command-line utility creates a log file in the current directory with the same name as the
data file name (datafilename.log ).
If the debug parameter is specified as a global parameter, the value of this parameter will be
common for all the commands in the options.xml file.
In the options.xml file, the number of threads in a pool can be configured at the global level
by setting the -threads parameter in the global tag with the optimum value. This switch is
optional; if the command does not have this switch, the value of the -threads parameter is
set to its default value (50).
Note
If the -threads parameter is specified as a global parameter, it overrides the threads
option that was provided as a command line parameter while invoking Data Import
command-line utility.
options.xml file scenario

The following XML tags and attributes can be used in the options.xml file:
Page 2019 of 4705
Home
import Root element of the options.xml file.

global Contains the global parameters with the attributes (name and value).
commands Contains the attribute, isSerial (default value, False) for serial and parallel
importing.
command Contains the parameter with attributes (name and value).
Note
You can rename the options.xml file to any custom name. Make sure that the file
contains only the above XML tags and attributes, and is a valid and well-formed file. If the
options.xml file is not a valid file or it does not exist, the Data Import command-line utility
displays an error and will not proceed further.
<import>
<global>
<parameter name ="x" value="ServerName"/>
<parameter name ="u" value="UserName"/>
<parameter name ="p" value="Password"/>
<parameter name ="debug" value="3"/>
<parameter name ="threads" value="32"/>
</global>
<commands isSerial = "true">
<command>
<parameter name ="D" value="1"/>
<parameter name ="o" value="DataFileDirPath"/>
</command>
<command>
<parameter name ="D" value="3"/>
<parameter name ="o" value="DataFileDirPath1"/>
<parameter name ="e" value= "10000,10050"/>
</command>
</commands>
<import>
Data Import utility scenarios

In this topic:
Multithreaded environment scenarios
With a mapping file scenarios
Without a mapping file scenarios
Page 2020 of 4705
Home
Multithreaded environment scenarios

The following examples show you how you can use the Data Import utility in a multithreaded
environment:
In the following example, the -o option specifies the path to the directory that contains the
data files to import. All of the data in the files is imported to the specified form.
com.bmc.arsys.apiext.data.DataImport -x
formName
-o dataFilePath -l logFilePath
serverName -u
userName
-p
password -f
For example:
com.bmc.arsys.apiext.data.DataImport -x machine1 -u joeuser

-p 1a2b3c -f HelpDesk -o "C:\files" -l "C:\files\test.log"
The data in the files in C:\files is imported to the HelpDesk form. A log is created in test.log.
In the following example, the -filelist option is used with -o, and only the data files listed are
used. All of the data in the files is imported to the specified form.
-f
formName -o
dataFilePath -filelist
serverName -u
listOfFiles
userName -p
-l
password
logFilePath
For example:
com.bmc.arsys.apiext.data.DataImport -x machine1 -u joeuser

-p 1a2b3c -f HelpDesk -o "c:\files" -filelist "user.arx,
user.csv,abc.xml,xyz.ascii" -l "c:\files\test.log"
The data in the user.arx, user.csv, abc.xml, and xyz.ascii files in C:\files is imported to the
HelpDesk form. A log is created in test.log.
With a mapping file scenarios

The following examples show you how you can use Data Import utility with a mapping file:
In the following example, the server name, form name, and data file name are optional
because the mapping file contains the information:
com.bmc.arsys.apiext.data.DataImport -u
-d mappingFileDir -l logFile
userName -p
password -m
mappingFileName
Page 2021 of 4705
Home
In the following example, the server name, form name, and data file name override the
names in the mapping file. When you use the Data Import utility with a mapping file, you can
override one or more of those names.
-m
mappingFileName -d
serverName -u
-p
password
dataFilePath -f
userName
formName
mappingFileDir -l logFile -o
Without a mapping file scenarios

Without a mapping file, you must specify the server name and data file name because there is no
mapping file to provide such information.
The -d and -a options are not shown in the following examples, but if you work with multiple servers
on the same computer, you can use -d for duplicate record handling and -a to specify a port
number.
The following examples show how you can use the Data Import utility without a mapping file:
In the following example, minimal options are used. The dataFilePath specifies the data file
with path to import. If there are multiple data sets in the same data file, an import is
attempted for all forms.
com.bmc.arsys.apiext.data.DataImport -x serverName -u
dataFilePath
-l
userName
-p
password -o
logFile
In the following example, the formName determines which set of data from the data file is
imported to the server. The form name on the server and in the data file must match.
formName
-o dataFilePath -l logFileName
serverName -u
userName -p
password -f
In the following example, an import is being attempted into the form called formA on the
server, but the data comes from formB in the data file.
-f "formA=formB" -o
dataFilePath -l
serverName -u
userName
-p
password
logFileName
Page 2022 of 4705
Home
Exporting data by using the AR Export command-line utility

Use the BMC Remedy AR Export command-line utility to export the contents of a BMC Remedy AR
System server form to an .arx file. You can extract data from more than one AR System server
form and consolidate the data in a single .arx file. You can also exclude the data of certain fields
from being exported to the .arx file. The AR Export utility also supports Unicode data.
Note
The AR Export utility does not export the contents of an AR System server form to a CSV
file or to an XML file.
The utility can extract all the data from an AR System server form. The utility can also extract data
from a form based on the string that defines the qualification criteria. If the form contains an
attachment, the attachment data is extracted to a folder whose name is the same as that of the .arx
file. By default, the utility adds a time stamp to the folder containing the attachment data.
Running the utility

You can run this utility from a command prompt using a batch file ( arexport.bat) on Microsoft
Windows platform or a script (arexport.sh) on UNIX platform. The utility is installed as part of the
BMC Remedy AR System server installation. The arexport.bat file is located in the <
ARServerInstallationDirectory>\artools folder in Windows and the arexport.sh file is located in
the <ARServerInstallationDirectory>/artools folder in UNIX.
Use the following command to run the export utility and enter qualification criteria. Parameters
enclosed in square brackets are optional.
arexport.bat -u <userName> -x <serverName> -p <password> -t <TCPPortNumber>

-form <formName> -datafile <outputFile>
[ -delim <delimiter>
-a <authenticationString>
-T <transactionSize>
-L <logfilePath>
-e <exclusionFieldList>
-q <qualificationString>
-o <overwriteOption>
-timestamp <timeStamp>
-timeout <timeoutValue>
]
The following table describes the arexport command options, which can be used in any order in
the command:
Page 2023 of 4705
Home
Option
Description
-u
Specify the user name that identifies the user account for the AR System server.
-p
Specify the password for the user account. If the user account has no password, use -p "".
-a
Specify the name of the external authentication string or Windows NT domain. This is related to the Login window's
Authentication field. See Authentication String Alias introduction.
-x
Specify the name of the server to connect to.
-t
Specify the TCP port number to connect to. If the port number is unknown, use -t 0.
-O
Use this option to overwrite existing attachments and data file. The following values are valid for this option:
1 - Overwrite existing attachments and data file.
0 - Do not overwrite existing attachments and data file.
-form
Specify the name of the form from which you want to export data. To export data from multiple forms, use a
comma-separated list of form names in the following format:
-form "form1, form2, form3"
If the -form option is not specified, an error message is logged in the artools.log file and the utility stops running.
-datafile
Specify the name and path of the file in which to store the data. If you do not specify the file extension, the utility
adds the .arx extension to the data file.
-e
Specify the field IDs for which you do not want to export data. You can use a comma-separated list in the following
format:
-e "3, 7"
-T
Specify the size of the transaction. The default size is 100 records.
-L
Specify the log file path. To specify a log file path, use the following format:
-L c:\ARExport\exportlog.log
Note
Ensure that the log file path exists and that the file extension is included in your command.
When you specify the -L option, logs are not generated in the default artools.log file located in the <
ARServerInstallationDirectory>\Arserver\Db folder. For information about the logging for the AR Export
command, see Logging for the arexport command.
-q
Specify a string that qualifies the search criteria. Use an escape character if the qualification string contains double
quotes (for example, if the qualification string is 'RequestID' = "000000011"').
Use the following format:
"'1' = \"000000011\""
where 1 is the field ID.
Note
Page 2024 of 4705
Home
Option
Description
Do not use a field label as the qualification string. You must use a field name or a field ID as the
qualification string.
-delim
Specify the delimiting character to use when you specify multiple values to an option. By default, a comma is the
delimiting character. Use the -delim option with the -form and -e options that take multiple values as input. After
you specify a delimiter, you must use the same delimiter for all the options that take multiple values as input. Not
using the same delimiter might cause incorrect data extraction.
For example, if you enter the following command, the AR Export utility ignores the field IDs (4, 6) listed in the -e
option and includes the data for all the fields:
arexport.bat -u <userName> -p <password> -x <serverName> -delim ";" -form "form1;form2" -e 4,6
The following command successfully extracts the data by excluding the data of the fields with IDs 4 and 6.
arexport.bat -u <userName> -p <password> -x <serverName> -delim ";" -form "form1;form2" -e 4;6
Use the -delim option if the form name itself contains a comma. For example, use the following format to specify a
semicolon as the delimiter if the form name contains a comma:
arexport.bat -u <userName> -p <password> -x <serverName> -form "Test,form1;form2" -datafile <

dataFilePath> -delim ";"
Note
Test,form1 is the name of the form containing a comma.
Use this option to add a time stamp to the folder containing form attachment data. This option has the following
timestamp
values:
1 - Do not add a time stamp.
0 - Add a time stamp.
-timeout
Specify the timeout period for connecting to the server. You can specify Normal, Long, and XLong seconds after
which the timeout occurs. Use the following format to specify the timeout values:
-timeout Normal:Long:XLong
The default timeout values for Normal:Long:XLong are 120:300:1800.
Note
You must specify all three values even if you want to set one timeout value.
For example, if you want to set the Long timeout value to 400 seconds, use -timeout 120:400:1800.
Page 2025 of 4705
Home
Example
Consider a situation in which a user with the user name Demo needs to export data from a form
named Form1 into the data file c:\ARExport\data.arx, using a qualification string such as 'FieldID'="
000000001123" with transaction size 50, and needs to exclude data for fields with IDs 8 and 5. The
arexport command would look like the following:
Windows
arexport.bat -u Demo -x myServer -p "abc" -form "Form1" -datafile "c:\ARExport\data.arx
" -T 50 -e "8, 5" -q "'1' = \"000000001123\""
UNIX
arexport.sh -u Demo -x myServer -p "abc" -form "Form1" -datafile "/ARExport/data.arx" T 50 -e "8, 5" -q "'1' = \"000000001123\""
Logging for the arexport command

If an exception occurs when the form data is being exported, the exported records of that form are
rolled back and removed from the .arx file and the details are logged in the artools.log file.
On Windows, the artools.log file is located in the <ARServerInstallationDirectory>\Arserver\Db
folder.
On UNIX, the artools.log file is located in the <ARServerInstallationDirectory>\db folder.
Using the Request ID to improve performance or security

This section contains information about using the Request ID to improve the performance or
enhance the security of your BMC Remedy AR System environment:
Working with the Request ID field
Changing the next available ID for new requests
Changing the Request ID field length or prefix
Preserving Request ID field values
Changing Request ID field values to a new format
Updating the Request ID field in other AR System tables
Note
These procedures address the most commonly requested BMC Remedy AR System
technical information. For access to the complete set of BMC Remedy AR System
technical information and procedures, visit the Customer Support website.
Page 2026 of 4705
Home
Every form defined in BMC Remedy AR System contains a set of core fields. The Request ID core
field has a unique field ID of 1. You can change the field's label to something other than "Request
ID," but the field ID is always 1.
The Request ID field contains a character string that holds a unique index for each request. The
form of this string is an optional prefix, which can consist of any alphanumeric characters, followed
by a 0-padded numeral (for example, HD0000000000001 ). The length of the Request ID field must
be either 1 or between 5 and 15 characters, inclusive. Specifying a length of 1 causes leading
zeroes to be stripped from the value in the Request ID. The prefix can be as long as the total length
of the field less five characters.
When new requests are submitted, BMC Remedy AR System generates a new ID for the request
by appending the next available ID to the prefix, if a prefix is specified.
The Request ID field contains a unique number sequence. Create other fields to contain
information specific to your site instead of using the Request ID field. Overloading the Request ID
field with other information can restrict your control of this data and can limit the flexibility of
searches on the data.
Working with the Request ID field

Every form defined in BMC Remedy AR System contains a set of core fields. The Request ID core
field has a unique field ID of 1. You can change the field's label to something other than "Request
ID," but the field ID is always 1.
The Request ID field contains a character string that holds a unique index for each request. The
form of this string is an optional prefix, which can consist of any alphanumeric characters, followed
by a 0-padded numeral (for example, HD0000000000001 ). The length of the Request ID field must
be either 1 or between 5 and 15 characters, inclusive. Specifying a length of 1 causes leading
zeroes to be stripped from the value in the Request ID. The prefix can be as long as the total length
of the field less five characters.
When new requests are submitted, BMC Remedy AR System generates a new ID for the request
by appending the next available ID to the prefix, if a prefix is specified.
The Request ID field contains a unique number sequence. Create other fields to contain
information specific to your site instead of using the Request ID field. Overloading the Request ID
field with other information can restrict your control of this data and can limit the flexibility of
searches on the data.
The following sections discuss working with the Request ID value or the Request ID field:
Changing the next available ID for new requests.
Changing the Request ID field length or prefix.
Preserving Request ID field values.
Page 2027 of 4705
Home
Changing Request ID field values to a new format.

Updating the Request ID field in other AR System tables.
Changing the next available ID for new requests

In this topic:
Database command scenarios for changing the next available request ID
The Request ID is used to automatically generate the unique index number attached to each BMC
Remedy AR System request. Under some conditions, you might need to reset the next available ID.
For example, you might need to establish different ranges for a similar form on two different servers
, or you might need to reserve a range of numbers for later use.
Note
Do not change the next available ID to a number lower than the greatest existing ID. The
Request ID field value must be unique within BMC Remedy AR System, and resetting the
ID to a lower number could conflict with existing Request ID field values. If you try to
submit a request with an existing ID, BMC Remedy AR System returns an error and
prevents the request from being submitted until the conflict is resolved.
If you must change the next available ID, change it when the system is not in use to avoid conflicts
with users who are submitting new requests.
To change the next available ID for a form in an SQL database

1. Stop AR System server.
2. Using any front-end tool that provides direct access to an SQL database, log in as a user
with write access to the AR System tables.
3. Connect to the AR System table area.
4. Find the Request ID field for the form that you want to modify.
5. Update the next available ID.
6. Restart the AR System server.
Database command scenarios for changing the next available request ID

The following scenarios show how to change the next available ID for DB2 Universal, Oracle,
Microsoft SQL Server, and Sybase databases. In the scenarios, the next available ID for a form
named ZZZ is changed from the current value of 1291 to a new value of 25000.
DB2 Universal scenario

>open DB2 command center
Connect to AR System.
Page 2028 of 4705
Home
>select name, nextId from arschema where name = 'ZZZ';

NAME
NEXTID
--- ------ZZZ
1291
1 row(s) retrieved.
>update arschema set nextId = 25000 where name = 'ZZZ';
1 row(s) updated.
Oracle scenario
% sqlplus
Enter user-name: ARAdmin
Enter password: <password> (AR#Admin# by default.)
SQL>select name, nextId from ARAdmin.arschema where name ='ZZZ';
NAME
NEXTID
------------------------------ ---------ZZZ
1291
SQL>update ARAdmin.arschema set nextId = 25000 where name = 'ZZZ';
1 row updated.
SQL>Commit;
commit complete
SQL>exit
Microsoft SQL Server and Sybase scenario

% isql -Usa
1>use ARSystem
2>go
1>select name, nextId from arschema where name = 'ZZZ'
2>go
name
ZZZ
nextId
1291
------------------------------ ---------(1 row affected)

1>update arschema set nextId = 25000 where name = 'ZZZ'
2>go
(1 row affected)
1>exit
Changing the Request ID field length or prefix

You can change the prefix or length of the Request ID field. The existing Request ID field values
are preserved. To change the values to the new format, see Changing Request ID field values to a
new format.
To change the length of the Request ID field

1. Log in to BMC Remedy Developer Studio as a user with administrator access.
2.
Page 2029 of 4705
Home
2. Open the form that you want to alter.

3. Select the Request ID field.
4. Set the Input Length property to the desired length in the Input Length field.
The length of the Request ID field must be either 1 or between 5 and 15 characters,
inclusive. If you specify 1, leading 0s are stripped from the value the Request ID field. If you
specify a prefix for the Request ID field, the field must be at least 5 characters greater than
the prefix.
5. Save the changes to the form.
To change the prefix of the Request ID field

1. Log in to BMC Remedy Developer Studio as a user with administrator access.
2. Open the form that you want to alter.
3. Select the Request ID field.
4. Set the Default Value property to the desired prefix.
The Request ID field must be between 5 and 15 characters in length. If you specify a prefix
for the Request ID field, the field length must be at least five characters greater than the
prefix.
5. Save the changes to the form.
Preserving Request ID field values

You might want to preserve the Request ID field values of your BMC Remedy AR System requests
for the following reasons:
Backward compatibility You might have cross-references that see requests by the
Request ID field value.
History The Request ID field values were created with the old format, and there is no
need for change.
Design Your BMC Remedy AR System design requires periodic change to the Request
ID field. For example, use the current year as a prefix for that field.
No data No requests were submitted, so there are no Request ID fields to convert.
Changing Request ID field values to a new format

Using an AR Export file to change the request ID field format
Editing the .arx file
Using SQL commands to shorten the Request ID field
Using SQL commands to lengthen the Request ID field value
You might want to change the values of Request ID fields for your BMC Remedy AR System
requests for the following reasons:
Page 2030 of 4705
Home
Consistency All the Request ID field values for a form follow the same format. If the
format changes, all the requests change to match the format.
Design Your BMC Remedy AR System design changed, and this design references the
new format of the Request ID field. Usually, the length of the field changes from the default
15 to something shorter, and you must eliminate the extra leading zeros.
You can use either of the following methods to update Request ID field values:
Using an AR Export file to change the request ID field format.
Using SQL commands to shorten the Request ID field.
After implementing one of those methods, see Updating status history tables and Updating
attachment tables.
Warning
Before updating field values or tables, back up your database to make sure your original
data is saved if a failure occurs during the update.
Using an AR Export file to change the request ID field format

You can edit AR Export (.arx ) files regardless of the database underlying your BMC Remedy AR
System. You can use the .arx strategy or a different strategy that bypasses BMC Remedy AR
System to operate directly in the database.
To change the Request ID field format through an AR Export file

1. In the browser, open the form that you want to change.
2. Create a report.
a. Choose Tools > Reporting.
b. In the Report dialog box, choose Report > New.
c. In the Properties - << New Style >> dialog box, click Add All to add all the fields to the
report style.
d. Select the Request ID field under Selected Fields and move it to the top of the list.
e. Choose Report > Export To > File and use .arx format to save all the data for the form
to a file.
f. Close the Report dialog box.
3. Edit the file to change the format of the Request ID field.
See Editing the .arx file.
4. In the browser, delete all requests in the form.
5. In Data Import, choose File > New Mapping.
6. In the Source Data File field, enter the .arx file you edited.
7. In the Source Form Name, enter the form from which you created the .arx file.
8.
Page 2031 of 4705
Home
8. In the Target Server and Target Form Name fields, enter the server and form to which to
import the data.
This is the same server name and form name you used to create the .arx file. (You are
simply changing the Request ID field on the same form.)
9. Click Auto Map to map the fields.
10. Click the Options tab.
11. Under the Data Handling panel, select the following options:
Make Non-Core Required Fields Optional
Disable Pattern Matching
12. Under the Duplicates panel, select Reject Duplicate Records from the Handle Duplicate
Request IDs By list.
13. Choose Import > Start Import.
Editing the .arx file

After the first few header lines, the remaining lines in the .arx file have the following format:
DATA "000000000000001" "<otherData>" 1 "<otherData>"
where <otherData> is data from the form.

The Request ID field always follows the keyword DATA. In this example, the Request ID field has no
prefix and is 15 characters in length. Use a text editor, such as WordPad, to convert the format of
the Request ID field.
The following procedures show how you can shorten a Request ID field with a length of 15
characters to 10 characters and add a prefix of ABC.
To edit the .arx file in Windows

1. Open the .arx file in a text editor that has a Find/Replace command with a feature for
matching case (for example, WordPad).
2. Use the Find/Replace command to search for DATA "00000000.
Note
This command contains eight zeros. Five of the zeroes represent the difference
between the original length of fifteen characters and the new length of ten
characters. The other three zeros represent the spaces to be replaced by ABC.
3. Use the match case feature.
4.
Page 2032 of 4705
Home
4. Replace all instances of:

DATA "00000000
with:
DATA "ABC
5. Save the changes to the file.
To edit the .arx file in UNIX

1. Open the file in a text editor.
2. Type the following command:
g /^DATA "00000000/s//DATA "ABC/
3. Save and close the file.
Using SQL commands to shorten the Request ID field

Changing existing Request ID field value format when the Request ID does not have a prefix
Changing existing Request ID field value format when the Request ID has a prefix
Only administrators running BMC Remedy AR System with an SQL database can update existing
request ID field values by directly accessing the SQL database. The syntax for direct access is
different for each SQL database that BMC Remedy AR System supports.
To use the methods described in this section, you must be familiar with basic commands in the
SQL command interface. SQL commands bypass BMC Remedy AR System completely. If you
bypass BMC Remedy AR System, verify that all data is valid when you are finished.
Tip
Create a practice table in your database and practice the commands you will issue to
make sure that you are issuing the correct commands. Make sure you back up your
database or all the relevant tables.
Note
When you change the length of the Request ID field in a database table, all related
database tables, such as status history tables ( H Tables), and Attachment tables ( B
Tables and BC Tables) must also be updated.
Page 2033 of 4705
Home
Important
Stop BMC Remedy AR System before you attempt any database modifications.
Finding the name of the table

Before you can shorten the request ID field value, you must find the table holding the form being
changed.
To find the table name

1. Find the correct schema ID for the form with the following query:
Select SchemaId, name from arschema order by 2
This query returns a list of schema IDs and associated form names.
2. Find the correct field ID with the following query. (The example assumes that the schema ID
is 43.)
Select FieldId, FieldName from field where SchemaId = 43
This query returns a list of field IDs and associated field names.
3. Use the schema ID, field ID, and information in the following table to construct the table
name.
AR System table name constructs

Table
name
Description
T
schemaID
A table that contains the data in your form. A table named T43 indicates that 43 is the schema ID.
T
schemaID
(Oracle only) A table that contains long text and diary data. For example, a table named T43C536870924 indicates
C fieldID
that 43 is the schema ID and 536870924 is the field ID. In many cases, the form has more than one long text or diary
field. This format is used for backward compatibility with forms created using BMC Remedy AR System versions prior
to 4.5.
H
schemaID
A table that contains the Status History information for your form. A table named H43 indicates that 43 is the schema
ID. See the Database Reference Using relational databases with BMC Remedy AR System .
A table that contains a list of all the attachments and related information for each record in your form. A table named
schemaID
B43 indicates that 43 is the schema ID. See The attachment tables for a form.
B
schemaID
C fieldID
A table that contains the actual Binary objects for attachment fields in your form. A table named B43C536870924
indicates that 43 is the schema ID and 536870924 is the field ID. In this example, the field ID for the attachment field
is 536870924. In some cases, the form has more than one attachment field.
Note
For T schemaID and B schemaID tables, the request ID column of the table is always
named C1. For the H schemaID, T schemaIDC fieldID, and B schemaIDC fieldID tables,
the Entry ID column is equivalent to the C1 column.
Page 2034 of 4705
Home
Changing existing Request ID field value format when the Request ID does not have a prefix
The following examples assume that the table is named T43 and that the field size is 8 characters.
The 8 represents the number of characters to keep, starting from the right side of C1. C1 is
originally 15 characters long. Make sure that the number of characters in the second parameter in
the RIGHT function is equal to the new size of the C1 field and that the sum of the two numeric
values in the SUBSTR function is 16 (1 greater than the original length of C1 ).
DB2 database scenarios

To add a prefix to the T schemaID table, use the following syntax:
updcolate T43 set C1 = RIGHT(C1, 8)
To add a prefix to the B schemaID table, use the following syntax:
update B43 set C1 = RIGHT(C1, 8)
For the H schemaID table, use the following syntax:
update H43 set entryId = RIGHT(entryId, 8)
For the B schemaIDC fieldID tables, use the following syntax:
update B43C536870924 set entryId = RIGHT (entryId, 8)
Oracle database scenarios

update T43 set C1 = substr(C1,8,8);
update B43 set C1 = substr(C1,8,8);
update H43 set entryId = substr(entryId,8,8);
update B43C536870924 set entryId = substr(entryId,8,8);
For the T schemaID C fieldID tables, use the following syntax:
update T43C536870924 set entryId = substr(entryId,8,8);
Note
In the functions substr(C1,8,8) and substr(entryId,8,8), the first 8 represents the starting
position of the characters to keep, and the second 8 is the number of characters to keep.
Page 2035 of 4705
Home
Microsoft SQL Server and Sybase database scenarios

update T43 set C1 = RIGHT(C1, 8)
update B43 set C1 = RIGHT(C1, 8)
update H43 set entryId = RIGHT(entryId, 8)
update B43C536870924 set entryId = RIGHT (entryId, 8)
Changing existing Request ID field value format when the Request ID has a prefix
The following examples assume that:
The table is named T43.
The prefix is HD.
The field size (including the prefix) is 8 characters.
The 6 represents the number of characters to keep, starting from the right side of C1. C1 is
originally 15 characters long. Make sure that the number of characters in your prefix plus the
second parameter in the RIGHT function is equal to the new size of the C1 field.
DB2 database scenarios

update T43 set C1 = 'HD' || RIGHT(C1, 6)
update B43 set C1 = 'HD' || RIGHT(C1, 6)
update H43 set entryId = 'HD' || RIGHT(entryId, 6)
update B43C536870924 set entryId = 'HD' || RIGHT (entryId, 6)
Oracle database scenarios

update T43 set C1 = 'HD'||substr(C1,10,6);
update B43 set C1 = 'HD'||substr(C1,10,6);
Page 2036 of 4705
Home
update H43 set entryId = 'HD'||substr(entryId,10,6);

update B43C536870924 set entryId = 'HD'||substr(entryId,10,6);
For the T schemaIDC fieldID tables, use the following syntax:
update T43C536870924 set entryId = 'HD'||substr(entryId,10,6);
Note
In the functions substr(C1,10,6) and substr(entryId,10,6), 10 represents the starting
position of the characters to keep, and 6 is the number of characters to keep.
Microsoft SQL Server and Sybase database scenarios

update T43 set C1 = "HD"+ RIGHT(C1, 6)
update B43 set C1 = "HD" + RIGHT(C1, 6)
update H43 set entryId = "HD" + RIGHT(entryId, 6)
update B43C536870924 set entryId = "HD" + RIGHT (entryId, 6)
Using SQL commands to lengthen the Request ID field value

The format for all the supported databases is the same for lengthening the Request ID field format
as with shortening the Request ID field format. See Using SQL commands to shorten the Request
ID field for hints about how to run the SQL interface and find the name of the table to be changed.
In the following examples, the length of the field is restored to 15 characters (the maximum) from
the current 10 characters by adding 5 leading zeros to the value of the Request ID field and
assigning the resulting 15-character string to the Request ID field. When you determine the name
of the table (T43 in the example), issue one of the following commands at the prompt:
DB2
*% update T43 set C1 = '00000' \|\|C1*
Oracle
Page 2037 of 4705
Home
*% update T43 set C1 = '00000' \|\| C1*
Sybase and Microsoft SQL Server
*% update T43 set C1 = '00000' + C1*
To add a prefix, specify the prefix as part of the string to be added. For example, to expand to 15
characters and add a prefix of ABC, use 'ABC00' instead of '00000' in the preceding example.
Updating the Request ID field in other AR System tables

When you change the Request ID in a main data table, you must also consider whether you need
to make a similar change to the status history table and attachment tables.
Updating status history tables

Status history information is stored in a separate table. This table uses the Request ID field as the
link to the main table. Accordingly, you use the same procedure to change the Request ID field
values in the status history table as you do in other tables.
To update the status history table, use the commands described in the previous examples,
substituting H43 for T43 and entryId for C1. For more information, see Using SQL commands to
shorten the Request ID field and The status history table for a form .
Updating attachment tables

Attachment information is stored in the following tables:
Attachment Details table Holds attachment characteristics, such as the name and size of
the attachment.
Attachment Data table Holds the actual attachment.
These tables use the Request ID field as the link to the main table. Accordingly, you use the same
procedure to change the Request ID field values in the status history table as you do in other tables
.
The Attachment Details table is named with a B followed by the schema ID (for example, B3 ). The
Attachment Data table is named with a B followed by the schema ID, followed by C, followed by the
attachment field ID. For example, the Attachment Data table might be called B7C536870920,
where 7 is the schema ID, and 536870920 is the attachment field ID.
The column holding the Request ID in the Attachment Details table is named C1, and in the
Attachment Data table, it is named entryId. To update the Request ID field in the attachment tables
, use the commands described in the previous examples, substituting the appropriate table name,
Page 2038 of 4705
Home
and using C1 or entryId for the Request ID. For more information, see Using SQL commands to
shorten the Request ID field.
See the The attachment tables for a form.

This section contains information about the AR System database:
Table updates for AR System form changes
Understanding the relationship between forms and database tables
Using relational databases with BMC Remedy AR System
Table support for server group tables
The AR System data dictionary
Database column types used for AR System fields
Related information for supported databases
Table updates for AR System form changes

When you restructure a regular form by adding, deleting, or changing the length of fields, BMC
Remedy AR System restructures the underlying database to reflect those changes.
Table updates when adding fields to a form
Table updates when deleting fields from a form
Table updates when changing character field lengths
Note
This section does not apply to join forms. Adding or deleting fields in a join form simply
adds or removes the references to the fields in the underlying form. You cannot change
the length of a field in a join form because it is defined in the underlying form.
For view forms, the database view is re-created when any fields are added or removed. The
database is not re-created if field properties (for example, length) are changed.
Important
Consider performance when you restructure your database. When a table is restructured,
the performance impact of the operation depends on the amount of data in the table. If the
table contains a large amount of data, the restructuring operation might take a long time,
and it might take a large amount of log and data space within the system. Accordingly,
plan updates to occur during hours when access to data in the system is not critical.
Page 2039 of 4705
Home
Table updates when adding fields to a form

When you add a field to a form, a column is added to the main data table by using the ALTER
TABLE command. The structure of the database is changed to add the column according to the
rules stated in Understanding the relationship between forms and database tables .
The value for the new field in existing entries is NULL even if it is a required field. You can change
these values at any time. When the field is added, it can be used for all existing or future entries.
Use the BMC User Modify All operation to assign a default value for the field.
Table updates when deleting fields from a form

Deleting a field from a form removes the corresponding column and all data associated with the
field from the database. The following sections describe how each database deletes fields.
Table updates for DB2

In a DB2 database, the following syntax is used to build a table that contains all the structure and
data of the original table except the deleted column:
CREATE TABLE
newTableExcludingFieldBeingDeleted INSERT INTO
newTable AS SELECT
allFieldsExcludingFieldBeingDeleted FROM oldTable
After the table is created, the original is deleted:
DELETE TABLE
oldTable
Any indexes that are defined as part of the form definition are re-created on the rebuilt table.
Table updates for Oracle, Sybase, and Microsoft SQL Server

In Oracle, Sybase, and Microsoft SQL Server databases, the ALTER TABLE ... DROP ... syntax is
used to remove the column from the table.
Table updates when changing character field lengths

The following sections describe how each database changes the length of a character field.
Note
The operation of changing character field lengths logs the entire table that is modified. If
this table is large, it consumes a large amount of log space. You might need to expand
your system's log space.
Page 2040 of 4705
Home
Table updates for DB2 when changing character fields

In DB2 databases, the length of a character field is changed in one of these ways:
If the new length and old length are both <= 255 bytes, the ALTER TABLE command is
used to change the columns only if the new length is greater than the old. Neither the table
nor the index is re-created.
If the new length and old length are both <= 255 bytes but you reduce the length of a
character field, the database column is not changed or reduced. This prevents the possibility
of data loss. The database continues to report the original column length.
Note
This can be a problem if the row length approaches the limit of the tablespace's page size.
If you encounter tablespace errors because of column sizes, you can temporarily increase
the column size to greater than 255 and decrease the column to the size you want.
For any other change in length, a column is created with the new length restriction. All the
data is copied from the original column to the new column, and the original column is deleted
from the main data table. (Depending on the amount of data, this process can take a
substantial amount of time. Make sure that the database has enough space to accommodate
the data copy.)
Table updates for Microsoft SQL Server when changing character fields
In Microsoft SQL Server databases, if the field is created in BMC Remedy AR System 5.1 and later,
the length of a character field is changed in one of these ways:
If the original size is <= 8000 bytes and you decrease the length, no change is made to the
table.
If the original size is > 8000 bytes and the new length is > 8000 bytes, no change is made to
the table.
For any other change in length, a column is created with the new length restriction. All data
from the original column is copied to the new column, and the original column is deleted from
the main table.
If the field is created in a version of BMC Remedy AR System earlier than 5.1, the length of a
character field is changed in one of these ways:
If the original size is <= 255 bytes and the new length is <=8000 bytes, no change is made to
the table.
the table.
Page 2041 of 4705
Home
the main data table.
Note
In Microsoft SQL Server 2005, when the underlying database table is marked for
database replication, you cannot change the field length. If you try to do so, the ALTER
TABLE command returns this error: Cannot rename the table because it is published
for replication. (SQL Server 15051). To resolve this, turn off database replication,
change the field size, and then turn database replication on. For more information, see the
Microsoft SQL Server documentation.
Table updates for Oracle when changing character fields

The following table shows the changes that BMC Remedy AR System makes to Oracle databases
when you change the length of character fields. The way that field length changes are handled
depends on the initial size of the field and whether the field was created in the current version or a
previous version of BMC Remedy AR System.
Changing character field lengths for Oracle
Administrator Action
BMC Remedy AR System Action
Decreases the length of a field from > 4000 bytes

to <= 4000 bytes.
Adds a varchar column to the main data table; copies the data from the clob
Decreases the length of a field from <= 4000

bytes to less than 4000 bytes.
Performs no restructuring.
Increases the length of a field from <= 4000 bytes

to > 4000 bytes.
Adds a clob column to the main data table; copies the data from the varchar
Increases the length of a field from > 4000 bytes

to another value also > 4000 bytes.
column to the new column; deletes the old column.
column to the new column; deletes the old column.
Table updates for Sybase when changing character fields

In Sybase databases, the length of a character field is changed in one of these ways:
If the original size is <=255 bytes and you decrease the length, no change is made to the
table.
the table.
the main data table.
Page 2042 of 4705
Home
Server actions when changing full text indexed fields

If the length of a full text indexed field is changed, the full text index might be restructured. The
following table describes the server actions that can occur.
Server actions when full text indexed fields are changed
If the administrator does this
BMC Remedy AR System server does this
Shortens a field that is <= 32K.
Lengthens a field that is <= 32K. The new length is <=

32K
Alters the index to increase the index size and preserve the existing
data.
Lengthens a field that is <= 32K. The new length is > 32K.
Reindexes the field to generate a new index. a
Shortens a field that is > 32K. The new length is <= 32K.
Reindexes the field to generate a new index. a
Lengthens a field that is > 32K.
The following warning appears after the length change is saved: A rebuilding of the
corresponding full text index has been initiated due to the field length
change (ARWARN 681)
Understanding the relationship between forms and database tables

The main data table for a form
The status history table for a form
The attachment tables for a form
Currency columns for a form
Indexing AR System tables
SQL view creation for a form
The arschema table holds information about each form, including form name, schema ID and next
request ID.
When a regular form is created, three or more of the following tables are created in the database to
hold the information (requests) for that form:
Main data table
Status history table
Attachment tables
Currency table
The main data table for a form

Each form has an associated main data table that holds all the information for that form. The main
data table contains a column for each field except Attachments and Status History. Each main data
table or view (for join forms) is named with a T followed by the unique ID (schemaID ) for the form (
for example, T3 ). To find the ID, search the arschema table by the name column and retrieving the
Page 2043 of 4705
Home
schemaId value. The ID does not change regardless of changes made to the form, so the table
name remains the same. In AR System Data Dictionary: Forms, Fields, VUIs, and Sample Forms ,
the main data table is labeled T n .
All columns in each table or view are named with a C followed by the unique ID for the field in the
form. For example, the Submitter field is C2. The ID for the field does not change; the creator of the
field can assign the ID. Every ID is unique within a form, so duplicate name issues do not occur.
After an ID is assigned, it cannot be changed, regardless of any changes to the field. For
information about reserved and core IDs, see the Developing section.
If a join form contains an attachment field, a column is added to the Main Data view. The contents
of this column are a concatenation of the C, CO, and CC columns of the Attachment Details table. If
attachments are added to the base form, the view is updated. See The attachment tables for a form
.
Because BMC Remedy AR System must retain the IDs of the requests in the underlying table to
form the ID of a join form entry, there are a few extra columns and some special handling for
column C1. BMC Remedy AR System creates a series of columns for each regular form that is
involved in the join tree. The columns are named with an E followed by a zero-based index (three
regular tables would be named E0, E1, and E2 ). These columns point to the corresponding entry
IDs (column C1 ) of the regular forms. The C1 column for the join form is determined by
concatenating the entry IDs of the regular forms (in the E columns) separated by vertical bars ( | ).
The status history table for a form
Note
In BMC Remedy AR System 7.0.00 and later, status history tables are optional and are
set through form properties, so status history tables are not always available for regular
forms.
The status history table contains all the information for the Status History field. Each status history
table or view (for join forms) is named with an H followed by the unique ID for the form (for example
, H3 ). The ID is the same ID that the main data table or view uses, and the name of each also
remains unchanged. Every main data table has an associated status history table. In AR System
Data Dictionary: Forms, Fields, VUIs, and Sample Forms , the status history table is labeled Hn.
The most important column in this table is the entryId. It provides a reference to the C1 column of
the main data table. (Column C1 is always the Request ID.) This column is followed by a series of
one or more column pairs. There is one pair for each state defined for the Status field. The columns
are named with a prefix followed by the numeric representation for each state. The prefixes are U
for the user name and T for the time the entry was last changed to the corresponding state. The
Page 2044 of 4705
Home
numeric value is zero-indexed. For example, a form with three states for the Status field would yield
a table with seven columns: entryId, U0, T0, U1, T1, U2, and T2.
If status values are added, appropriate columns are added to this table to reflect the new states. If
states are deleted, the columns are left in the table, enabling the states to be added again in the
future. The data for the status values is stored in the database as an integer that relates to the
order of the choices. If you add values at the beginning or in the middle of existing values, other
values in the list might change.
Unlike in regular forms, for join forms, the Status History field is optional. If it is present, the Status
and Status History fields must be from the same base table. If there is no Status History field in the
form, the Status History table does not exist. If a Status History field is present, it is defined as an
exact duplicate view of the status history table or view of the base form to which it is connected.
The only difference is the name of the view. For more information about the Status History field,
see Setting form view properties.
Note
View and vendor forms do not have corresponding status history tables.
The attachment tables for a form

There are two attachment tables: the attachment details table and the attachment data table.
Attachment details table

The Attachment details table contains information for the properties of Attachment fields. For every
Attachment field in the form, a separate table is created to store the attachment value.
The Attachment details table is named with a B followed by the unique ID for the form (for example,
B3 ). In AR System Data Dictionary: Forms, Fields, VUIs, and Sample Forms , the attachment
details table is labeled B n . An attachment details table with one column ( C1 ) is created with every
form.
For every attachment field added to any attachment pool on the form, three columns are added.
Each column is named with C, CO, or CC, followed by the attachment field ID. For example, the
three columns added for one attachment might be called C536870920, CO536870920, and
CC536870920, where 536870920 is the attachment field ID.
The C column stores the full path name of the attached file. The CO column stores the original size
(in bytes) of the attached file. The CC column stores the compressed size (in bytes) of the
attachment file.
Page 2045 of 4705
Home
Attachment data table

For each attachment field on a form, an attachment data table is created. The attachment data
table is named with a B followed by the unique ID for the form, followed by C, followed by the
attachment field ID. For example, the attachment data table might be called B7C536870920, where
7 is the schemaID, and 536870920 is the attachment field ID. In AR System Data Dictionary: Forms
, Fields, VUIs, and Sample Forms , the attachment data table is labeled BnC fID.
The Attachment data table has two columns: one that holds the Request ID ( entryId ) and one that
holds the data from the file. The column holding the data is named with a C followed by the
attachment field ID. For example, the data column might be named C536870920, where
536870920 is the attachment field ID.
Limiting attachment size

Attachments can be very large. Large attachments can adversely affect AR System server memory
resources. To limit the size of attachments sent to the server and thereby prevent excessive
memory growth and reduce transmission times, use the following AR System configuration file
option:
AR-Max-Attach-Size Specifies the maximum size of compressed attachments that can be sent
to the AR System database from the AR System server. This option applies to all databases.
This limit does not apply to attachments retrieved from the database by the AR System server.
Hence, if large attachments were added to any database before this limit was specified, the server
can still retrieve them.
For Oracle databases, however, you can also limit the size of retrievable attachments by using the
following AR System configuration file option:
Db-Max-Attach-Size Limits the size of compressed attachments that the AR System server can
retrieve from Oracle databases.
For information about setting configuration file options, see AR System configuration files.
Currency columns for a form

Where a field in a form typically has one corresponding column in the main data table, the currency
field has several columns and, therefore, a unique naming convention to distinguish the extra
columns. Whereas typical fields follow the naming convention described in The main data table for
a form (all columns in each table or view are named with a C followed by the unique ID for the field
within the form), the currency field is named with a C followed by the unique ID for the currency
field and a unique suffix for each additional currency column stored in the database.
The currency suffixes used to name the additional currency columns are defined in the following
table.
Suffixes used for currency columns
Page 2046 of 4705
Home
Suffix
Currency Column Represented
Decimal value
Code associated with decimal value
Timestamp or Date established as the conversion date
Type of currency being used (USD, EUR, JPY, and so on)
Value of specified type of functional currency
For example, the columns for a currency field might be called C536870913V, C536870913C,
C536870913D, or C536870913USD.
Indexing AR System tables

Indexes are automatically maintained for all the tables created by BMC Remedy AR System. Some
are defined by BMC Remedy AR System, and others are defined by an administrator. If a table is
restructured through BMC Remedy AR System, all indexes are re-created for the new table.
The main data table has an index supported by BMC Remedy AR System defined for the C1
column. This column corresponds to the Request ID field of the form. (In Microsoft SQL Server
databases, the table is created using a primary key, which enables database replication.) The index
is a unique index and is used extensively as the main index of the table.
For the main data table, the administrator can create additional indexes for the form. The indexes
are unique only if defined as such. These additional indexes are not clustered because there can
be only one clustered index, and it is reserved for the main index supported by BMC Remedy AR
System.
The status history table has an index supported by BMC Remedy AR System defined on the
entryId column. This column also corresponds to the Request ID field of the form. The index is a
unique clustered index and is the main index of the table. BMC Remedy AR System does not
create additional indexes for the status history table.
The Attachment Data and the Attachment Details tables each have unique indexes supported by
BMC Remedy AR System. For the Attachment Data table, the index is defined on the entryId
column, and for the Attachment Details table, the index is defined on the C1 column. These
columns correspond to the Request ID field of the form. The administrator cannot create additional
indexes.
Indexing a currency field requires special considerations. Because a currency field is represented
by multiple columns in the main data table, multiple columns are indexed. Standard queries against
a currency field could potentially use any of several different columns, depending on the currency
Page 2047 of 4705
Home
type specified. To provide comprehensive coverage, indexing a currency field requires an index for
the value column, the type column, and for each functional currency column. This can produce
significant overhead for the main data table. Therefore, consider indexing a currency field carefully
before doing so.
Note
Indexes cannot be created for join forms. The form definition is just a view and the
database does not support indexes for views. Indexes defined for the underlying tables
are available and are used when performing operations against the join form. For view
forms, you must create indexes within the database. The BMC Remedy AR System
cannot create indexes on the view of the external database's table. For vendor forms, the
administrator who implemented the ARDBC data source must define and document a
mechanism to establish indexes on the underlying data. For more information about
ARDBC, see the Developing an API application.
Rebuilding indexes (DB2 only)

The clustered index on the arschema table is created on the schemaId field instead of the name
field.
If you are upgrading your Microsoft SQL Server or Sybase database, the change is included with
the installation. For other databases, you must manually create the arschema table on the
schemaId field.
For more information, see Preparing your database.
To create a clustered index on DB2

1. List the tables that have indexes on the name column, and re-create indexes on those tables
as described in the following steps.
2. Drop the existing index.
DROP INDEX schema_id_ind

DROP INDEX schema_ind
3. Create an index as required.
CREATE UNIQUE INDEX schema_id_ind ON arschema (schemaId) CLUSTER

CREATE UNIQUE INDEX schema_ind ON arschema (name)
4. Reorganize all the indexes.
Page 2048 of 4705
Home
REORG INDEXES ALL FOR TABLE arschema
SQL view creation for a form

For each table that is built in the system (except for the attachment tables), an SQL view is
automatically created. This view uses the form name as the view name and the field names (not a
display label in one of the views) as the column names. The names are created by using the
following rules:
All alphabetic and numeric characters remain as defined.
All other characters are converted to an underscore ( _ ).
If the first character is not alphanumeric, a leading A is added to the name.
If the name of a field is blank, a field name with a leading A followed by the fieldId is used.
If the name is one of the reserved words for the database, the string _x is appended.
The name of the table must be unique after the conversion. If it is not, three digits are appended to
it, beginning with 001 (if necessary, the name is truncated to fit the maximum length allowed for an
SQL name). If 001 does not make the name unique, 002 is tried, then 003, and so on until a unique
name is created. Column names must also be unique, so the same naming convention is used.
The name of the SQL view must also be unique after the conversion. If it is not, the schema ID is
appended to it (if necessary, the name is truncated to fit the maximum length allowed for an SQL
name). Column names must also be unique, so the same naming convention is used.
The SQL view of the status history table follows the same strategy as the SQL view of the base
table. The name of the table is created by adding SH_ to the front of the name of the base table
view. The column names are mapped to the name of the Request ID field, and the names of each
of the Status values with _TIME and _USER appended. So a form with two states, New and Closed
, ends up with columns in the view named Entry_Id, New_USER, New_TIME, Closed_USER, and
Closed_TIME.
These SQL views are re-created when the name for the field is changed or when a change is made
to the form that affects the underlying table (deleting a field, adding a field, or changing the length
of a field).
You can use the view or the base tables to read data from the database. The SQL views are
especially useful when a third-party report writer is used because the names of its tables and
columns are easier to use than their internal, numeric representations in the base tables.
Using relational databases with BMC Remedy AR System

BMC Remedy AR System can use any of the following database platforms :
IBM DB2
Page 2049 of 4705
Home
Oracle
Sybase ASE
Note
For the most accurate information about supported platforms and software, Compatibility
matrix in the BMC Remedy ITSM 9.0 online documentation.
Each type of relational database behaves differently with regard to search qualifications, wildcards,
and so forth. The following topics describe these differences.
Using IBM DB2 Universal Database with BMC Remedy AR System
Using Microsoft SQL Server with BMC Remedy AR System
Using Oracle with BMC Remedy AR System
Using Sybase with BMC Remedy AR System
In general, BMC Remedy AR System hides the underlying database from the user. The AR System
server interacts with the database and provides information to the user independent of the
underlying database. All access through the API supplied with the product goes through this server
and is independent of the database.
Note
If you upgrade from a previous version of BMC Remedy AR System, the data dictionary is
restructured. This chapter describes changes that occur during installation and changes
that occur as new data is stored in the database.
BMC Remedy AR System supports read access directly from the tables but does not support
update access to any of the AR System tables directly through SQL. You must go through the AR
System API for update access.
Note
BMC Remedy reserves the right to change the structure of the AR System database in
any release. If the structure is changed, the database version number is updated to
indicate a change.
Page 2050 of 4705
Home
Other than AR System data, BMC Remedy AR System and its installation do not interact with or
affect other data in the database. The only exception is data referenced by using the Direct SQL
capability within workflow or by using a view form. For more information about this function, see the
Developing section.
Warning
Because BMC Remedy AR System passes SQL commands to the database without
checking the syntax, all commands are submitted to the database. Make sure all
submitted commands achieve the desired result. Your SQL commands should comply
with ANSI SQL standards so that single quotation marks are reserved for strings and
double quotation marks are reserved for use with database object names only.
When you install BMC Remedy AR System over a relational database, an AR System database is
created. By default, this database is named ARSystem, and the user ARAdmin is defined. You
can choose other values during installation. This document refers to the default values, so if you
changed them during installation, substitute your database and user names for ARSystem and
ARAdmin. The characteristics of the AR System database vary depending on the type of
underlying relational database.
You can perform any system administrator activity on the database or on any of the tables it
contains. This includes performing regular backups, creating more tablespaces to be added to the
AR System database, and adding more containers to tablespaces. With a Sybase or Microsoft SQL
Server database, flush the transaction log (or configure it to autoflush) as part of your regular
backup strategy.
After the AR System database is created, BMC Remedy AR System creates a series of tables that
form its data dictionary. See The AR System data dictionary.
For information about different behaviors and requirements for installing BMC Remedy AR System
with specific databases, see Preparing your database.
For information about configuration options and parameters associated with specific databases, see
ar.cfg or ar.conf.
Using IBM DB2 Universal Database with BMC Remedy AR System

IBM DB2 behaviors that you need to consider are described in the following sections.
User name and password

See Using IBM DB2 Universal Database user names and passwords for user name and password
information.
Page 2051 of 4705
Home
Form and field limits

When you create a form, there is a size limit. The total size of all data fields in a form cannot
exceed 16 KB with the installed BMC Remedy AR System database. This is due to a DB2 limitation
that creates a database with a tablespace that has a 16 KB page size. If you create a form that
exceeds 16 KB, you must create a tablespace with a large page size before you create such a form
.
To create a tablespace with a larger page size for a particular form

1. Stop the BMC Remedy AR System server.
2. Create a tablespace with 32 KB page size. (You might want to name the tablespace
something like TBS32K.)
3. Start the BMC Remedy AR System server.
4. In a browser, open the AR System Administration: Server Information form.
5. On the Database tab, add the following options to the database configuration file.
Form: <formName>
Clause: IN TBS32K
This causes the table for the formName form to be created in the tablespace of 32 KB.
You can also specify the clause as follows:
Form:
Clause: IN TBS32K
This causes the table for all the forms to be created in the tablespace of 32 KB.
6. Click OK to save this server information.
7. Create the form.
The following limits pertain to the size of attachments and fields:
The character field length is limited to 1 MB.
The attachment size is limited to 1 GB.
You cannot sort character fields greater than 254 bytes.
You cannot store background bitmaps larger than 1 MB.
LIKE predicate
DB2 does not support using a column reference on the right side (or pattern) of the LIKE predicate.
Only character-value references are supported. For example, the following query returns an error
message because DB2 does not support using a field ID on the right of the LIKE predicate.
"Demo" LIKE 'Submitter'
This might affect the functionality of BMC Remedy applications.
Page 2052 of 4705
Home
Using Microsoft SQL Server with BMC Remedy AR System

Microsoft SQL Server behaviors that you need to consider are described in the following sections.
Diary and Character field qualifications

When you specify search criteria for a field that contains more than 8000 characters or a diary field,
you must use the LIKE operator. If you use any other relational operator, you receive an error.
Case sensitivity in queries

By default, the Microsoft SQL Server search criteria are in dictionary order and are case-insensitive
. You can, however, specify an option that enables case-sensitive searches. For more information,
see your Microsoft SQL Server documentation.
Reducing deadlocks by using snapshot isolation

Microsoft SQL Server 2005 provides the "snapshot" isolation level, which allows a transaction to
read the last committed version of the data that is currently being changed. Thus, the transaction's
view of the data is consistent with the state of the data when the transaction began without being
blocked by other transactions. This reduces the possibility of deadlocks.
Warning
Some processing overhead occurs due to the creation of a temporary database with a
large size, and the storage and retrieval of versioned data.
For more information about the snapshot isolation in SQL Server, go to http://msdn.microsoft.com/
en-us/library/ms130975.aspx.
To use a snapshot isolation level with the AR System database

1. Stop the AR System server to ensure that all connections to the AR System database are
closed.
For a server group or a shared database, stop all of the AR System instances.
2. To verify whether the appropriate isolation level is set for the AR System database, enter:
SELECT is_read_committed_snapshot_on FROM sys.databases where name = 'ARSystem'
3. To set the snapshot isolation level, enter:
ALTER DATABASE ARSystem SET READ_COMMITTED_SNAPSHOT ON
4. Restart the AR System server. Optionally, to revert to the original setting, use the following
commands in the same sequence as mentioned:
Page 2053 of 4705
4.
Home
ALTER DATABASE ARSystem SET READ_COMMITTED_SNAPSHOT OFF
Improving performance with parameterization

The AR System server uses dynamically built queries that need to be compiled and recompiled
frequently. By default, the AR System database uses simple parameterization.
Forced parameterization converts any literal value that appears in a SELECT, INSERT, UPDATE,
or DELETE statement to a parameter during query compilation. A parameterized query requires
less recompilation, thereby improving performance.
Tip
Do not use forced parameterization in environments that rely heavily on indexed views
and indexes on computed columns. Error reporting for forced parameterization might differ
from that of simple parameterization. Only experienced database administrators should
use forced parameterization after determining that its usage does not adversely affect
performance.
For further information about forced parameterization, go to http://msdn.microsoft.com/en-us/library/

ms175037.aspx.
To use forced parameterization with the AR System database

1. To set forced parameterization, enter the following SQL command:
ALTER DATABASE ARSystem SET PARAMETERIZATION FORCED
You can set this attribute without interrupting the existing database connections.
2. To revert to the original setting, enter the following SQL command:
ALTER DATABASE ARSystem SET PARAMETERIZATION SIMPLE
Using Oracle with BMC Remedy AR System

When specifying search criteria, you cannot use diary fields or character fields that contain more
than 4000 characters. The database system does not support qualifications on these field types. If
you specify a qualification for one of these field types, you receive an error.
When the Oracle-Search-On-Clob setting option in the ar.conf (ar.cfg ) file is set to true (the
default), you can perform a string search (without wildcards) on these field types. For more
information about the ar.conf or ar.cfg file, see ar.cfg or ar.conf.
Page 2054 of 4705
Home
For searches on database entries, the only wildcard character supported in the LIKE comparison is
the percent symbol (%). There is no support for sets or ranges of values.
When used with the LIKE operator, the underscore (_) character cannot function as a wildcard or
as literal text.
Wildcards are fully supported in filter, escalation, and active link qualifications and in pattern
specifications for character fields.
Warning
If you use an Oracle AR System database with the Unicode database option, problems
might occur if the NLS_LENGTH_SEMANTICS parameter is not set to BYTE in the AR
System database and in the database server instance. See Preparing to install on a
Unicode database and Preparing to upgrade on a Unicode database .
Using Sybase with BMC Remedy AR System

This section describes Sybase behaviors that you need to consider.
Diary and character field qualifications

When specifying query criteria for a field containing more than 255 characters or a diary field, use
the LIKE operator. If you use any other relational operator, you receive an error.
For decimal fields, a NULL value is read from the database as 0.00 and not as a NULL value. This
is due to an incorrect return from the Sybase database library.
Case-insensitive queries
By default, query criteria is case sensitive. You can, however, specify an option for case-insensitive
queries. For more information, see your Sybase documentation.
Issues with AR System joins

The following issues pertain to AR System joins and Sybase databases:
With Sybase databases, you cannot nest outer-joined AR System forms.
When opening an outer join form in modify mode, the database operation might fail. If it does
, you receive AR System error 552 and Sybase error 4426.
Sybase does not support long character or diary fields in an outer join form.
In the database, long character fields and diary fields are implemented as text columns.
If you query on a diary or long text field in the inner table of an outer join, Sybase error 7114
causes arserverd to crash. (Sybase Change Request #122344)
Page 2055 of 4705
Home
Sybase character sets

The following issues pertain to Sybase database character sets:
If your Sybase server is configured to use the ISO-8859-1 character set, you must include
the following line in your ar.conf file:
Sybase-Character-Set: iso_1
If you experience character conversion errors, contact Sybase Support for help matching the
Sybase client (arserverd process) character set with your Sybase server character set.
The database removes trailing spaces added to names, menu labels, and field labels in
SQL statement length limit

You cannot submit an SQL statement longer than 5197 characters to a Sybase database. If you do,
the AR System server returns an error citing incorrect syntax.
Table support for server group tables

The database tables listed in the following table support server groups.
Database tables for server groups

Table
Description
servgrp_applic
Contains internal application licensing information. Each time a server in a server group starts, it removes
records related to itself from this table.
servgrp_board
Serves as a bulletin board for all servers in a server group to record their existence and to provide updates
about their current status. This table contains one record for each server in the group. It has the following
fields:
serverName The name of the server to use to send requests through the API.
serverPort The port number in use by the server that should be used to send requests through the
API.
intervalCount A heartbeat count periodically updated to indicate that the server is running.
pendingSignals Currently pending signals sent by other servers in the server group.
opFlags A character string indicating the current state of operation ownership in the server group.
servgrp_config
Contains configuration information for server group management. This table has the following fields:
name The logical name of the server group.
checkInterval The interval (in seconds) between server group management checks.
servgrp_ftslic
Contains internal full text licensing information. Each time a server in a server group starts, it removes
records related to itself from this table.
servgrp_op_mstr
Contains control information for each server operation that can be managed within a server group. This table
contains one record for each operation. It is an internal table manipulated only by AR System.
servgrp_userlic
Contains internal user licensing information. Each time a server in a server group starts, it removes records
related to itself from this table.
For more information about server groups, see Configuring server groups.
Page 2056 of 4705
Home
The AR System data dictionary

In this topic:
The initial table of the AR System data dictionary
The schema table in the AR System data dictionary
The field table in the AR System data dictionary
The menu table in the AR System data dictionary
The image table in the AR System data dictionary
The filter table in the AR System data dictionary
The escalation table in the AR System data dictionary
The active link table in the AR System data dictionary
The workflow mapping tables in the AR System data dictionary
The container table in the AR System data dictionary
The overlay and custom object columns in the AR System data dictionary
The AR System data dictionary is composed of tables that contain the structural definitions of all
the forms, filters, escalations, active links, character menus, and containers that are entered into
the system (see the following figure, the following figure, and the following figure).
Together, these tables contain the complete definition of the structures and workflow in your
implementation of BMC Remedy AR System. As you add or alter structures in your system,
appropriate updates are made to these tables to reflect the changes.
AR System Data Dictionary: Forms, Fields, VUIs, and Sample Forms
Page 2057 of 4705
Home
AR System Data Dictionary: Active Links, Filters, and Escalations
Page 2058 of 4705
Home
AR System Data Dictionary: Container
Page 2059 of 4705
Home
The initial table of the AR System data dictionary

The first table is named control, and it contains one row. The columns contain information about
the version of the database, dbVersion, and a set of numbers identifying the next available ID for
the various structure items that can be created.
The schema table in the AR System data dictionary

A set of tables is used to define the form (known as schema in the database tables). The
arschema table contains information about the form definitions. The four main fields in the
arschema table are:
schemaId The unique internal ID for the form (which does not change, regardless of
changes to the form).
name The administrator name for the form.
schemaType The type of form (regular, join, view, or vendor).
nextId The next available ID for a new entry for that form.
Page 2060 of 4705
Home
The following set of tables holds information associated with the form definition:
schema_group_ids Defines which groups have access to the form.
subadmin_group Defines which groups have subadministrator access potential for this
form.
schema_list_fields Defines which fields are returned in response to the ARGetListEntry
and ARGetListEntryWithFields API calls.
schema_vendor Defines how the form is attached to an ARDBC data source.
schema_view Defines how the form is attached to a database table.
schema_join Defines how the form is joined, if applicable.
schema_index Defines the indexes for the form.
schema_sort Defines the default sort order for the form.
schema_archive Defines the archive information for the form.
Every form contains at least one view user interface (VUI) that represents the various layouts and
fields that hold the data for the form. The vui table contains information about each VUI in each
form. Every VUI is identified by the combination of the schemaId that connects the VUI to a form,
and the vuiId that identifies that VUI within the form.
The field table in the AR System data dictionary

The field table contains all the information (except for the display information) about each field in
each form. Every field is identified by the combination of the schemaId that connects the field to a
form and the fieldId that identifies the field within the form.
The vuiId and fieldId are unique within the form, so a single ID identifies either a VUI or a field.
The field_dispprop table contains information used to define how the field is displayed in the form.
The objProp column in the field_dispprop table holds a list of fields whose display properties
have changed in the view overlay form. The field_permissions table contains information about
the permissions of various groups to the individual fields. The following series of additional tables
holds information that is specific to each data type: field_int, field_real, field_char, field_diary,
field_dec, field_curr, field_date, field_enum, field_attach, field_table, field_column,
field_view, field_display, and field_enum_values (there is no additional data for timestamp, trim,
or control fields).
If a field is located in a join form, there is an additional entry in the join_mapping table. This entry
contains the definition of how this field is connected to the field in the base forms that make up the
join form.
If a field is located in a view form, there is an additional entry in the view_mapping table. This entry
contains the definition of how this field is connected to the field in the base forms that make up the
view form.
Page 2061 of 4705
Home
If a field is located in a vendor form, there is an additional entry in the vendor_mapping table. This
entry contains the definition of how this field is connected to the field in the base forms that make
up the vendor form.
The menu table in the AR System data dictionary

The char_menu table contains an entry for each menu, and tags each with a charMenuId. A set of
tables associated with the char_menu table (linked by charMenuId ) provides the details about the
various types of character menus:
char_menu_list
char_menu_query
char_menu_file
char_menu_sql
char_menu_dd
The image table in the AR System data dictionary

The image table contains an entry for each image object stored in BMC Remedy AR System.
All images used in form views and fields were stored ("embedded") in the display properties of the
views and fields as a byte string using the ARByteList data type. If the same image was used in
multiple views or fields, a separate copy of the image was embedded in each view and field.
The images can be stored in the image table as shared objects in binary format. This enables
multiple views and fields to share a single image object simply by storing a reference to the image
object in their display properties. The reference uses the charVal data type.
The image table includes unique indexes on the following fields:
imageID AR System assigns a unique image ID to each stored image.
name You assign a unique name to an image object when you create it.
For backward compatibility with pre-7.5.00 AR System clients, the AR System server converts the
charVal reference to a data string before transferring it to the client.
Two XML ENUM data types for exporting images ( AR_STRUCT_ITEM_IMAGE and
AR_STRUCT_ITEM_XML_IMAGE ) and an export format (image ) are added. For more
information about image objects, see Working with images.
The filter table in the AR System data dictionary

The filter table contains an entry for each filter, and tags each with a filterId. Tables associated
with the filter table (linked by filterId ) provide the details about the various actions defined for each
filter:
Page 2062 of 4705
Home
filter_call
filter_notify_ids
filter_exit
filter_process
filter_goto
filter_push
filter_gotoaction
filter_serviceaction
filter_log
filter_set
filter_message
filter_sql
filter_notify
The escalation table in the AR System data dictionary

The escalation table contains an entry for each escalation, and tags each with an escalationId.
Because escalations and filters are so tightly linked, the information about actions for escalations is
stored in the same tables as the filter actions. The escalationId and the filterId are unique within
the table, so a single ID identifies either a filter or an escalation.
The active link table in the AR System data dictionary

The actlink table contains an entry for each active link, and tags each with an actlinkId. Tables
associated with the actlink table (linked by actlinkId ) provide the details about the various actions
that are defined for each active link:
actlink_macro
actlink_goto
actlink_macro_parm
actlink_exit
actlink_set
actlink_call
actlink_process
actlink_close
actlink_message
actlink_commit
actlink_set_char
actlink_open
Page 2063 of 4705
Home
actlink_dde
actlink_sql
actlink_gotoaction
actlink_push
actlink_wait
actlink_auto
actlink_serviceaction
The support_file table stores report definitions. Finally, the table actlink_group_ids contains the
list of groups that can execute the active link.
The workflow mapping tables in the AR System data dictionary

A set of mapping tables associates each filter, escalation, or active link with all its forms, allowing
administrators to create shared workflow. The filter_mapping table contains the filterId and
schemaId for each entry, creating a link between each filter and form. The escal_mapping table
associates escalations with forms by storing the escalationId and schemaId for each entry. In a
similar way, the actlink_mapping table associates active links with forms by storing the actlinkId
and schemaId for each entry.
The container table in the AR System data dictionary

The arcontainer table contains an entry for each container, and tags each with a containerId.
Containers are used to define guides, applications, packing lists, workspaces, and web services.
The three main fields in the table are:
containerId The unique internal ID for the container.
name The administrator name for the container.
containerType The type of container.
The following set of tables holds information associated with the container definition:
arctr_group_ids Defines which groups have access to the container.
arctr_subadmin Defines which groups have subadministrator access to the container for
containers that are not owned.
arreference Defines the references for each container.
arref_group_ids Defines group access permissions for external references.
cntnr_ownr_obj Lists the owners for the container.
A list of references defines the components that belong to each container. For example, a container
might reference forms, workflow objects, and other internal and external objects that make up an
application or guide. Each container can have zero, one, or multiple references. Each reference is
identified by the containerId of the container to which it belongs, and by the referenceId that
Page 2064 of 4705
Home
identifies the object itself.

All references are described by reference type, data type, reference order number, label, and
description. Internal references store the referenceObjId. External references store a short value
or long value that describes the external reference. The arref_group_ids table can have zero, one,
or multiple group entries that define group access permissions for each external reference. Each
entry describes a groupId permitted to access an external reference.
For more information about using containers to create guides, see Containers and structures. For
more information about the data structures used to define containers, see Containers and
structures.
The overlay and custom object columns in the AR System data dictionary
The following columns are added to the actlink, arcontainer, arschema, char_menu, escalation,
field, filter, image, and vui tables in the AR System database to support the overlays and custom
objects:
overlayProp(int) Holds a bitmask value that specifies the overlay state of an object. The
values are:
0 (unmodified)
1 (overlaid)
2 (overlay)
4 (custom)
By default, this column is blank, which is the same as 0 (unmodified). When an
overlay is created, the create overlay operation sets this column to 1 in the overlaid
object and to 2 in the overlay object.
overlayGroup(nvarchar(254)) Identifies the overlay group to which an object belongs.
The values are:
0 (does not belong to an overlay group)
1 (belongs to the overlay group)
An object can belong to only one overlay group.
All overlay and custom objects have 1 in this column. Unmodified and overlaid objects
always have 0 in this column.
resolvedName (nvarchar(254)) Holds the name of the overlaid object.
overlayExtended(int) - Defines whether an object is extended. The values are:
0 (not extended)
1(extended)
Note
Page 2065 of 4705
Home
When you use the get function of the AR System driver utility for an object,
it displays the overlayProp and overlayGroup values for all objects, except
the unmodified ones.
The following table shows the values for the overlay* columns by object
customization type:
Database overlay column values by object customization type
Object type
Database overlay column values

overlayProp
overlayGroup
Unmodified origin
Overlaid
Overlay
Custom
In addition to the preceding columns, the following columns were added to the
arschema and vui tables:
resolvedSchemaId int (arschema)
objProp nvarchar(254) (vui)
Note
For each overlay, an entry is added to the baseline object table. Nonetheless, field and
form overlays are not treated as individual objects in the database. Instead, they are
treated as subsets of the overlaid object properties because they share data with the
overlaid object. All other types of overlays are treated as individual objects, although they
remain dependent on their overlaid objects and are tightly coupled with them.
For more information about overlay and custom objects, see Customizing applications using
overlays and custom objects.
Database column types used for AR System fields

In this topic:
DB2 column types used for AR System fields
Microsoft SQL Server column types used for AR System fields
Oracle column types used for AR System fields
Sybase column types used for AR System fields
The following sections list the column types used for AR System fields in each database type
supported by BMC Remedy AR System.
Page 2066 of 4705
Home
Note
Control, display-only, page, page holder, table, table column, trim, and view fields do not
require storage in database tables, so they are not listed in this section.

The following table shows the DB2 column types used for each AR System field type whose values
are stored in database tables.

DB2 column type
Attachment
blob (up to 1 GB)
Character with a maximum length of 4000 or fewer bytes
varchar
Character with an unlimited length or a maximum length of more than 4000 bytes
clob (up to 1 MB)
Currency (a group of columns composed of a combination of the specified column types)
decimal, varchar, and integer
Date
integer
Date/Time (time stamp)
integer
Decimal
decimal
Diary
clob (up to 1 MB)
Integer
integer
Real
float
Selection
integer
Time
integer
Note
Previously created fields that use longvarchar types continue to use longvarchar.
Microsoft SQL Server column types used for AR System fields

The following table shows the Microsoft SQL Server column types used for each AR System field
type whose values are stored in database tables.
Microsoft SQL Server column types used with AR System fields
Page 2067 of 4705
Home
SQL Server column type
Attachment up to 2 GB
image
varchar
text
decimal, varchar, and int
Date
int
int
Decimal
decimal
Diary
text
Integer
int
Real
float
Selection
int
Time
int
Oracle column types used for AR System fields

Configuring process administrator capabilities shows the Oracle column types used for each AR
System field type whose values are stored in database tables.
Oracle column types used with AR System field types

AR System field
type
Oracle column type
Attachment up to 4
GB
blob For the Oracle RDBMS, the default maximum attachment size is 2 GB. (This was increased from 1
MB to 2 GB.) To adjust the maximum attachment size, update the Db-Max-Attach-Size configuration
parameter in the ar.conf (ar.cfg ) file. For more information about these files, see ar.conf (ar.cfg). The
maximum value is limited by your server operating system and configuration.
Note
Attachment fields created by a pre-7.0 BMC Remedy AR System server remain a long raw data
type. New attachment fields use the Oracle blob type.
Character with a
maximum of 4000 or
fewer bytes
varchar
clob The AR_SERVER_INFO_ORACLE_CLOB_STORE_INROW server information setting controls

Oracle CLOB storage. It takes these values:
TRUE --- CLOBs are created "in row."
Page 2068 of 4705
Home
AR System field
type
Oracle column type
Character with an
unlimited length or a
maximum length of
more than 4000
bytes
Large in-row CLOBs can degrade CPU performance, but small CLOBs can improve performance
because the CLOB data can be fetched with the row from the database. AR System in-house
application developers convert any character field designed to contain more than 255 bytes into a
CLOB (database input length = 0). Typically, such fields are not expected to hold large amounts of
data. Therefore, unless you expect to store unusually large amounts of data in CLOBs, set this
option to TRUE before installing AR System applications so that all database tables for applications
are created in-row.
FALSE (default) --- CLOBs are created "out row."
Out-row CLOBs can cause the database to grow rapidly. Use out-row CLOBs only when your
database storage is not limited and your CLOBs are expected to hold large amounts of data.
Note
If a field contains more than 4000 characters, the CLOB is stored out row no matter which
value is specified for this server setting.
For more information about the storage and performance effects of using in-row versus out-row
CLOBs, see Using Oracle CLOBs with BMC Remedy AR System . The corresponding setting in the
AR System server configuration file is Oracle-Clob-Storage-In-Row. |
Currency (a group of columns composed of a
combination of the specified column types)
decimal, varchar, and number (15, 0 )
Date
number (15, 0 )
number (15, 0 )
Decimal
decimal
Diary
clob For more information, see the preceding Oracle data type
description for character fields with unlimited length.
Integer
number (15, 0 )
Real
float
Selection
number (15, 0 )
Time
number (15, 0 )
Page 2069 of 4705
Home
Sybase column types used for AR System fields

The following table shows the Sybase column types used for each AR System field type whose
values are stored in database tables.
Sybase column types used with AR System fields

Sybase column type
Attachment up to 2 GB
image
varchar
text
decimal, varchar, and int
Date
int
int
Decimal
decimal
Diary
text
Integer
int
Real
float
Selection
int
Time
int
Related information for supported databases

The following table lists suggested reading for databases that BMC Remedy AR System supports.
Depending on the version of your database, the titles might differ slightly.
Database type
Suggested reading
All
Introduction to Database Systems by C.J. Date
DB2
A Complete Guide to DB2 Universal Database by Don Chamberlin
Oracle
SQL Reference Manual
Oracle Administrator's Guide
Sybase
Sybase Commands Reference Manual
Sybase Administration Guide

Transact-SQL Desk Reference: For Microsoft SQL Server
Microsoft SQL Server 2000 Administrator's Companion
Page 2070 of 4705
Home
SQL definitions of the data dictionary tables

The SQL commands that define the data dictionary for the AR System database are in the following
files:
ARSystemServerInstallDir/Logs/arsystem_create_tab.txt
This file is created when you install the AR System server for the first time or when you
overwrite your current server installation. It contains all the SQL commands required to
create the default data dictionary for your AR System database type. This file is not deleted
or modified when you upgrade your server.
ARSystemServerInstallDir/Logs/arsystem_upgrade_sql.txt
When you upgrade your AR System server, this file is created to record the differences
between the SQL commands used to create the data dictionary in your previous version of
the AR System database and in your upgraded version.
Each subsequent upgrade overwrites this file. Therefore, to save its contents, rename it
before performing another upgrade.
The names of these files are the same for all database types.
To view the contents of these files in a reader-friendly format, open them in WordPad.
For more information about the SQL commands that define the AR System data dictionary,
see the following documents:
Database type
Document
DB2 Universal Database
A Complete Guide to DB2 Universal Database
Transact-SQL Desk Reference: For Microsoft SQL Server
Oracle
Oracle SQL Reference Manual
Sybase
Sybase Commands Reference Manual
Migrating applications and data between AR

System servers
This section contains information about migrating applications and data between AR System
servers:
Migration overview
Navigating the BMC Remedy Migrator interface
Setting BMC Remedy Migrator options
Performing migrations
Working with migration scripts
Using migration reports
Page 2071 of 4705
Home
Migration overview
This section contains information about the migration process and modes:
BMC Remedy Migrator process overview
How objects are migrated
Migration modes
Managing embedded server names
Cache file management overview
BMC Remedy Migrator process overview

BMC Remedy Migrator automates the process of transferring objects and data from one source (
server or file) to another. For example, you can develop workflow applications on a development
server (source) and use BMC Remedy Migrator to transfer them to a production server (destination)
, ensuring the integrity of all migrated changes.
With BMC Remedy Migrator, you connect to one or more AR System servers and then select a
source and destination for the objects, fields, or data you are migrating. The following sections refer
to two server types:
A source server, where you modify or update your applications that are in development.
A destination server, where users work with the current versions of your applications that are
in production.
Note
During migration, the source server should show no impact in performance. Impact to the
destination server can vary from minimal to heavy, depending on the number of changes
being made, the size of the objects, server speed, network bandwidth, and traffic.
You can perform migrations using either of two methods: immediate migrations or scripted
migrations.
Immediate migrations run in Migration mode.
Scripted migrations run in Scripting mode. In this mode, you create scripts that you can save
, schedule, and reuse. You can also use the Before and After commands to run a program
before or after the script executes.
To migrate objects, you select the objects you want to migrate and start the migration using
menu commands or by dragging the objects to the destination server.
A migration consists of the following steps:
1. BMC Remedy Migrator packages the selected objects.
2.
Page 2072 of 4705
Home
2. BMC Remedy Migrator expands the package and looks for join forms, table fields in forms,
related objects, and required menus.
3. BMC Remedy Migrator produces a migration results file.
4. The migration begins.
BMC Remedy Migrator migrates the objects in a specific sequence (see Migration sequence), and
then generates a migration result report.
Migration process
When a migration begins, BMC Remedy Migrator retrieves the next object from the results file and
compares the source object to the destination object, if any. Based on the results, BMC Remedy
Migrator performs the following actions:
Creates the object, if it is missing, on the destination server.
Modifies the destination server if the object is different from what is on the source server.
For Form and Related migrations, BMC Remedy Migrator performs the following actions:
Marks the objects to delete or disable if they are not in the source server.
Deletes or disables all marked objects (active links, filters, or escalations) that are on the
destination server.
Page 2073 of 4705
Home
How objects are migrated

This section explains how BMC Remedy Migrator moves objects and manages join forms, table
fields, and Form and Related Object migrations, and how BMC Remedy Migrator manages
embedded server names.
Form migrations
When migrating a form from one server to another, BMC Remedy Migrator migrates the form and
the menus referenced by the form. This makes sure that the form works correctly when a user
opens it in BMC Remedy Mid Tier. In some cases, BMC Remedy Migrator tries to migrate more
than the form and menus, as described in the following sections.
Migrating join forms

When migrating a join form, BMC Remedy Migrator builds a tree that represents the structure of the
join form. For example, to migrate Join Form A, BMC Remedy Migrator goes over the tree from top
to bottom to find all the regular forms first (shaded forms). To make sure that the forms are created
in the correct order, all the regular forms are migrated first, then all the join forms.
Join form migration example
Before migrating the forms, BMC Remedy Migrator processes them as follows:
Retrieves Join Form A, and sees that it has two member forms: Join Form B and Join Form
C.
Retrieves Form B, sees that it is a join form, and adds it to the join form list.
Retrieves Join Form C, sees that it is a join form, and adds it to the join form list.
Looks at Join Form B and sees that it has two member forms: Regular Form D and Join
Form E.
Page 2074 of 4705
Home
Retrieves Regular Form D, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form D because it does not have any
members.
Retrieves Join Form E, sees that it is a join form, and adds it to the join form list.
Looks at Join Form E, sees that it has two members: Regular Form H and Regular Form I.
Retrieves Regular Form H, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form H because it does not have any
members.
Retrieves Regular Form I, sees that it is a regular form, and adds it to the regular form list. At
this point, all processing stops for Regular Form I because it does not have any members.
Looks at Join Form C and sees that it has two members: Regular Form F and Join Form G.
Retrieves Regular Form F, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing stops for Regular Form F because it does not have any members
.
Retrieves Join Form G, sees that it is a join form, and adds it to the join form list.
Looks at Join Form G and sees that it has two members: Regular Form I and Regular Form
J.
Retrieves Regular Form I and sees that it is a regular form. However, it has already been
added to the regular form list. At this point, all processing stops for Regular Form I because
it does not have any members.
Retrieves Regular Form J, sees that it is a regular form, and adds it to the regular form list.
At this point, all processing for Regular Form J stops because it does not have any members
.
The forms are then migrated as follows:
Regular Forms D, H, I, F, and J are migrated first, because they do not depend on any other
forms.
Join Forms E and G are migrated next, because they are required for Join Forms B and C.
Join Forms B and C are migrated next, because they are required for Join Form A.
Finally, Join Form A is migrated, which was the original request.
Migrating a form and related objects

When migrating a form with related objects, BMC Remedy Migrator retrieves a list of the active
links, filters, escalations, associations, guides, applications, and web services attached to the form,
according to the options you set. It then adds those objects to the list of objects to be migrated.
For example, if you migrate a form with one active link and one filter, BMC Remedy Migrator
migrates the form, the active link, the filter, and any menus used by the form. If you migrate a join
form, BMC Remedy Migrator includes the objects related only to the join form. It does not include
the objects related to the forms needed to complete the join form migration.
BMC Remedy AR System and BMC Remedy Migrator use field IDs, not field names, to determine
differences between source and destination environments. For example, if the source form has a
Page 2075 of 4705
Home
field name of Field_ABC, and the destination form has a field name of Field_XYZ, with the same
field ID, BMC Remedy Migrator replaces instances of the form Field_XYZ with Field_ABC on the
destination server.
After a migration from a development server to a production server, you might notice that field
names on forms or fields referenced in workflow (such as Set Fields actions) have been changed
on the production server.
If field names are the same, but field IDs are not, and the migration includes data, then the scenario
is reversed: BMC Remedy Migrator migrates data to the destination form and creates entries on the
destination server where the field IDs are the same. If the source form has a field name of
Field_ABC and the target form has a field name of Field_ABC with different field IDs, BMC
Remedy Migrator migrates the data to the destination field ID that matches. If the field types are not
the same, the migration fails.
Before making modifications to your development environment, migrate the production server to the
development server. This ensures that field IDs are synchronized. If you need to add fields to both
environments manually, assign them the same field ID.
Archive forms
If you are migrating a form that has an archive form associated with it, the archive form is created
on the destination if it does not already exist, or it is modified if it already exists. When a regular
form is migrated for the first time, the server creates the form itself, then the archive form.
Migration modes
BMC Remedy Migrator executes migrations in two different modes: Migration mode and Scripting
mode. BMC Remedy Migrator defaults to the last mode used.
You can also use either Migration or Scripting mode to perform a copy/prefix migration on the same
server (see Copy-Prefix migrations).
Depending on how many threads you allocate in the Migration option, you can perform as many
migrations simultaneously as there are threads. If BMC Remedy Migrator uses up its allocation of
threads, migrations are queued until a thread becomes available. For more information about
threads, see Using multiple-threads for multiple migration.
Migration mode
In Migration mode, migrations run immediately.
Scripting mode
In Scripting mode, you can create migration scripts that can be saved and run manually at your
convenience, or scheduled to run at a specific date and time.
Page 2076 of 4705
Home
You can use Scripting mode to migrate objects from one server to multiple servers. You can create
reusable sets of multiple server migrations and put them in a holding position. This keeps you from
having to run each migration separately, one after the other. You can schedule them to run on a
specific day and time, or you can open and run them whenever they are needed.
For additional information about migration scripts and scheduling migration scripts, see Creating
and saving migration scripts and Scheduling scripted migrations.
Copy-Prefix migrations
When using only one server, you cannot migrate identically named objects to the same server. You
must change the prefix before a migration can begin. In a Copy/Prefix migration, you migrate
objects to the same server, and then change the object's prefix in the Prefix dialog box. See,
Migrating objects to the same server.
The Copy/Prefix migration runs in either migration or scripting mode. It is useful for doing simple
development or testing of workflow on the same server. It also keeps all the relationships between
forms and related workflow separate.
Managing embedded server names

Objects and fields you can migrate
Sequence for migrating objects
How preference servers work
How authentication servers work
BMC Remedy Migrator replaces all object references to the source server with the name of the
destination server when migrating from one server to another. When trying to determine if an object
references the source server, BMC Remedy Migrator uses the name of the server you defined in
the Accounts dialog box.
For example, if you define the server as a fully qualified host name (such as source.domain.com),
BMC Remedy Migrator uses source.domain.com as the name of the server it replaces. Any
references to the unqualified name source are not replaced. If you define the server name as only
source, BMC Remedy Migrator replaces any references it finds to both the unqualified name source
and the fully qualified host name source.domain.com. BMC Remedy Migrator considers
source.domain.com, source.some.otherdomain.com, and source.domain.net to be the same
server.
The following table outlines what happens to server references when BMC Remedy Migrator
replaces the reference for servers named "source" with the reference "destination," when both of
the servers are in the*domain.com* domain.
Page 2077 of 4705
Home
Change in server references for source names

Server name
referenced
Server name
replaced with
Action taken by BMC Remedy Migrator
source
destination
recognizes source and replaces it with destination.
source.domain.com
destination
recognizes source and replaces it with destination.
source.otherdomain.net
destination
recognizes source and replaces it with destination, because it does not know
that the domain is not the correct one.
server.domain.com
server.domain.
com
The object references a different server and BMC Remedy Migrator leaves the
reference intact.
The following table outlines what happens to server references when BMC Remedy Migrator
replaces the references for servers named source.domain.com with "destination," when both of
the servers are in the domain.com domain.
Changes in server references for destination names
Server name
referenced
Server name
replaced with
Action taken by BMC Remedy Migrator
source
source
does not recognize the name as the same as source.domain.com and does
not replace it.
source.domain.com
destination
recognizes source.domain.com and replaces it with destination.
source.otherdomain.net
source.otherdomain.
net
does not recognize the name as the same as source.domain.com and does
not replace it.
server.domain.com
server.domain.com
The object references a different server and BMC Remedy Migrator leaves
the reference intact.
Objects and fields you can migrate

BMC Remedy Migrator can migrate the following BMC Remedy AR System objects and fields.
Objects
BMC Remedy AR System objects that you can migrate include:
Forms (including different views of forms)
Workflow objects (active links, filters, escalations, active link and filter guides), including
locked objects
Associations
Applications, including deployable applications
Packing lists
Web services
Menus
Groups
Roles
Distributed maps
Page 2078 of 4705
Home
Distributed pools
Data
Views
Flashboards (variables, data sources, Flashboards, and Flashboards alarms)
System objects
Plug-in definitions
Plug-in modules
Fields
BMC Remedy AR System fields that you can migrate include:
Data fields (character, diary, integer, real, selection, date/time, date, time, decimal,
attachment, attachment pool, currency)
Control fields (buttons, menus, toolbar icons)
Trim fields (lines, boxes, text)
Table fields (client side or server side), including tree view and table views
Page fields
Flashboards fields
Alert List fields
Application List fields
View fields
Result List fields
Data visualization fields
Sequence for migrating objects

BMC Remedy Migrator uses a predefined sequence for migrating objects. For Regular, Join,
Display-only, View, and Vendor forms, BMC Remedy Migrator looks for the views, then the fields,
for each form, repeating the process if necessary before it moves on to the next object type in the
sequence. The following table outlines the sequence of object migrations.
Object migration sequence
Sequence
Object
Sequence
Object
Groups
15
Active link guides
Roles
16
Distributed Server Options: DSO maps
Regular forms:
17
Distributed Server Options: DSO pools
18
Flashboards variables
3a Views
3b Fields
Join forms:
4a Views
Page 2079 of 4705
Home
Sequence
Object
Sequence
Object
19
Flashboards data sources
20
Flashboards
21
Flashboards alarms
4b Fields
Display-only forms:
5a Views
5b Fields
View forms:
6a Views
6b Fields
Vendor forms:
7a Views
7b Fields
Fields
22
Filter guides
Views
23
Web Services
10
Images
24
Packing lists
11
Menus
25
Applications
12
Active Links
26
Plug-in modules
13
Filters
27
Plug-in definitions
14
Escalations
28
Data
How preference servers work

You can log on to a preference server, which sets the behavior and display characteristics of each
client. These preferences can be stored locally on the client machine, or centrally on a designated
preference server. Centralized preferences make the same settings and customizations available
when logging in to multiple machines. Local preferences can be used when no preference server is
designated or available. Regardless of whether centralized or local preferences are used, multiple
users can use the same client machine with individual preferences and customizations.
Only BMC Remedy AR System 5.0 or later servers can be used as preference servers. If no
preference forms are found on your AR System server, a text box appears asking if you want to
create the preference server forms. The BMC Remedy Migrator Preference form is then created to
set up a preference server.
For more information about preference servers, see Setting user preferences.
Note
Page 2080 of 4705
Home
If you are logged in to two computers simultaneously and make a change on one by
changing an option or licensing a server, you do not automatically see the new options or
licenses on the other computer. You must log on again to the preference server to view
the new changes.
How authentication servers work

Administrators can have greater control by verifying user authentication using an authentication
server . With an authentication server, BMC Remedy Migrator checks to see if a user is a
registered user. If a match is found, the user definition and permissions specified in the matching
user record are used. If no match is found, the authentication is stopped and the user is treated as
a guest user.
If authentication is not enabled in BMC Remedy AR System, BMC Remedy Migrator cannot
authenticate a user. See Configuring after installation or Configuring the AR System server for
external authentication.
Cache file management overview

In this topic:
Refreshing and updating cached objects
Space limitations on caching
When you open a server window for the first time, BMC Remedy Migrator generates the following
cache files in the Migrator directory on your hard drive:
A server cache, where workflow support files are located.
A database information cache for the server, which lists all the required BMC Remedy AR
System object information. This information is used by the list views for both the server
windows and the form detail windows.
A dependency file cache for the server, which is used to generate upward and downward
dependency information.
You can specify the directory in which to store cache files. See Specifying directories to store
migration files.
Although initial caching takes time because BMC Remedy Migrator copies all the objects from the
server to your computer and builds the database, cache files ultimately save time and lessen the
load on the server.
Refreshing and updating cached objects

To recache your computer after the initial caching, select View > Refresh (or press F5).
Whenever you reopen a server window, BMC Remedy Migrator updates cache files, taking less
Page 2081 of 4705
Home
time because only changed objects are cached. BMC Remedy Migrator also updates the object
type cache when you switch object types in the left pane of the server window. For example, when
you go from Forms and click Filters, BMC Remedy Migrator updates filters. When you go from
Filters and click Forms, BMC Remedy Migrator updates forms.
BMC Remedy Migrator also updates the cache file during a migration. To view the changes in the
cache after a migration, refresh your display by pressing F5.
You can turn automatic caching on or off. To do so, select Tools > Options, and then click General
in the left pane to display the caching options (see Setting general options).
Note
BMC Remedy Migrator provides an option to keep or delete the database and
dependency files generated with .migrator files. See Setting general options.
Space limitations on caching

During a cache process, BMC Remedy Migrator warns you when less than 10 MB of space is
available on your computer. When you see this warning, stop the caching process, create more
hard drive space, and then cache again.
Warning
If you rename any object on a server where the cache is enabled, you must open that
server in BMC Remedy Migrator and update the cache before making any more changes
to that object. This is required for the cache to recognize the object changes.
Navigating the BMC Remedy Migrator interface

This section describes how to navigate the BMC Remedy Migrator interface. It also describes
logging on to AR System server through BMC Remedy Migrator.
Working with BMC Remedy Migrator
Page 2082 of 4705
Home

The first time you log on to an AR System server, BMC Remedy Migrator retrieves all object
definitions from the associated server. This retrieval builds a cache on the client machine in the
Migrator directory. The first retrieval can take some time, but makes it faster and easier to access
those definitions in the future.
Note
By default, caching is disabled. See Displaying objects in a server window for information
about managing the cache process.
Logging on and opening a server window

BMC Remedy Migrator provides two methods by which you can log on. The following procedures
outline each method. For information about setting login options, see Setting general options.
To log on to BMC Remedy Migrator

1. Perform either of the following actions:
If you are not already logged in, select File > New Server Window to display the Login dialog
box and open a new server window.
To log on to BMC Remedy Migrator without opening a server, select Tools > Login. For
example, you must be logged in to BMC Remedy Migrator to refresh a previously saved
differences report or to add licensed servers.
Note
You must license the server that you want to log on. For information about adding a
license, see Navigating the BMC Remedy Migrator interface .
1. In the Login dialog box, enter your BMC Remedy AR System user name and password for
that server, and click OK.
By default, the BMC Remedy Migrator login window shows the User Name and Password
fields only. By clicking the Options button, you can also display the Preference Server and
Authentication fields.
The first time you use BMC Remedy Migrator, both the User Name and Password fields are
empty. The next time you log on, BMC Remedy Migrator remembers the last user name and
tries that information first (unless it has been changed) when logging on to a server.
2. (optional) To log on to a preference server, click the Options button to display the Preference
Server field. Then, enter or select the preference server name.
3. If required, type your authentication server in the Authentication text box.
4.
Page 2083 of 4705
Home
4. To add, modify, or delete an existing server or manage usage of a server, click the Accounts
button.
For information about the Accounts dialog box, see Working with BMC Remedy Migrator.
5. Click OK.
6. In the Select Server dialog box, select the server you want to use, and click OK.
The server window appears, showing the BMC Remedy AR System objects residing on the
server you logged in to. Then, the Retrieving Objects window appears and lists the objects
that BMC Remedy Migrator is opening for the server.
Note
Depending on the number of objects the server has stored, opening a server can
take some time while objects are being retrieved and cached. You can cancel the
cache process by clicking the Cancel button in the Retrieving Objects window.
7. (optional) To open another server window, repeat this procedure.

By logging on to each server individually, you can specify a different user name and
password for each server.
Working with BMC Remedy Migrator

This section describes viewing and using windows, and synchronizing views in BMC Remedy AR
System. It explains how to use the migration status pane and how to customize menus, toolbars,
and columns. It also describes how server windows work, how to display or remove objects and
forms in server windows, and how to export and convert definition and XML files.
BMC Remedy Migrator main window overview
Using the migration status pane and tabs
Using menus and the main menu bar
Customizing BMC Remedy Migrator
Working with server windows
Creating a data search
Using field mappings
Shortcut keys
BMC Remedy Migrator main window overview

The main BMC Remedy Migrator window displays tools and information that control viewing server
or report information and viewing synchronized objects across views. You can navigate in BMC
Remedy Migrator using the mouse or shortcut keys, or by customizing the main menu or toolbars.
Page 2084 of 4705
Home
For information about menus, toolbars, and shortcut keys, see Customizing BMC Remedy Migrator.
When you open BMC Remedy Migrator without logging on to a specific server, the main window is
empty. When you open a server window, you can display object details, migration status details,
reports, files, and scripts.
Note
Not all menu items or toolbar buttons are accessible until you log on to a server and open
a file.
BMC Remedy Migrator main window

The BMC Remedy Migrator main window includes the following areas:
Title bar--Displays the currently open server.
Main menu bar and toolbars--Appears at the top of the window. For information about
customizing the main menu bar and toolbars, see Customizing BMC Remedy Migrator. For a
detailed description of the main menu bar and toolbars, see Using menus and the main
menu bar.
Left pane (navigation pane)--Displays lists of objects available for the currently open server.
Object lists can be displayed in two formats:
Object type tab--groups objects in folders by how they are named. See Displaying
objects in the Object Type view.
Prefix tab--Lists objects by folders named according to how they are organized, for
example, a packing list. Some objects might be grouped under folders with labels
using initials. See Displaying objects in the Prefix view.
Right pane (object list view)--Displays the server and report windows, with details for the
currently selected object or report. See Types of object details.
Page 2085 of 4705
Home
Status bar--Appears at the bottom of the main BMC Remedy Migrator window. It displays the
Messages about the status of BMC Remedy Migrator tasks
The name of the user currently logged in to BMC Remedy Migrator
Help for menu commands and toolbar buttons
To show or hide the status bar, select View > Status Bar.
In addition, a migration status pane can be displayed at the bottom of the window
when you select View > Migration Status. This area displays migration in progress
and enables you to control, monitor, and store migrations. The status pane is
described in Using the migration status pane and tabs .
Viewing information in BMC Remedy Migrator windows
Viewing synchronization within windows
Viewing information in BMC Remedy Migrator windows

In the left pane of the server window, you can use either the Object Type or Prefix tab to select
Backup files, Script files, and Migration Report Result files. To view these files, save them in the
directories specified in BMC Remedy Migrator options. See Specifying directories to store migration
files.
To locate a file in a different directory, select Tools > Options > Directories. To display the contents
of a file, select that file in the right pane.
Object lists appear within windows in ascending order by name when you open a secondary
window or when you select a new object type.
Note
Nonalphabeti cal characters are sorted individually before alphabetical characters. For
example, a dash (-) is sorted before a colon (:).
Viewing synchronization within windows

To synchronize the window views, select an object in any open server or report window and select
View > Synchronize Views. If that object is located in the server or report, every open view displays
the selected object.
Page 2086 of 4705
Home
Using the migration status pane and tabs

You can use the migration status pane and status tabs to view and control migrations. From the
status pane, you can watch the progress of a migration and use the status tabs to monitor a
migration's status. You can also control active migrations and view information about active,
completed, and scripted migrations.
Migration status panes

The migration status pane at the bottom of the BMC Remedy Migrator window displays an instant
view for monitoring all your migration activity (see also Managing migrations).
To show or hide the migration status pane, select View > Migration Status.
Migration status pane
To undock and relocate the migration status pane, select the outer edge of the pane and drag it to
another location.
The following table outlines the information you can view in the migration status pane:
Information in migration status pane
Field
What it does
Name
Lists the script name or migration name.
Status
Shows the status of an interrupted or completed migration, and how many passes of this migration have occurred.
For example, if this is the first instance of this migration, a migration is being repeated once, the message "Migrating
pass 1." This enables you to see how many times a specific migration occurred.
Type
Designates a scheduled or immediate migration.
Progress
Indicates the completion percentage for a migration.
Start Time
Indicates the actual start time for a migration.
End Time
Indicates the actual end time for a migration.
Source
Lists the name of the source server.
Destination
Lists the name of the destination server.
Page 2087 of 4705
Home
Field
What it does
Description
Displays a brief description of the migration.
Migration status tabs

The migration status tabs show you an instant view of all your migration activity. You can view
immediate, scheduled, or completed migrations, depending on which status tab you select.
Click each tab to show the status of the following types of migrations:
All--Shows all immediate and scheduled migrations in progress.
Immediate --Shows all immediate migrations that are in progress, queued, or interrupted.
Scheduled --Shows all scheduled migrations, as indicated by migration scripts.
Completed --Shows all completed migrations. To display the migration statistics in a
migration result report, click the Completed tab and then double-click a migration listing.
Using menus and the main menu bar

The main menu bar, at the top of the main BMC Remedy Migrator window, provides access to most
of BMC Remedy Migrator's features, such as: licensing and logging on to servers, migrating AR
System objects between servers, exporting definitions, and printing. You can customize BMC
Remedy Migrator's main menu to fit your individual working style. (See Customizing BMC Remedy
Migrator for additional information.)
If a menu contains commands that are gray, that command is unavailable for the task you are
working on. Not all menu items are available or listed until you log on to a server and open a file. A
brief description of all of the main menu commands appears in the following tables.
File menu
Edit menu
View menu
Servers menu
AR System Objects menu
Migrate menu
Script menu
Tools menu
Window menu
Help menu
File menu
The selections available in the BMC Remedy Migrator File menu depend on the window that is
currently active. For example, the New Differences Object and New Migration Script selections
become available only when a server window is open and active. The Export to HTML selection
becomes available only when a dependencies, differences, or results report window is open and
active.
Page 2088 of 4705
Home
File menu selections

Menu
selection
Use to
New
Open a new server window. When you make this selection, you are prompted to select a server. You can have
Server
Window
multiple server windows open in a single session.
New
Migrator
File
Create a new .migrator file. When you make this selection, a definition window opens. You can add to the contents
of this window by dragging objects to it from any open server window. Then, select either Server or Migrator File as
the destination type.
New
Create a new Differences report. When you make this selection, a new definition window opens. You can then add
Differences
Window
content by dragging objects to it from any open server window. Then, select either Server or Migrator File as the
destination type.
New
Migration
Script
Create a new migration script. When you make this selection, a new window opens. You can then record migrations
that are happening from one server to another, or to a file.
Open
Select a file to open in BMC Remedy Migrator.
Close
Close the active window.
Save
Save an open window or file using the existing name or a default.
Save As
Save an open window or file with a new name.
Print
Select a printer, a print range (pages), and number of copies.
Print
Preview
Preview the file you want to print (migration result, differences, and dependency reports only).
Print Setup
Select a printer, paper, and orientation.
Send
Open a send window form your email application so you can send the currently active file on your desktop.
Export to
Export a report to HTML format for editing and printing. This selection appears only when a report is open.
HTML
Recent
Files
List the most recent files used.
Exit
Shut down BMC Remedy Migrator.
Edit menu
The following table lists selections in the BMC Remedy Migrator Edit menu.
Edit menu selections

Menu selection
Use to
Copy
Copy a selected object in a BMC Remedy Migrator window.
Paste
Paste an object that was copied into a BMC Remedy Migrator window.
Delete
Delete a selected object in a BMC Remedy Migrator window.
Page 2089 of 4705
Home
View menu
The BMC Remedy Migrator View menu provides several submenus. The Search Bar command is
available only after opening a Form Details window; the Description Bar selection is available only
after opening a Script window; and the Zoom selection is available only when you are viewing an
active report.
View menu selections
Menu selection
Use to
By Application
Filter the server view to show only local and deployable applications.
By Workspace
Filter the server view to show only objects included in a specified workspace or packing list.
By Form
Filter the current Server/Definition view to display a subset or selected list of forms, together with
related objects.
Normal
Switch filtering off when users select viewing by form, application, or workspace.
Form Details
Show form details in a new window, including fields, views, and related objects.
Differences
Show the differences between two or more selected objects.
Form and Related

Differences
Show the differences between forms and their related objects.
Downward Dependencies
Show downward dependencies for a selected object.
Upward Dependencies
Show upward dependencies for a selected object.
Toolbars
Select the toolbars that you want displayed in the main window.
Migration Status
Show or hide the migration status pane at the bottom of the main window.
Description Bar
Show or hide the description bar (for before and after commands) when you are creating a migration
script.
Status Bar
Show or hide the status bar beneath the migration status pane.
Arrange Icons
Arrange a window's icons alphabetically by name, automatically, or lined up on a grid.
Zoom
Set the Zoom factor for the dependencies, differences, and migration result reports, and for printing a
report.
Refresh
Refresh the current view.
Synchronize Views
Synchronize objects within the other open server and report windows.
Servers menu
The Servers menu is available only when a new script is created or an existing script is opened.
Servers menu selections
Menu selection
Use to
Change Login Information
Update login information, or log on as a different user.
Add Server
Select another server to add to the list of servers in a script.
Page 2090 of 4705
Home
Menu selection
Use to
Add Migration File
Add a .migrator file.
Remove Server
Remove a server from the list of servers in a script.
Change History Option
Modify the Change History options on a server in a script.
Change History String
Modify the string in the Change History options on a server in a script.
Default Prefix Options
Change the default prefix options on a server in a script.
Use Definition Files for Backup
Specify a definition (.def ) file format as the backup on a server in a script.
Use Migrator Files for Backup
Specify a .migrator file format as the backup on a server in a script.
Back Up All Objects
Back up all objects on a server in a script.
Back Up Specified Objects
Select the objects to be backed up on a server in a script.
Back Up Directory
Specify a directory for storage of backup files on a server in a script.
AR System Objects menu

The Objects menu is available only when a new script is created or an existing script is opened.
Objects menu selections
Menu selection
Use to
Change Source
Change the source server for an object in a script.
Change Destination
Change the destination server for an object in a script.
Prefix Options
Change the prefix options for an object in a script.
Destination Name
Change the name of the object on the destination server in a script.
Data Mode
Open the Data Migration Settings dialog box used to set up data migrations.
Number of Records
Enter the number of records to use for a data migration.
Search Criteria
Enter an actual data migration search.
Remove Object
Remove the object form the list of objects in a script.
Migrate menu
The following table outlines the Migrate menu and its submenus. The All Fields, All Views, and
Migrate Field by Type submenus and selections are available only from a Form Detail window.
Migrate menu selections
Menu selection
Use to
All BMC Remedy AR System
Migrate all objects.
Objects
Form and Related Objects
Migrate selected forms and their related objects.
Deploy Application
Migrate an application and its supporting objects.
Page 2091 of 4705
Home
Selected Objects
Migrate selected objects.
Form Data
Display a submenu that allows you to:

Migrate form data only.
Migrate a form and data.
Migrate a form, related objects, and data.
Migrate Objects by Type
Display a submenu that allows you to migrate the following objects:

All forms
All active links
All filters
All escalations
All active link guides
All applications
All packing lists
All web services
All menus
All groups
All images
All distributed maps
All distributed pools
All Flashboards
All Flashboard data sources
All Flashboard variables
All Flashboard alarms
All Fields
Migrate all fields form selected forms.
All Views
Migrate all views from selected forms.
Migrate Field by Type
Select the following field types to migrate from selected forms (from the Form Detail
window):
Character fields
Diary fields
Integer fields
Real fields
Selection fields
Date/time fields
Decimal fields
Buttons
Panel fields
Lines
Boxes
Text
Attachments
Tables
Alert fields
Result list fields
View fields
Flashboard fields
Currency fields
Date fields
Time fields
Page 2092 of 4705
Home
Set Admin Mode on Destination

Server
Turn on or off the restriction of non-administrative users during a migration.
Migration Mode
Run migrations immediately.
Scripting Mode
Create a migration script to save or schedule.
Script menu
The following table lists selections available in the Migrator Script menu.
Script menu selections
Menu selection
Use to
Schedule Migration
Script
Schedule a migration for the specific month, date, and time, and the users to notify upon completion.
Edit Scheduled
Migration
Edit a scheduled migration.
Execute Migration Script
Open and run a migration script.
Tools menu
The Tools menu includes Source Control options. If Source Control installed on your system, the
Source Control submenu selections are also available.
Tools menu selections
Menu selection
Use to
Login
Open the Login dialog box.
Accounts
Manage user and server lists (where you add servers to BMC Remedy Migrator)
Licenses
Display current licenses and add or edit existing licenses.
Export
Definitions
Export object definitions to an BMC Remedy AR System definition ( .def ) file.
Export
Export an application to an BMC Remedy AR System definition (. def ) or XML (.xml ) file.
Application
Export Locked
Definitions
Export locked object definitions to an BMC Remedy AR System definition ( .def ) file. The lock key must be
entered and verified, and a lock type selected.
Convert
Convert BMC Remedy Migrator definition (.def ) files to Migrator (.migrator ) definition format.
Definition Files
Customize
Customize the main menu and toolbars.
Options
Configure BMC Remedy Migrator options.
Source Control
Display a submenu that allows you to perform the following tasks:

Get the latest version
Check in a file
Check out a file
Page 2093 of 4705
Home
Undo a checkout action

Add to Source Control
Remove from Source Control
Show the history
Show the differences
Show user information
Activate the refresh status
Run Source Control client
Window menu
The Window menu provides options for positioning BMC Remedy Migrator objects on your screen.
Window menu selections
Menu selection
Use to
Close
Close the active window.
Close All
Close all active windows.
Next
Display the next active window.
Previous
Display the previous active window.
Cascade
Arrange windows so they overlap.
Tile Horizontally
Arrange windows as horizontal, non-overlapping tiles.
Tile Vertically
Arrange windows as vertical, non-overlapping tiles.
Arrange Icons
Arrange icons at the bottom of the Window menu.
Server and Window List
List the open servers and windows for a session with the active server or window checked.
Help menu
The Help menu provides options for displaying BMC Remedy Migrator online help and version
information.
Help menu selections
Menu selection
Use to
Help topics
Open BMC Remedy Migrator help.
About BMC Remedy Migrator
Display program information, version number, and copyright date.
Customizing BMC Remedy Migrator

You can customize the BMC Remedy Migrator main menu, toolbars, and columns in windows.
Page 2094 of 4705
Home
Customizing the main menu and toolbars

To rearrange the items on the main menu, drag the menu items to a new location on the menu. To
remove toolbar buttons from the main toolbar, drag the buttons down into the main window.
To change the look of the toolbars, create a new toolbar, or to change BMC Remedy Migrator's
default toolbars and main menu, use the following procedure:
To customize the main menu and toolbars

1. Select Tools > Customize.
2. In the Customize dialog box, perform any of the following actions in the Toolbars tab (the
following figure):
Click a toolbar name to select or clear that toolbar.
Click Show Tooltips to select or clear the help text that is displayed when you point to
a toolbar button.
Click Cool Look to select or clear the shadow effect around the toolbar buttons.
Click Reset to restore BMC Remedy Migrator's default toolbars and main menu.
Click New to create a new user-defined toolbar. Then, type in the new toolbar name
and click OK, making sure to select the Toolbars tab. The new toolbar appears on
your screen empty.
Customize dialog box-Toolbars tab
3.
Page 2095 of 4705
Home
3. To add toolbar buttons or menu commands to the default view of the main window, click the
Command tab (the following figure) and select a category, and then drag the toolbar buttons
or menu items to your new toolbar.
Customize dialog box-Command tab
4. When you have finished making changes, click OK.
Rearranging window columns

You can rearrange the column order in a server window, a Form Detail view, and a Script view for a
chosen tree item.
To rearrange column order in a window

1. Select an object in the left pane of the server window.
2. Drag and drop the columns to a new location.
The next time you open the server window, BMC Remedy Migrator remembers your
changes and displays the columns in their new locations. You can also rearrange the
columns in the migration status pane.
Working with server windows

Use server windows to perform most migration tasks. When you open a server window, functions in
the main menu applicable to the task you are performing are available. Unavailable functions are
either not necessary for the task, or you have not selected the items that activate them.
You can have multiple server windows open in the BMC Remedy Migrator main window.
Page 2096 of 4705
Home
In this topic:
Opening a server window
Displaying objects in a server window
Viewing objects by form
Viewing form details
Viewing objects by application
Viewing objects by workspace
Types of object details
Deleting objects from servers or files
BMC Remedy Migrator performs the following actions:
Creates cache files by retrieving objects for the server and copying them to your computer. A
cache progress window shows the objects that are being retrieved. You can cancel the
cache by clicking the Cancel button.
Lists server objects in the left pane of the server window. You can select how objects are
viewed by clicking either the Object View or Prefix tabs.
Displays details for a selected object or report. You can view objects by form, by application,
or by workspace. See Displaying objects in a server window.
Opening a server window

Perform the following steps to open a server window in BMC Remedy Migrator.
To open a server window

1. Select File > New Server window.
2. From the list, select a server.
Opening a new server window
Page 2097 of 4705
Home
Displaying objects in a server window

When you log on to a server, the objects for that server are displayed in a server window.
Displaying objects in the Object Type view

The Object Type view lists objects by their type. It also lists backup, script, and result files. If no
objects exist on the server for an object type, that object type is not listed.
Object Type view
Page 2098 of 4705
Home
To view objects by type, click the Object Type tab in the left pane of the BMC Remedy Migrator
main window. To display all objects of a specific type, select the type from the list. The objects of
that type are listed in the right pane.
Displaying objects in the Prefix view

The Prefix view groups objects into folders, based on categories or on naming conventions you
define using colon (:) delimiters. For example, all objects named MB objectName appear in a folder
called MB. Objects named MB:Sub1: objectName appear in a Sub1 folder under the MB folder. In
the Name column, only the objectName portion of the object name is displayed.
Prefix view
Page 2099 of 4705
Home
To view objects by prefix, click the Prefix tab in the left pane of the BMC Remedy Migrator main
window. To view a set of objects, click the folder for the objects you want to view.

You can view the list of objects associated with each form.
Page 2100 of 4705
Home
To display objects by form

1. Select View > By Form.
The By Forms dialog box appears. By default, All Forms is the selected view option, and the
list of available forms is disabled.
2. In the View Option area, click the option button for the types of forms you want to view, and
click OK.
If you select Forms with Prefix, the Prefix field becomes enabled. Enter a prefix.
If you select Selected Forms, use the Add, Remove, Add All, or Remove All buttons to
create a list of the forms you want to view. To select more than one form, hold down
the Ctrl or Shift key as you make your selections.
3. In the left pane of the server window, click Forms to display the forms you selected.
BMC Remedy Migrator displays the forms according to the view options, and all the objects
related to those forms.
Viewing form details

You can double-click a form to view its details (or click once and press Enter).
In addition, you can view the details of forms (fields, views, and data) by right-clicking a form in the
Page 2101 of 4705
Home
right pane and then choosing Form Details. This action displays the Form Detail tree view.
Form detail list showing field details
To display the details of a selected form

1. In the left pane of the server window, under BMC Remedy AR System Objects, click Forms.
2. In the right pane of the server window, select a form.
3. Select View > Form Details.
The details for the selected form appear in the right pane of the BMC Remedy Migrator
window. The header bar shows the name of the form and the number of objects being
viewed for that form.
From the Form Detail window, you can migrate fields, views, data, and other objects related
to that form.
Note
When dragging an active link, filter, escalation, and so on from a Form Detail
window to another Form Detail window, the name of the form to which the object is
linked is not changed to the destination form name. Only fields and views are
created on the destination form. Also, data with fields and views are the only
objects migrated to the destination Form Detail view.
Viewing objects by application

You can view the list of objects pertaining to an application.
Page 2102 of 4705
Home
To view objects by application

1. Select View > View by Application.
View by Applications dialog box
2. In the By Application dialog box, select a local or deployable application.

For more information about local and deployable applications, see Deployable applications.
The objects for the selected application are listed in the right pane of the server window.
Viewing objects by workspace

A workspace allows you to limit the objects displayed in a window to only those objects that are
associated with a particular packing list or application. When you create new objects in the context
of the workspace, the objects are added to the packing list or application. For more information
about workspaces, see Starting and logging on to BMC Remedy Developer Studio .
To view objects by workspace

1. Click in the server or file window whose workspace objects you want to display.
Make sure that All Forms is selected in the By Form dialog box; otherwise, the menu option
is disabled. See Viewing objects by form.
2. Select View > By Workspace.
The By Workspace dialog box appears. If no workspace has been created on this server, the
message "No current record" appears.
3. Select an application or packing list from the list, and click OK.
In the server window, the object category reflects the options selected in the By Workspace
dialog box. For more information about applications, see Developing an application.
Page 2103 of 4705
Home
Types of object details

The right pane of the server or file window (the following figure) displays columns of objects and
details about each object listed. The following sections list the items listed for each object type.
Details for selected objects
Forms
The following table contains the items listed for forms.
Items listed for forms
Item
Description
Form Name
The name of the object.
Type
For forms, the type of form, such as Join or Regular.
Access Point
Whether an access point is available for the object. You can identify specific forms and guides in
deployable applications as access points, or points of integration, for use with other deployable
applications. For more information about deployable applications, see Deployable applications.
New Entry Point
Whether any new entry points are available for the object. A new entry point can be clicked to start a
task, such as creating a request. Entry points are listed in the Application List field on the home page
. For more information about home pages, see Home page components.
Search Entry Point
Whether any search entry points are available for the object. A search entry point can be clicked to
start a search.
Owner
The name of the user who created the object.
Timestamp
The date and time on which the object was created or changed.
Last Changed
The name of the user who last updated the object.
Lock State
The locked state of the object. Locking allows application developers to protect workflow objects that
are not designed for or intended to be customized, by preventing them from being modified or even
viewed. An object can have one of the following locked states:
None Allows users to view and modify the object.
Read-only Prevents users from modifying the object, but allows them to view its details.
Hidden More restrictive lock that prevents users from viewing details of a locked object,
including in BMC Remedy Migrator differences and dependency reports.
Page 2104 of 4705
Home
For more information about locked objects, see Locking objects.

Archive
Whether archiving is enabled or disabled for a form. You can use the data archiving feature in BMC
Remedy AR System to set up options for backing up of data in forms. Archive forms can be migrated
if they exist on the destination. For more information about data archiving, see Archiving data.
Views, Fields, Data Fields,

Trim Fields, Control Fields
The number of fields of each type included in the form.
, Page Fields, Table Fields

Member A, Member B,
If this is a join form, the names of the member forms.
and so on
Active links, filters, and escalations

The following table contains the items listed for active links, filters, and escalations.
Items listed for active links, filters, and escalations
Item
Description
Name
The name of the active link, filter, or escalation.
Primary
Form
The name of the form that appears in BMC Remedy Mid Tier when the application opens.
Forms
The number of forms referenced.
Referenced
Enabled
Whether this object is enabled.
Order
The execution order for this object.
Execute On
The action on which this object executes.
If Actions
The number of if actions included.
Else Actions
The number of else actions included.
Owner
The name of the user who created this object.
Timestamp
The date and time on which this object was last changed.
Last
Changed
The name of the user who last changed this object.
Lock State
The locked state of the object. Locking allows application developers to protect workflow objects that are not
designed for or intended to be customized, by preventing them from being modified or even viewed. An object can
have one of the following locked states:
Control
Field (active
links only)
Typically a menu field or a button, which fires an active link when selected.
Focus Field
(active links
only)
A field on which an active link fires when the field gains focus.
Page 2105 of 4705
Home
Qualification
The text of any qualification created for this object.
Active link guides and filter guides

The following table contains the items listed for active links, filters, and escalations.
Items listed for active link guides and filter guides
Item
Description
Name
The name of the active link guide or filter guide that appears in the server window the BMC Remedy System
Administration Console.
Form
Name
The name of the form to which the guide applies.
Type
The type of form to which the guide applies, for example, a regular form.
Label
The name of the guide that appears in the Open dialog box in BMC Remedy Mid Tier.
Owner
The name of the user who created the guide.
Timestamp
The date and time on which the guide was last changed.
Last
Changed
The name of the user who last changed the guide.
Lock State
Hidden More restrictive lock that prevents users from viewing details of a locked object, including in BMC
Remedy Migrator differences and dependency reports.
Description
A description of the guide's function.
Applications
The following table contains the items listed for applications.
Items listed for applications
Item
Description
Application
Name
The name for the application.
Application
Label
The name for the application that appears in the Open dialog box in BMC Remedy Mid Tier, and in the application
title bar.
Primary
Form
The form that appears when the application is opened in BMC Remedy Mid Tier.
Primary
View
The view of the form that appears when the form is opened.
Page 2106 of 4705
Home
Owner
The name of the user who created the application.
Timestamp
The date and time on which the application was last changed.
Last
Changed
The name of the user who last changed the application.
Lock State
Application
The current production state of the application, for example, Maintenance or Test.
State
Type
The type of application, either local or deployable. Deployable applications use permissions based on roles that are
specific to the application, rather than groups that are specific to the server.
Description
A description of what the application does or other pertinent information.
Packing lists
The following table contains the items listed for packing lists.
Items listed for packing lists
Item
Description
Packing
The name of the packing list.
List Name
Packing
List Label
The label used, if any, for the packing list.
Owner
The name of the user who created the packing list.
Timestamp
The date and time on which the packing list was last changed.
Last
The name of the user who last changed the packing list.
Changed
Lock State
Description
A description of the packing list's function.
Web Services
The following table contains the items listed for web services.
Items listed for web services
Page 2107 of 4705
Home
Item
Description
Web
The name of the web service.
Services
Name
Form
Name
The form used as the access for the web service.
Web
The name that is displayed to users.
Services
Label
Owner
The name of the user who created the web service.
Timestamp
The date and time on which the web service was last changed.
Last
Changed
The name of the user who last changed the web service.
Lock State
Description
A description of the web service's function.
Menus
The following table contains the items listed for menus.
Items listed for menus
Item
Description
Menu
Name
The name of the menu.
Type
The type of menu, either Character, File, Search, SQL, or Data Dictionary.
Refresh
The condition on which the menu is refreshed, either On Connect, On Open, or on 15 Minute Interval.
Timestamp
The date and time on which the menu was last changed.
Owner
The name of the user who created the menu.
Last
Changed
The date and time on which the menu was last changed.
Lock State
Page 2108 of 4705
Home
Groups
The following table contains the items listed for groups.
Items listed for groups
Item
Description
Group ID
The unique ID for the group
Group
The name of the group.
Name
Group
The permission type for the group, either None, View, or Change.
Type
Category
The category of group, either Regular, Computed, or Dynamic.

Regular groups are explicit groups that you create and to which you assign a specific list of users.
Computed groups are explicit groups that you create and to which users are assigned based on a comparison
of users belonging to other explicit groups. For example, you can create a computed group that 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.
Dynamic groups use the contents of special fields to determine group membership.
For more information about groups, see Creating and managing groups.
Flashboard
The following table contains the items listed for Flashboards.
Items listed for Flashboards
Item
Description
Flashboards
A tool for representing data visually from BMC Remedy BMC Remedy AR System forms.
Flashboards
alarms
Tools that enable sending of notifications to specific users based on a threshold value.
Flashboards
Specify the information you want to monitor from a single form. In Flashboards, a variable represents data, such as
variables
a slice of a pie graph, a bar in a bar graph, or a line in a line graph.
Plug-ins
The following table contains the items listed for plug-ins.
Items listed for plug-ins
Item
Description
Plug-in
modules
The names of plug-in modules. Plug-in modules are used with the arplugin process, which is a companion process
to the AR System server. It loads configured plus-in modules to interface with external data.
Plug-in
definitions
Definitions for selected plug-ins.
Roles
Page 2109 of 4705
Home
The following table contains the items listed for roles.

Items listed for roles
Item
Description
Role ID
The unique identifier for this role.
Role Name
The name of the role.
Application
The application to which this role belongs.
Images
The following table contains the items listed for images.
Item
Description
Name
The name of the image.
Type
The type of the image. For example, jpeg, gif, png, etc.
Checksum
This is short data which added to the image for the purpose of detecting errors which may be introduced during its
migration, transmission or storage.
Owner
The name of the user who created the image.
Timestamp
The date and time on which the image was created or changed.
Last
Changed
The name of the user who last updated the image.
Description
A description about the image.
Lock State
The locked state of the image. Locking allows application developers to protect workflow objects that are not
designed for or intended to be customized, by preventing them from being modified or even viewed. An image can
Hidden More restrictive lock that prevents users from viewing details of a locked object, including in BMC
Remedy Migrator differences and dependency reports.
Associations
The following table contains the items listed for associations.
Item
Description
Name
The name of the association.
Enabled
Whether this object is enabled.
Type
The type of association. There are two types of associations which you can create in BMC Remedy Developer
Studio:
Direct associations
Page 2110 of 4705
Home
Item
Description
For more information, see Associations overview.
Primary Schema
The name of the primary form used in the association.
Secondary
The name of the secondary form used in the association.
Schema
Owner
The name of the user who created the association.
Timestamp
The date and time on which the association was created or changed.
Last Changed
The name of the user who last updated the association.
Deleting objects from servers or files

Although you typically delete objects from within Developer Studio before you migrate, you can
delete objects, including locked objects, from servers or files using BMC Remedy Migrator. To
make sure that nothing is affected by the deletion, BMC Remedy Migrator runs a check on the
object that you want to delete.
Note
Locked objects can be deleted only in blocks. Deleting one object that belongs to a locked
group deletes the entire group. Deleting a locked form that is part of a join deletes the join
form.
To delete objects
1. In the right pane of the server or file window, select the objects you want to delete.
BMC Remedy Migrator cannot delete DSO (Distributed Server Option) Map-related forms,
User and Group forms, and BMC Remedy AR System-specific forms, such as the User
Preference form. Also, BMC Remedy Migrator does not support deletion of data in .migrator
forms.
If other objects are affected by the deletion, those objects are listed. If no other objects are
affected, a confirmation message appears.
Deleting objects impact warning message
Page 2111 of 4705
Home
3. Confirm that you want to delete the objects:

Click Yes to delete the specified selection and continue to the next object.
Click No to skip the specified selection.
Click Yes to All to delete all the selected objects.
Click No to All to stop the deletion.
Warning
If you select Yes to All, BMC Remedy Migrator deletes every object without checking the
impact of the deletion on the links to other objects.
Creating a data search

A BMC Remedy Migrator search allows you to create specific search criteria of your data records
for a customized migration.
Note
This option is not available if the source is a file.
Page 2112 of 4705
Home
To create a data search

1. In the Data Migration Settings dialog box under Data Settings, select Search Selection from
the Data Mode list box.
If you supply a number in the Number of Entries text box, only the first number of entries that
match the search are migrated.
2. To create a search, click the list box next to the Search Criteria text box.
Search Criteria dialog box
3. In the Search Criteria dialog box, enter search criteria. Use the following methods to help
build a search:
Click Fields to display a menu for fields, selection values, and keywords.
Select Fields, Selection Values, or Keywords to display submenus with variables that
are specific to the data records you are migrating.
Important
Because BMC Remedy Migrator relies on the API to generate qualification
structures, BMC Remedy Migrator does not support using locale-specific
formatting in qualification strings. The API supports generic formatting such
as dd-mm-yy for dates and number formats without punctuation (such as
15000 instead of 15,000 ). Because of this, do not use spaces,
comma-separated values, or any other locale-specific punctuation when
entering qualifications in BMC Remedy Migrator. For example, when
entering a keyword, be sure that there are no spaces. An entry such as*$
TIMESTAMP$* (with a space between the $ and the T ) causes an error.
Here are some examples of searches you can create:
'Creator' = "Administrator" AND 'License Type' = "Fixed"
In this example, BMC Remedy Migrator searches for entries created by an

administrator user with a fixed license.
'Creator'= "Jane Doe"
Page 2113 of 4705
Home
In this example, BMC Remedy Migrator searches for entries created by the user Jane
Doe.
4. Click OK to use the search, or Cancel to stop it.
Your search criteria appear in the Search Criteria field of the Data Migration Settings dialog
box.
Search criteria for data migration
Using field mappings

The Enable Field Mapping option in the Data Migration Settings dialog box allows you to apply field
mappings to a data migration. When you check the Enable Field Mappings check box, the
Mappings button becomes active. Using this feature, you can map source fields to either a
destination field or a keyword.
You can also save mappings to a file for reuse later, to save time and reduce errors. You can load
the saved mapping file instead of entering the mapping values again. When you save a mapping,
the form name, the server the form resides on, and the data file name are saved.
You can auto-map all fields according to the field ID or the field name used in Developer Studio .
You can remove any of these generated mappings or add mappings.
Keep these conditions in mind when using field mappings:
Field mapping in BMC Remedy Migrator does not work with data files such as .arx files.
BMC Remedy Migrator does not perform any validations on field mappings.
A source field can be mapped only once.
A destination field can be mapped to more than one source field.
To apply field mappings

1. Check the Enable Field Mappings box in the Data Migration Options dialog box.
2. Click the Mappings button.
3. In the Field Mappings dialog box, enter the mappings you want to use for the data migration.
To auto-map field IDs or field names, click the Auto Map IDs or Auto Map Names
buttons.
To add a mapping, click Add Mapping.
Page 2114 of 4705
3.
Home
To delete one or more mappings from the Current Mappings list, select the mappings,
and click Delete. To remove all of the mappings, click Delete All.
To save a mapping, select the mapping and click Save.
To load a mapping you have saved, click Load and select the mapping.
4. Click OK.
Shortcut keys
BMC Remedy Migrator uses special shortcut keys for menu commands and when working in a
server window using the Migrate and Tools menus.
Shortcut keys
Menu
Key sequence
Use to
File menu
Ctrl+N
Open a new server window.
Ctrl+F
Create a new*.migrator* file.
Ctrl+R
Create a new differences window into which you can drag and drop content.
Ctrl+O
Open an existing file or browser window.
Ctrl+P
Print the active document.
Ctrl+S
Save the active file.
Ctrl+C
Copy a selection and put it on the clipboard.
Del
Delete selected objects form a server or file.
Ctrl+V
Paste a selection from the clipboard and put it in an active file.
Migrate menu
Ctrl+M
Migrate selected objects.
Tools menu
Ctrl+D
Show differences.
Ctrl+E
Show downward dependencies.
Ctrl+U
Show upward dependencies.
F5
Refresh the display.
Ctrl+A
Select all choices in Form Detail and Server views.
Edit menu
All
Setting BMC Remedy Migrator options

BMC Remedy Migrator provides various categories of options that enable you to configure how to
process object and data migrations, how to manage differences between source and destination,
how to display migration results, and the directories to use for backup, result, script, and cache files
. The following sections describe each option category.
You can reset any options you have changed back to their default values by clicking the Set Default
button for that set of options.
Page 2115 of 4705
Home
Setting general options

Migration options
Specifying directories to store migration files
Viewing backup, script, and results files
Working with Source Control
Setting general options

Use the General options to change when login prompts occur, when cache refreshes happen, and
whether confirmation prompts should be displayed when performing migrations.
To reset options to their default values, click Set Default.
General options
To select general options

1. Select Tools > Options.
The BMC Remedy Migrator Options dialog box appears.
2. In the BMC Remedy Migrator Options dialog box, select General.
3. Select the following general options:
Page 2116 of 4705
3.
Home
Login/Display Login Dialog Box for Each Server Connection If unchecked, enables
you to log on to multiple servers using a single password. If checked, you must log on
every time you open a server window or whenever a server is referenced. You can
use this option to specify account settings to limit available servers. See Setting-up
BMC Remedy Migrator.
Caching Allows you to cache the local server or update directly from the server.
Refresh object cache and database on type change If checked, refreshes
objects when changing to a different object type (for example, from active links
to filters). Objects in BMC Remedy Migrator are also refreshed when you open
a server and when you press F5 to refresh manually.
Cache server objects locally If checked, refreshes objects locally.
Delete associated dependency and database files for .migrator binary files
when the BMC Remedy Migrator file is closed Provides the option to keep
or delete the database and dependency files that are generated with*.migrator*
binary files. Earlier, these files were always deleted when a .migrator file was
closed, requiring them to be regenerated each time a .migrator file was
reopened. This process can consume up to 40 minutes for the largest*.migrator
* files.
Retaining the database and dependency files eliminates the recaching process
and allows .migrator files to be reopened faster. Because the files are retained
, this option requires additional space on the server where the .migrator files
are stored.
The default value is not to delete the files (option unchecked).
Migration Mode If checked, confirmation prompts are displayed when
performing migrations in Migration mode, or when migrating data entries to the
same form.
4. Click OK.
Migration options
Migration options set how migrations are performed.
Migration options
Page 2117 of 4705
Home
You can select the following migration options:

Multiple-thread Specifies options for using multiple threads during migrations.
Required Objects Specifies whether to migrate required menus, table field forms, join
form members, associations, applications, BMC Remedy Flashboards variable and data
source objects, and forms related to menus and associations.
Backup Specifies which types of objects you want to back up, where to back them up,
and the type of file to back them up as.
Object Removal Provides options for deleting or disabling objects that reside on the
destination server, but not on the source server, during a Form and Related Objects
migration.
Change History--Specifies how BMC Remedy Migrator adds or merges entries in history
fields after each migration.
Groups Specifies how BMC Remedy Migrator merges new groups with existing groups.
Data S pecifies default settings for data migrations. These settings are used as the
default settings in the BMC Remedy Migrator Data Settings dialog box.
Retry Enables you to specify the number of migration retries and the time (in seconds)
between retries. The default number of retries is 3, and the default number of seconds is 300
.
Ignore Prefixes Enables to you specify prefixes that should be ignored during migrations.
Page 2118 of 4705
Home
Masks Enables you to include or exclude objects in a migration or a Differences report.

You can synchronize mask settings so that they are the same for both migrations and
Differences reports.
For each group of options, you can revert to the BMC Remedy Migrator defaults by clicking Set
Default.
Selecting objects to migrate
Using multiple-threads for multiple migration
Backing up destination server
Removing or disabling objects
Setting the change history options
Merging groups
Merging data
Setting migration retry options
Specifying prefixes to ignore
Specifying objects to compare
Selecting objects to migrate

Under Required Object settings, you can specify objects to be migrated automatically. These
options guarantee that all required objects are included in a migration.
With Shared Workflow Settings, you can either merge the list of forms linked to shared workflow
objects on the source server with the list of forms on the destination server, or replace the list of
associated forms on the destination server with the list on the source server.
To select Required Object options

2. In the BMC Remedy Migrator Options dialog box, select Migration > Required Objects.
Required Objects options
Page 2119 of 4705
Home
3. Leave the option settings for the following objects at their default values of Yes to have them
migrated automatically:
Menus
Table field forms
Join form members
BMC Remedy Flashboards variables
Flashboard data sources
Associations
Forms related to menus
Forms required by applications
Forms related to associations
4. To require migration of forms required by applications, select Yes for the Migrate Forms
Required by Applications option. If you are migrating data for a form that the application
does not own, the Yes setting ensures that the required form for the data is migrated to the
destination. If this option is set to No and you are migrating data for a form that the
application does not own, BMC Remedy Migrator creates a special data-only form as a
placeholder for the data so that it can be migrated successfully. See Migrating applications.
5. To require migration of the state of an application, select Yes for Migrate Application States.
This property defines the application state (Maintenance, Production, or Test). It applies to
deployable applications only. For more information about application states, see Working
with deployable application states.
6. Select Yes or No for Merge Shared Workflow, depending on how you want to handle shared
workflow objects:
Page 2120 of 4705
6.
Home
Yes The list of s hared workflow forms associated with the object on the source
server mergeswith the list of shared workflow forms on the destination object.
No (default) The list of shared workflow forms associated with the object on the
source server replaces the list of shared workflow forms on the destination object.
7. Click OK.
Using multiple-threads for multiple migration

Using the Multiple-thread options, you can select whether to use multiple threads for multiple
migrations. The term thread refers to operating system functionality, allowing programs to break up
into two or more independent work units for concurrent execution. Multiple threads allow the
execution of other tasks while a migration is in progress, or to do multiple migrations concurrently. If
you do not use multiple threads, you can run only one migration at a time. The default setting is
multiple threads and execution of up to 10 migrations at a time. The optimal number of migrations
to select depends on your hardware configuration.
For more information about working with threads, see AR System server threads.
To select Multiple-thread options

2. Under Category, open the Migration list and select Multiple-thread.
Multiple-thread options
Page 2121 of 4705
Home
3. Select Use Multiple Threads for Migrations to execute more than one migration at a time;
select Do Not Use Multiple Threads for Migrations to limit migrations to one at a time.
4. Enter the number of migrations you want BMC Remedy Migrator to execute.
If you execute more migrations than the threads you have specified, the extra migrations are
queued until a thread becomes available.
5. Click OK.
6. Restart your computer for the multi-thread option changes to take effect.
Backing up destination server

Backup options enable you to back up the destination server before a migration occurs. As a
safeguard, BMC Remedy Migrator copies the objects to be changed on the destination server to a
backup directory before migration by default. (Only destination servers are backed up.)
You can view backup files from a server or file window by selecting Backup Files in the left pane
and viewing the files in the right pane.
Note
BMC Remedy Migrator does not back up data for restored fields. Also, BMC Remedy
Migrator does not support backups of BMC Remedy Flashboards or plug-ins to definition (
.def ) files. These objects can be backed up using . migrator files.
Page 2122 of 4705
Home
To select Backup options

2. Under Category, select Migration > Backup.
Backup options
3. In the Backup the following objects area, select a backup option:

Back up all objects (default) all objects are backed up.
Back up specified objects A list of objects appears. The default selection is Yes for
each object. If you do not want to back up an object, click the object name and select
No from the drop-down list for that object.
Disable all BMC Remedy Migrator does not perform any backups.
4. In the Backup Root Directory section, select a location to store your backup files, or accept
the default BMC Remedy Migrator backup directory shown.
By using the BMC Remedy Migrator backup directory, you can access backup files
conveniently by clicking Backup Files in the left pane of the server window.
5. In the Backup File Type region, select the type of file you want your objects backed up as.
Note
Make sure you have enough space on your computer for the backup files.
Page 2123 of 4705
Home
Select a file format:

Migrator (*.migrator ) default setting
Definition (*.def )
Both Migrator files and definition (* .migrator and *.def )
6. Click OK.
Removing or disabling objects

Object Removal options enable you to delete or disable objects from a Form and Related migration.
Objects that can be disabled:
Active links
Escalations
Filters
Objects that can be deleted:
Active links
Escalations
Filters
Filter guides
Active link guides
Web services
BMC Remedy Migrator deletes or disables objects only on the destination server as part of a Forms
and Related migration. For example, if you migrate Form 1 from Server A to Server B, BMC
Remedy Migrator deletes or disables Active Link x and Filter x from Server B.
Note
Object Removal options do not apply to locked workflow.
Migration object removal example
Page 2124 of 4705
Home
During a Forms and Related Objects migration, any objects related to a form that exist on the
destination but not on the source can be deleted, disabled, or ignored on the destination when the
migration takes place. If you specify that objects on the source should be deleted, BMC Remedy
Migrator backs up those objects before deleting them (see Backing up destination server).
Note
Forms are never deleted during migrations.
The default setting for these options is to disable all objects.
To select Object Removal options

2. Under Category, select Migration > Object Removal.
Object Removal options
Page 2125 of 4705
Home
3. In the Delete or Disable Objects section, select how BMC Remedy Migrator should handle
objects on the destination during a Form and Related Objects migration:
Ignore All Objects BMC Remedy Migrator ignores all objects on the destination
server.
Disable All Objects (default) BMC Remedy Migrator disables all objects. The
objects remain on the server disabled.
Disable Specified Objects
When Disable Objects is selected, BMC Remedy Migrator disables the active
links, escalations, or filters related to the selected objects.
When Delete Objects is selected, BMC Remedy Migrator deletes the active
links, escalations, filters, filter guides, active link guides and web services
related to the selected objects.
4. Click OK.
Setting the change history options

With the Change History options, you can modify, merge, or append an BMC Remedy AR System
Change History. The change history of an object includes the owner of the object, who last modified
it, and the date it was modified.
Note
Page 2126 of 4705
Home
Change History merging works only when the difference mask for the workflow property is
enabled in the Options dialog box, and when the change history options have also been
configured.
To select Change History options

2. Select Migration > Change History.
3. In the Change History Merge Options area (the following figure), select how BMC Remedy
Migrator should merge or add entries to the change history after each migration:
Do not modify Change History (default)--the existing change history on the source is
not migrated to the destination.
Merge Change History
Append string to Change History--enables you to enter some text, such as a
description of the change history.
Merge Change History and append a string--the String field becomes enabled, and
you can enter some text, such as a description of the merge.
4. Click OK.
Change History options
Page 2127 of 4705
Home
Merging groups
Group options enable you to select how BMC Remedy Migrator should merge new groups with
existing groups. BMC Remedy AR System defines several special groups that cannot be created
using the Group option, including public, administrator, subadministrator, customize, submitter,
assignee, and assignee group.
Note
Groups are migrated by group ID, not by group name.
To select Group options

2. Under Category, select Migration > Groups.
3. In the Group Merging options area (the following figure), select how BMC Remedy Migrator
should merge new groups with existing groups:
Reject Duplicate Groups BMC Remedy Migrator generates an error for groups with
existing request IDs.
Generate New ID for All Groups BMC Remedy Migrator creates a new request ID
for all groups.
Replace Old Group with New Group BMC Remedy Migrator replaces old group
information with new group information.
Update Old Group with New Group's Data BMC Remedy Migrator merges old
group information with new group information.
Group options
Page 2128 of 4705
Home
4. For each group merging option, select either or both settings:

Ignore Required Fields
Ignore Pattern Checking
5. Click OK.
Merging data
Data options enable you to select how BMC Remedy Migrator should merge new data with existing
data. "Data" is defined as the entries within forms.
To select Data options

2. Select Migration > Data.
3. In the Data Merging options area (the following figure), select how BMC Remedy Migrator
should merge new data with existing data:
Reject Duplicate Records BMC Remedy Migrator generates an error for records
with existing request IDs.
Generate New ID for All Records BMC Remedy Migrator creates a new request ID
for all records.
Note
This option is not supported for migrations in which the destination is a file.
Page 2129 of 4705
Home
Replace Old Record with New Record BMC Remedy Migrator replaces old record
information with new record information.
Update Old Record with New Record's Data BMC Remedy Migrator merges old
record information with new record information.
Data options
4. For each data merging option, select one or both settings:

Ignore Required Fields
Ignore Pattern Checking
5. In the Default Data Migration Mode section, select which data records to migrate:
Do not migrate any records.
Migrate all records.
Migrate query selection.
Migrate first numberOfRecords records.
6. Click OK.
Note
The Related Workflow options section is available only when the destination is a server;
not available if the destination is a migrator file.
Page 2130 of 4705
Home
Setting migration retry options

Retry options enable you to specify if BMC Remedy Migrator should stop a migration and attempt
recovery if the server crashes, is stopped by another user, or becomes too busy to return results.
Earlier, BMC Remedy Migrator would continue to migrate all objects even when the server stopped
functioning.
You can also specify the number of retries and the time (in seconds) between retries. The default
number of tries is 3, and the default wait time is 300 seconds.
To set retry options

2. Select Migration > Retry Options.
3. In the Number of Times to Retry (the following figure), enter a number, or accept the default
value of 3. If you want no retries, enter 0.
4. In the Seconds to Wait Between Retries, enter a number, or accept the default of 300
seconds.
5. Click OK.
Retry options
Page 2131 of 4705
Home
Specifying prefixes to ignore

This option enables you to instruct BMC Remedy Migrator to bypass workflow objects that begin
with specific prefixes during a direct or a scripted migration.
All BMC Remedy Migrator installations include a default list of prefixes in the Ignore Prefixes dialog
box. You can add new prefix names, edit existing prefix names, or clear the list. A Set Defaults
button is available to restore the default prefix list at any time.
The default prefixes include those required to allow correct migration of CMDB, BMC Remedy
Approval Server, and SLA/SLM applications. They are:
AP
OBJSTR
RE
BMC
SLA
zSLAGen
Ignore Prefix can be applied to all workflow objects except these:
Data
Roles
Groups and Computed Groups
Fields
Views
Prefixes ignored in Results report

When a migration is completed, the Results report lists the prefixes that were ignored. The status
information for workflow objects ignored during a migration notes these objects as ignored.
To specify prefixes to be ignored

2. Select Migration > Ignore Prefix (the following figure).
3. Perform any of the following actions:
To add a prefix to the list, click Add, and enter the prefix name.
To remove a prefix from the list, select the prefix, and click Remove.
To edit the name of an existing prefix, select the prefix from the list, click Edit, and
make the needed changes.
4. Click OK.
Ignore Prefix option
Page 2132 of 4705
Home
Specifying objects to compare

Migration mask options enable you to specify exactly which objects to compare between source
and destination before a migration and what should be migrated if an object already exists.
You can also synchronize migration mask options with the mask options for Differences reports, so
that the settings are the same for both types of options. The Synchronize button provides a
convenient way to create an exact match between the migration and Differences report mask
options.
To set migration mask options

1. Select Tools > Options, and select Migration.
2. Select Masks.
3. Click in the field for the type of object for which you want to set options (the following figure),
and select the option from the drop-down list.
4. To synchronize the migration mask options with those for the Differences report, click
Synchronize Difference Masks.
For more information about Differences report mask options, see Mask options.
5. Click OK.
Page 2133 of 4705
Home
Migration mask options
Specifying directories to store migration files

Directory options enable you to specify the directories in which backup, migration result, script, and
cache files are stored. Even when the directory path or name is changed, BMC Remedy Migrator
locates all the appropriate files for a specific server.
To select directory options

2. Under Categories, select Directories.
When you are using BMC Remedy Migrator for the first time, the default directory paths are
shown. You can keep these default selections, or change them.
3. To change the directory path for a file type, click the button to the right of the directory path
field, and enter a new path.
4. Click OK.
Viewing backup, script, and results files

You can view the BMC Remedy Migrator files on different servers regardless of the directory
options setting.
To view your files

1. Click the server window associated with the backup, result, or script file you want to view.
2.
Page 2134 of 4705
Home
2. In the left pane of either the Object Type or Prefix view, click either Backup Files, Script Files
, or Result Files.
Viewing backup, script, or result files
The files are listed in the right pane. For each file, the list shows the name (including the date and
time of the migration) and the migration status.
To open a file, double-click the file name.
Working with Source Control

BMC Remedy Migrator Source Control (SC) functions in the same way that the BMC Remedy AR
System SC functions, except that BMC Remedy Migrator can generate differences reports between
objects under SC. If SC is enabled BMC Remedy AR System (Enforced mode enabled), BMC
Remedy Migrator can also enable SC. See Configuring AR System servers and Setting version
control options.
Note
You can use Source Control with BMC Remedy Migrator only when the AR System server
is integrated with a third party source control system, by using the BMC Remedy
Administrator tool.
SC is a standard that was developed for tools to interface to Source Control systems (such as
Microsoft Visual SourceSafe, PVCS, CM Synergy, and so on). BMC Remedy Migrator provides an
interface to the SC system so it can "talk" to these tools. This allows you to save your work with
version numbers and checkin and checkout capability. The checkin and checkout capability lets
teams share an application without overwriting each other's work.
In this topic:
Page 2135 of 4705
Home
Starting SC in BMC Remedy Migrator

To start and use SC in BMC Remedy Migrator
Using SC in BMC Remedy Migrator
BMC Remedy Migrator migrates an object and replaces it within the Source Control system if:
The object is checked in to SC.
The object is checked out by the same user who is performing the migration.
If the object is checked out by a user other than the user who is performing the migration, the object
is not migrated.
Because SC migration is multi-byte, all Unicode items are converted to multi-byte and back when
working with SC.
Starting SC in BMC Remedy Migrator

SC integration in BMC Remedy Migrator is essentially the same as that in BMC Remedy AR
System. The one exception is that BMC Remedy Migrator can compare the differences between
SC objects using the BMC Remedy Migrator differences report.
BMC Remedy Migrator SC Options
To generate a differences report for SC, select Tools > Source Control > Show Differences. For
information about working with differences reports, see Migrating applications and data between AR
System servers
Note
Groups, Data, DSO Maps, Fields, and Views cannot be added to SC.
Page 2136 of 4705
Home
To start and use SC in BMC Remedy Migrator

1. Verify that you have SC enabled BMC Remedy AR System for a particular server by viewing
the server window to see if SC columns are displayed.
2. Select Tools > Source Control to display the BMC Remedy Migrator SC options, or use the
Source Control toolbar.
Using SC in BMC Remedy Migrator

The BMC Remedy Migrator SC menu and toolbar buttons enable you to perform standard SC
functions. You can also check out objects, convert them from a*.def* file to a .migrator file, and
generate a differences report. The SC login box requests your name and password only when you
log on for the first time.
To verify that BMC Remedy Migrator integrates to your Source Control systems application, view a
window within BMC Remedy Migrator. If SC is functioning, the following columns appear in the
BMC Remedy Migrator Server, Form Detail, and Script windows.
Source control information in BMC Remedy Migrator windows
Column heading
Description
In SC
Verifies if the object is in SC. This heading only appears in a SC window.
Checked Out By User
States who has the object checked out.
SC Last Modified By
States who last modified the object.
SC Timestamp
States when an object was last accessed.
If you see a check mark over an object's icon, that object has been checked out. BMC Remedy
Migrator remembers column settings for the next viewing (see Rearranging window columns).
The following table lists and describes the functions available from the BMC Remedy Migrator SC
toolbar.
Source control icons in BMC Remedy Migrator SC toolbar
BMC
Remedy
Migrator
SC icon
Description
Get Latest
Version
Retrieves the latest definition file for the object being checked into SC and imports it to a server. When you "get" an
object, you are retrieving a copy. The file is not locked from other system administrators.
Page 2137 of 4705
Home
Check In
Checks the file back into SC. If Enforced mode is enabled in BMC Remedy AR System and you check in an object,
the file is no longer locked and other system administrators can use it or modify it. If Enforced mode is disabled,
more than one user can check in an object at the same time.
Check Out
Checks a file out of SC. If Enforced mode is enabled in BMC Remedy AR System and you check out an object, the
file is locked and no other system administrator can modify it. If Enforced mode is disabled, more than one user can
check out an object at the same time.
Undo
Overrides objects that have been checked out by someone else. You must have a working folder set in your SC
Check Out
client for this command to work properly. The file is no longer locked and the earlier version is retained in the SC
project.
Add to
Source
Control
Adds the objects to the SC database. The file is archived in the SC project.
Remove
from
Source
Control
Removes the objects from SC.
Note
Removing files from SC does not remove them from the server.
Show
Shows the history of objects selected in the SC integration. History reports summarize information about revisions of
History
the objects.
Show
Differences
Checks out objects, converts them to a . migrator file, and generates a differences report. See Migrating
User
Information
Displays user information about administrators of the SC database.
Refresh
Status
Refreshes the current status information of an object from the SC database.
applications and data between AR System servers
Page 2138 of 4705
Home
Run
Source
Runs the SC system client.
Control
Client
Performing migrations
BMC Remedy Migrator is fully Unicode capable. BMC Remedy Migrator allows migration of objects
and data between non-Unicode and Unicode servers. BMC Remedy Migrator does not have to be
executed on the same locale as a non-Unicode server.
Definition (.def ) files with multiple character encodings can be migrated as long as each block
within the .def file contains the character encoding used at the beginning of the block. If that line is
missing, the migration must be executed on a server of the same locale that was used to create the
.def file.
This section describes how to migrate objects, fields, and data. It also includes procedures on how
to run and clear migrations, and how to perform Copy/Prefix migrations.
Migration checklist
Managing migrations
Migrating objects between servers or files
Migrating applications
Migrating a form view and its associated fields
Migrating fields
Migrating data
Migrating objects to the same server
Migrating differing objects
Migrating dependent objects from a Dependency report
Migrating overlay objects and custom objects
Migrating using command-line interface
Migration checklist
Before you begin a migration, verify the following information:
Are you licensed and logged on to all of the servers you want to migrate to and from?
See Migrating applications and data between AR System servers for more information.
Page 2139 of 4705
Home
Do you want to restrict users from accessing a destination server that is involved in a
migration? (In BMC Remedy Migrator, Administrator mode is set to*on* by default.) If yes:
Select the production server window and select the Migrate menu.
Select Set Admin Mode on Destination Server to turn it on (check) and select it again
to turn it off (uncheck). If Set Admin Mode on the destination server is selected, BMC
Remedy Migrator enables the Administrator-Only mode on the destination server (if
your server supports it) during a migration, and turns it off when the migration is
complete.
Did you set up your migration and report options in the Tools menu? See Setting BMC
Remedy Migrator options for setting up migration options and Chapters 8 through 10 for
setting up report options.
If Enforced mode is enabled on the destination server, are all the objects on the
destination server checked into Source Control? BMC Remedy Migrator does not
change objects on a destination server if Enforced mode is enabled in BMC Remedy AR
System and the object is checked out by another user. For more information about the use
of source control in BMC Remedy AR System, see Setting version control options.
Do you want to review object dependencies or view object differences before you
start migrating? See Migrating applications and data between AR System servers and
Have you verified or added any prefixes for workflow items that should be ignored
during the migration process? See Setting BMC Remedy Migrator options.
Managing migrations
Use the migration status pane to view active or completed migrations, and monitor and control
migration activity. Use the migration status tabs to select and view migration activity and statistics.
See Migration status panes and Migration status tabs.
To control migrations from the migration status pane, click a status tab and then right-click a status
line to open a menu with the following options:
Start Starts a scheduled migration (before its scheduled time).
Restart Restarts an interrupted or stopped migration (starting from the point of interruption
and going forward).
Stop Stops any type of migration.
Delete Deletes an interrupted, stopped, scheduled, or completed migration, along with the
migration result files.
Migrating objects between servers or files

You can migrate objects between servers, between a server and a file, or between files.
Important
Page 2140 of 4705
Home
If you have migrated hierarchical groups (groups that include both parent and child
groups), the Differences report might show a difference between source and
destination. This could be because a child group was migrated but not its parent.
To resolve this difference, migrate both parent and child groups.
You cannot compare association object in BMC Remedy Migrator.
You cannot migrate your association object from .migrator or .def file to a server
and from a server to a .migrator or .def file.
1. Open windows for your source and destination.

To open a window for a server, select File > New Server Window, and select a server.
To open a window for a file, select File > Open, and select a file.
2. Click in the source window.
3. Select Migrate > Migration Mode.
4. From the Migrate menu, select the type of object migration to perform:
All BMC Remedy AR System Objects Migrate all objects listed in the source
window.
Form and Related Objects Migrate a form and all of its related objects.
Deploy Application Migrate an application and all of its objects to the same server.
See Migrating applications
Selected Objects Migrate only the objects selected in the source window.
5. From the Destination Type dialog box, select the destination type by clicking Server or
Migrator File.
If you select Server, select a destination server and enter your user name and
password.
The source server is always the server window that is active at the time of the
migration. To review object differences on the same server, select the same
destination server as your source, and then add a prefix when prompted by the Prefix
dialog box.
If you select Migrator File, enter the file destination path, type a file name, and click
Save. The migration is saved as a .migrator file.
6. If you are prompted to proceed with the migration, select Yes.
7. To view the progress and results of your migration, open the Migration Status pane by
choosing View > Migration Status if it is not already open.
Select the All tab to see the progress of the migration; select the Completed tab to
see a list of completed migrations.
To view a results report for a completed migration, double-click the migration in the
Completed tab. For more information about results reports, see Migration Result
reports.
Page 2141 of 4705
Home
You can migrate an application to another server, to the same server, between a server and a file,
or between files using two methods:
By migrating it as a selected object (Migrate > Selected Object).
By deploying it (Migrate > Deploy Application). This method migrates the application and all
of its supporting files.

Migrating an application as a selected object
Deploying an application
Migrating an application as a selected object

1. Open the server or file window that includes the application you want to migrate.
2. In the right pane, select the application.
3. Select Migrate > Selected Objects.
4. From the cascading menu, select Select Destination.
Note
You can also select any server or file listed in the cascading menu.
5. In the Destination Type dialog box, select Server or Migrator File.

If you select Server, select a destination server and, if necessary, enter your BMC
Remedy AR System user name and password.
If you select Migrator file, enter the name of the .migrator file to serve as the
destination.
If you are prompted to proceed with the migration, select Yes.
6.
Page 2142 of 4705
Home
6. To view the progress and results of the migration, open the Migration Status pane by
choosing View > Migration Status.
Deploying an application
When you deploy an application, BMC Remedy Migrator migrates the application and all of its
supporting objects to the destination.
Migrating application data to a file without a corresponding form

When creating an application using BMC Remedy Developer Studio, you can specify the data to be
exported when the application is deployed. This information is shown in the Data tab in the Modify
Application dialog box.
In BMC Remedy Migrator, when you deploy an application that contains data for forms that the
application does not own, those forms are not automatically migrated. However, BMC Remedy
Migrator provides an option to migrate forms required by applications at deployment. When this
option is set to Yes, the forms required by the application are included with the data in the migration
.
Required Objects option: Migrate Fields Required by Applications
If this option is set to No when you deploy an application that contains data for forms that the
application does not own, BMC Remedy Migrator creates a special data-only form to receive the
data being migrated. In the Object List window, this form is listed as a data-only form with a
different icon than that of a regular form or a display-only form.
Data-only form
Page 2143 of 4705
Home
During the migration, the data in this form is migrated, but not the form itself.
For more information about required objects options in BMC Remedy Migrator, see Selecting
objects to migrate.
Deploying an application to the same server

If you have an BMC Remedy AR System 6.0 or later server, you can deploy an application to the
same server as a copy/prefix migration. See Migrating objects to the same server.
To deploy an application
1. Open the server or file window that includes the application to deploy.
2. In the right pane of the window, select the application.
3. Select Migrate > Deploy Application.
4. From the cascading menu, select Select Destination.
Note
You can also select any server or file listed in the cascading menu.
5. In the Destination Type dialog box, select Server or Migrator File.

If you select Server, select a destination server and, if necessary, enter your BMC Remedy
AR System user name and password.
If you select Migrator file, enter the name of the .migrator file to serve as the destination.
If you are prompted to proceed with the migration, select Yes.
6. To view the progress and results of your migration, open the Migration Status pane by
choosing View > Migration Status if it is not already open.
Migrating a form view and its associated fields

You can select a view of a form and its fields, and the display properties associated with that view
instead of having to select all the fields and views for the form.
Page 2144 of 4705
Home
When a field is added to view overlay by using the Add Field To View Overlay menu item, a field
ID is assigned to it. When a view is selected for migration, BMC Remedy Migrator searches for all
of the fields with display properties for that view. BMC Remedy Migrator then migrates that view
and its associated fields to the destination form. It checks each field on the destination form and
takes the appropriate action:
If the field exists on the destination, BMC Remedy Migrator extracts the display properties
from the destination field for all views except the view being migrated.
It merges these display properties into the source field and compares the properties of the
source field with those of the destination field.
If the field does not exist on the destination, BMC Remedy Migrator recreates the field, and
verifies that the field includes only the display properties of the field being migrated.
Finally, BMC Remedy Migrator creates or modifies the field on the destination by using the
new merged source field.
If the field exists on the destination, BMC Remedy Migrator extracts from the destination field
the display properties for all views except the view being migrated.
This process is repeated for each field in the view. BMC Remedy Migrator migrates any new values
for the object properties in a view overlay form. All types of migration is supported for a view
overlay form.
Note
BMC Remedy Migrator does not remove field and view overlays from the destination
server after migration, even if you remove the field and view overlays from the source
server.
To migrate a form view and its fields

1. In the BMC Remedy Migrator main window, select the form whose view you want to migrate.
2. Right-click on the form name and select Form Details.
3. From the left panel, select Views.
4. Select the view you want to migrate.
5. Select Migrate > Selected View with Fields > Select Destination .
6. Select a form and click OK.
7. Click Yes in to confirm the migration.
Related topics
Adding a field to a view overlay
Page 2145 of 4705
Home
Migrating fields
You can use BMC Remedy Migrator to migrate fields from one BMC Remedy BMC Remedy AR
System form to another. By migrating lower-level fields or field-level objects from one form to
another, you can update forms at a more basic level. For example, you can migrate a Middle Name
field to a form with only first and last name fields.
To migrate fields
1. Open windows for the source and destination.
3. In the left pane of the source window under BMC Remedy AR System Objects, click Forms.
4. In the right pane of the source window, select the form that includes the fields you want to
migrate.
5. Click View > Form Details, or double-click the form name to open a Form Detail window for
the form.
The right pane lists the fields for the selected form.
Migrating fields
6. Perform one of the following actions:

To migrate all fields, select Migrate > All Fields, or Migrate > All Views.
To migrate fields of a specific type, select Migrate > Migrate Field by Type.
To migrate one or more fields, select the fields in the right pane. Use Shift-Click or
Ctrl-Click to select multiple fields. Then, right-click and select Migrate Selected Fields
from the pop-up menu.
7. From the Destination Type dialog box, select Server or Migrator File.
Page 2146 of 4705
Home
If you select Server, select a destination server and enter your BMC Remedy AR
System user name and password. You are prompted to select a destination form.
The source server is always the server window you have activated at the time of the
migration. To review object differences on the same server, select the same
destination server as your source, and then define a prefix. For the prefix, use a short
string, such as prod.
If you select Migrator File, select the .migrator file to which the field should be
migrated. A list of forms in the .migrator file is displayed. If the file has no forms in it,
you cannot migrate the field to that file.
9. To view migration progress and results, open the Migration Status pane by choosing View >
Migration Status.
Select the All tab to see the progress of the migration.
Select the Completed tab to see a list of completed migrations.
To view a results report for a completed migration, double-click the migration in the
Completed tab. See Migration Result reports
Migrating data
You can migrate data entries associated with a form from one server to another, between a server
and a file, or between files. For example, you can migrate data entries from a production server to a
development server for testing newly designed applications with actual data. Or, you can migrate
data from one file to another. Data is migrated individually or in a batch.
Note
If you stop and then restart a migration in progress, BMC Remedy Migrator restarts the
migration from the entry that was last migrated successfully.
By default, BMC Remedy Migrator uses the field IDs to map field values between the two forms you
select. You can migrate four types of data:
Individual entries
All entries
Searched entries
"X" number of entries
Note
Data Migration options are not available for Display Only forms.
Page 2147 of 4705
Home
Migrating ITSM, SLA, and CMDB data

BMC Remedy Migrator does not take the place of the current ITSM/SLA/CMDB installation
processes, because it cannot execute the meta workflow used to generate workflow required by the
client. BMC Remedy Migrator allows you to safely move generated workflow from the system on
which it was created to a production system without taking the meta workflow with it.
Note
All users must have administrator privileges to use BMC Remedy Migrator. When
migrating ITSM/SLA/CMDB application-related data, you must first verify that they are a
member of the required group or groups, in order for the data to be migrated correctly.

Migrating individual entries in a form
Migrating data entries
Migrating individual entries in a form

Perform the following steps to migrate individual data entries in a form.
To migrate individual entries in a form

1. Open a server window or a file containing the data entries you want to migrate.
2. Select Migrate > Migration Mode or Scripting Mode.
3. In both the source and destination windows, perform the following tasks:
a. In the right pane, select the form that is the source or destination for the data
migration.
b. Select View > Form Details to open the Forms Detail window:
4. Scroll to the bottom of the left pane of the source Form Detail window and click Data.
The right pane displays the data for the fields in the form.
Note
The columns displayed in the right pane for the form data are defined by the
settings in the Form Properties dialog box in BMC Remedy Developer Studio. The
Results List Fields tab specifies the fields to be displayed in results lists. If no fields
are specified, BMC Remedy Migrator uses the defaults for the form (field IDs 1 and
8). For example, in the Group form, Request ID and Long Group Name (fields 1
and 8) are displayed. To display additional fields, use BMC Remedy Developer
Studio to enter those fields. See Setting form properties.
Page 2148 of 4705
Home
The advanced search bar appears at the bottom of the Form Detail window, allowing you to
search for data to include in the migration.
5. Do either of the following actions in the advanced search bar:
To find specific data, enter criteria in the Search Criteria field, and click Apply. The
matching entries are listed in the Form Detail window.
To include all data, leave the Search Criteria field blank.
6. Select the data to migrate:
To migrate only the data found in your search, select the records from the source
Form Detail window and drag and drop them into the destination Form Detail window.
To migrate all the data from a specific form, first select the data in the right pane of
the source Form Detail window. To select all the data records, highlight the first data
record, hold down the Shift key, and then highlight the last data record.
7. Right-click in the right pane of the Form Detail window and select Migrate Selected Entries.
If you are migrating to a server, select the destination server in the Server dialog box.
If you are migrating to a file, enter or select a .migrator file name.
8. Select the destination form in the Form List dialog box.
Migrating data entries

Perform the following steps to migrate forms, data and related objects.
To migrate data entries

1. Open the windows that you want as the source and destination for the data you are
migrating.
2. Select Migrate > Migration Mode or Scripting Mode.
3. Select Migrate > Form Data, then select one of the following options:
Form Data Only--Only the entries within the form are migrated.
Form and Data--Both the form and the entries within the form are migrated.
Form, Related Objects, and Data--Both the form and the entries within the form are
migrated, along with all related objects.
If you are migrating forms and data to the same server, the Prefix dialog box appears.
Enter a prefix.
The
Data Migration Settings dialog box appears.
Data Migration Settings dialog box
Page 2149 of 4705
Home
The migration is listed at the top of the dialog box with the following information:
Source Name--The name of the server or file from which the data is being migrated. If
the source is a file, the complete file path is shown. A green check mark or a red X
through the icon indicates whether the migration instructions are valid.
Source Form--The name of the form that includes the data being migrated.
Destination Name--The name of the server or . migrator file to which the data is
being migrated. If the destination is a file, the complete file path is shown.
Destination Form--The name of the BMC Remedy AR System form on the destination
to which the data applies.
Object Settings--The objects to be included in the migration, based on what you
selected in step 3.
Data Mode--The specific data to be migrated. The setting shown is based on the
default value set in your migration options.
Ignore pattern checking (yes/no)--Whether pattern checking should be ignored.
Ignore required fields (yes/no)--whether required fields should be ignored.
Num Entries--The number of entries being migrated.
Search criteria--Any search criteria specified for this migration. If you did not specify
any search criteria, this column is blank.
The Source and Destination areas show the names of the source and destination
servers or files, and forms. For example, if you are migrating between two files, the
source and destination file paths are shown.
Page 2150 of 4705
Home
Source and Destination information for data migration
4. Select the migration to highlight it.

Selected migration in Data Migration Settings dialog box
Note
If your migration has any invalid instructions, the icon at the left of the server name
has a red cross (X) through it, and a message appears in the lower-left area of the
Data Migration Settings dialog box. You must make sure that all migration
instructions are valid before you can continue.
5. In the Object Settings region, select a setting for the objects to be migrated:
Form Only--Migrates only forms.
Form and Related--Migrates forms and related objects.
Form Data Only--Migrates only form data entries.
Form and Data--Migrates forms and data entries.
Form, Related and Data--Migrates forms, related objects, and data entries.
6. In the Data Settings region, select a data mode. The default selection shown corresponds
with the Data settings in your migration options. For more information about setting migration
options, see Setting BMC Remedy Migrator options. Accept the selection shown, or select
another selection:
No Data --No data entries are migrated. You can set the default setting for this mode
by choosing Tools > Options, expanding the Migration tree in the left pane, and then
selecting Data from the same tree.
All Entries--All entries are migrated according to your selections and settings.
Search Selection--Entries are migrated based on search criteria you specify. If the
source is a file, this selection is not available. For information about creating a search,
see Migrating objects to the same server.
Number of Entries--Number of entries that are migrated, starting from the newest to
the oldest.
7.
Page 2151 of 4705
Home
7. Select a data merging option. The default selection shown is based on the Data settings in
your migration options. For more information about setting migration options, see Setting
BMC Remedy Migrator options. Either accept the selection shown, or select another
selection:
Reject Duplicate Entries--BMC Remedy Migrator generates an error for entries with
existing request IDs.
Generate New ID for All Entries--BMC Remedy Migrator creates a new request ID for
all entries. If the destination is a file, this selection is not available.
Replace Old Entry with New Entry--BMC Remedy Migrator replaces old entry
information with new entry information.
Update Old Entry with New Entry's Data--BMC Remedy Migrator merges old entry
information with new entry information.
8. For each data merging option selected, check the appropriate check boxes to enable the
following options:
Ignore required fields
Ignore pattern checking
9. Select a default migration mode:
Do not migrate any records
Migrate all records
Migrate query selection
Migrate the first numberOfRecords records
10. Select server connection options:
Use List and Fast Server Threads --By default, BMC Remedy Migrator uses Fast and
List server threads as an alternative to the standard Admin thread. The default setting
for the Fast Thread Port is 390620; the default setting for the List Thread Port is
390635. To change these settings, enter different values. To disable Fast and List
Treads and use the Admin thread, uncheck the box.
11. Check the Disable Related Workflow check box to have BMC Remedy Migrator disable
related workflow during the data migration. The workflow is enabled after the migration is
complete.
12. Check the Enable Field Mappings box to apply field mappings for the data migration. See
Migrating applications and data between AR System servers .
13. Perform one of the following actions:
Select Apply, then OK, to begin the data migration.
Note
The OK button is disabled until all the migration instructions are valid in the
Data Migrations Settings dialog box.
Click Cancel to stop the data migration.

14. If you are asked if you want to start the migration, select Yes.
15.
Page 2152 of 4705
Home
15. To view migration progress and results, open the Migration Status Pane window and click
the All and Completed tabs. Then, double-click the migration you want to check.
Migrating objects to the same server

When migrating objects to the same server, you must change the object's prefix so that the objects
have unique names. This is called a Copy-Prefix migration.
Note
When migrating an application to the same BMC Remedy AR System 6.0 or later server,
you might notice that BMC Remedy Migrator does not automatically deploy a prefixed
version of the application. This is because the prefix is applied only to the application
name, not its objects. As a result, you might see an error message stating that the server
cannot create the application because its objects are already owned by the non-prefixed
application. To migrate the application to the same server, select Migrate > Deploy
Application, and select the same server as the destination. This ensures that the prefixed
version of the application is created and that it has referenced objects that are also
migrated.
Also, when a role is migrated to the same server without an application, a prefixed
application name is assigned to the role, but the role name is not prefixed.
To perform Copy/Prefix object migrations

1. Open the window containing the objects you want to copy or migrate.
2. Select the objects you want to migrate.
3. In the Destination Type dialog box, select Server, then select the same server.
Tip
Dragging and then releasing an object within the same server window, or
performing a copy and paste action, also opens the Prefix dialog box.
4.
Page 2153 of 4705
Home
4. In the Prefix dialog box, perform one of the following tasks:

Prefix dialog box
\
Click Add Prefix, then type the new prefix.
Click Replace First [HTMLUATarsadministeringmigrating: n ] Characters with New
Prefix, type a number, and then type a new prefix.
Click Remove Old Prefix, then type the old prefix.
Click Replace Old Prefix with New Prefix, type in the old prefix, and then type the new
prefix. For the prefix, use a short string (5 or fewer characters).
5. Click OK.
To view the progress and results of your migration, select View > Migration Status.
Note
When viewing the status of a Copy/Prefix migration, the prefix does not appear with
the server name.
Migrating differing objects

When migrating objects in a Differences report, only those objects that differ between the source
and the destination, or that are missing on the destination, are migrated.
To migrate differing objects

2. From the Migrate menu, click the type of Differences migration you want to perform.
For example, you can migrate All Different BMC Remedy AR System Objects or Selected
Object.
3. When the migration is finished, press F5 to refresh the report display.
Page 2154 of 4705
Home
Migrating dependent objects from a Dependency report

You can migrate dependent objects from a dependency report.
To migrate dependent objects

2. From the Migrate menu, select the type of dependency migration you want to perform.
For example, you can migrate All BMC Remedy AR System Objects and Dependencies or
All Forms and Dependencies.
3. In the Destination Type dialog box, select the destination type by clicking Server or Migrator
File.
a. If you click Server, select the destination server, and click OK. The source server is
always the server window you have activated at the time of the migration. The objects
you select are migrated to the destination server you selected.
b. If you click Migrator File, select the destination path, enter a file name, and click Save.
Migrating overlay objects and custom objects

This section discusses about the overlay support in BMC Remedy Migrator and explains the
migration process for overlay and custom objects:
Support for overlays and custom objects
Migration process overview for overlays and custom objects
Existing overlay migration
New overlay migration
Migrating overlays when corresponding overlaid objects do not exist at destination
Migrating origin objects for which overlays exist at the destination
Viewing the customization type in BMC Remedy Migrator
Support for overlays and custom objects

BMC Remedy Migrator supports preserving customizations with overlays and custom objects by
enabling you to:
Select only overlays or only origin objects in the object list by using a context menu or by
sorting on the Customization Type column
Compare overlays at the source to origin objects at the destination
Compare origin objects at the source to overlays at the destination
Generate a detailed difference report for selected objects only
Generate a detailed difference report for objects that are listed in a BMC Remedy Migrator
instruction file
Generate a BMC Remedy Migrator instruction file for selected objects only
Generate a BMC Remedy Migrator configuration file
Page 2155 of 4705
Home
Generate a Detailed difference report for differences not permitted in overlays. See Creating
a Migration Instruction file.
In this topic:
Creating a Migration Instruction file
Comparing objects at the same location
Creating a Migration Instruction file

Perform the following steps to create a Migration Instruction file to use for comparison.
To create a Migrator Instruction file

1. Select one or more items in the objects list and right-click to bring up the menu.
2. From the right-click menu, select Create Instruction File.
3. Select the source-destination mapping method to handle mapping in the report.
Map Origin to Overlay
Map Overlay to Origin
4. Use the Save As dialog to specify a file and location, and save the instruction file.
BMC Remedy Migrator caches overlays and custom objects along with all origin BMC
Remedy AR System objects and displays them in the objects list. For example, if an overlay
(ALI1_o) exists for an active link (AL1), BMC Remedy Migrator caches both these active
links because they are valid AR System server objects. It displays both AL1 and AL1 _o in
the objects list of the server.
BMC Remedy Migrator also enables you to perform the following operations:
Compare and migrate overlays and custom objects in the same manner as origin BMC
Remedy AR System objects.
When migrating objects, BMC Remedy Migrator does not migrate the overlayProp and
overlayGroup properties. These properties are managed by the server, and their values are
set only when you create an overlay or a custom object. See Customizing applications using
overlays and custom objects.
Compare objects within the same file or on the same AR System server.
See Comparing objects at the same location
Specify backup and masking options, and create migration scripts and dependency reports
for overlays and custom objects as you would for origin BMC Remedy AR System objects.
Note
BMC Remedy Migrator provides migration and comparison masks for view and field
properties. However, BMC recommends that you do not disable the migration masks. If
you do so, BMC Remedy Migrator does not migrate overlays and custom objects
corresponding to view and field objects that you modified or added in your source setup.
Page 2156 of 4705
Home
Migrate overlays and custom objects along with origin BMC Remedy AR System objects.
See Migrating overlay objects and custom objects.
BMC Remedy Migrator supports these operations only for those objects that the AR System
server supports. See Fixing non-permitted modifications.
Comparing objects at the same location

You can compare overlay objects that are of same type, having different names and exist in the
same file or on the same AR System server. For example, you can compare an object with its
overlay if they exist on the same server.
Note
BMC Remedy Migrator does not support comparing objects that are of same type and
have different names but exist in different locations.
To compare objects at the same location

1. In the objects list view of a file or an AR System server, select the objects that you want to
compare with other objects.
2. Select View > Differences > currentFileOrServerName.
The Source - Destination Mapping dialog box appears, as shown in the following figure.
Source - Destination Mapping dialog box
Initially, the Destination Object Name column is empty.

3. Use one of the following methods to compare the source objects with other objects:
Page 2157 of 4705
3.
Home
To compare overlay and origin objects in the same file or on the same server, perform
one of the following actions:
To compare origin objects with overlay objects, click the Map To Overlay
button. Any overlay objects in the Source Object Name column are cleared.
The names of the source objects suffixed with __o, which indicate the
corresponding overlay objects, are populated in the Destination Object Name
column.
To compare origin objects with overlay objects, click the Map To Base button.
Any origin objects in the Source Object Name column are cleared. The names
of the source objects without the __o suffix, which indicate the corresponding
origin objects, are populated in the Destination Object Name column.
Note
The Map To Overlay and Map To Base buttons are enabled only
when comparing objects in a file or on an BMC Remedy AR System
7.6.04 (or later) server.
For overlaid objects, the difference report indicates the differences against their
overlays. For unmodified objects, the difference report indicates that the
corresponding overlays are missing.
Change the values in Destination Object Name to the names of the objects that you
want to compare with the source objects. For example, to compare two different
active links (AL1 and AL2) on the same server:
a. In the server objects list, select ALI1.
b. In the Source - Destination Mapping dialog box, enter AL2 in the Destination Object
Name column and click OK.
Tip
Edit the values in the Destination Object Name column only if you know the
exact names of the objects that you want to compare. Otherwise, the
difference report generated might not be of value.
You cannot change the values in Source Object Name. Only the objects that you
selected in the objects list are considered as source objects for comparison.
Click the Prefix Dialog button to open the Prefix dialog box, where you can specify a
prefix for the destination objects.
See Creating and using Differences reports.
4. Click OK.
Page 2158 of 4705
Home
BMC Remedy Migrator compares the objects and generates the difference report.
Migration process overview for overlays and custom objects

When you migrate objects from an earlier version of the AR System server to an AR System
7.6.04 server or later, BMC Remedy Migrator migrates the origin objects but does not modify
any overlays or custom objects.
When you migrate objects from AR System 7.6.04 server or later to an earlier AR System server
version, BMC Remedy Migrator:
Migrates unmodified objects.
Migrates custom and overlaid objects. However, it does not migrate the properties that
indicate whether an object is custom or overlaid, because the properties are not supported
on the earlier server version.
Attempts to migrate overlays, but fails because the destination server does not support
overlays.
The following figure depicts the process that BMC Remedy Migrator follows for migrating overlays.
Migration process for overlays
Page 2159 of 4705
Home
You can migrate overlays and custom objects between the following locations:
From one AR System server to another
From a AR System server to a file
From a file to a AR System server
Page 2160 of 4705
Home
From one file to another
Note
When the destination location is a file, BMC Remedy Migrator updates it with the source
objects, taking into consideration any masking options that you specify. It does not check
whether overlaid or overlay objects are present at the destination.
Existing overlay migration

If you migrate an overlay that is already existing in the destination, BMC Remedy Migrator
overwrites the overlay object on the destination.
If you make changes to an overlaid object that are automatically reflected in its overlay. You cannot
migrate only the overlay. You must migrate the overlaid object. The appropriate changes are
automatically reflected in the overlay at the destination server.
When you migrate an AR Server overlay object, the difference report lists the changes to the
granular components of the overlay object. The report also specifies the overlay type that was
created.
The following figure shows customizations to the Group and Subadministrator Permissions listed
separately in a Differences report.
Group and Subadministrator permissions - Differences report
Customizations to the granular components of a form's properties are marked in a difference report.
The entries in the difference report for a form overlay in version 8.1 and later of AR System appear
as shown in the following image:
Property List - Differences report
Page 2161 of 4705
Home
For more information, see Granular overlays.
New overlay migration

If you migrate a new overlay from a source that does not exist at the destination, BMC Remedy
Migrator checks whether the corresponding overlaid object exists at the destination server. If the
overlaid object exists, BMC Remedy Migrator migrates the overlay.
Consider this example. The source server contains an active link (AL1) and its overlay (AL1_ o).
The destination server contains only the unmodified object, AL1. If you migrate AL1o, BMC
Remedy Migrator migrates AL1_o.
Migrating overlays when corresponding overlaid objects do not exist at destination

If you migrate an overlay when the corresponding overlaid object is not present at the destination
server, BMC Remedy Migrator attempts to migrate the overlay. However, the AR System server
returns an error. BMC Remedy Migrator includes the error message in the result report, and
continues its processing.
Consider this example. An active link (AL1) and its overlay (AL1_ o) exist at the source. Neither of
these objects exists at the destination. When BMC Remedy Migrator attempts to migrate AL1_ o,
the destination AR System server does not create the overlay because the corresponding overlaid
object does not exist.
The migrator difference report lists the difference in the object properties when you overlay an
object does not exist on the destination server. The following image shows the table that lists the
difference in the object property and the overlay type on the source and destination server.
Source object overlay - Difference report
Page 2162 of 4705
Home
For more information, see Granular overlays.
Migrating origin objects for which overlays exist at the destination

If you migrate an origin BMC Remedy AR System object for which a corresponding overlay exists
at the destination, BMC Remedy Migrator migrates the origin object. The destination AR System
server then evaluates the differences and updates the corresponding overlay with only the
permitted modifications. See Fixing non-permitted modifications.
If you migrate an overlaid form and all its related objects, BMC Remedy Migrator migrates the form,
its objects, and their corresponding overlays, but does not migrate the overlay form. You must
explicitly select the overlay that you want to migrate with its overlaid form.
Viewing the customization type in BMC Remedy Migrator

You can view the customization type of an object, such as overlaid, overlay, or custom, in BMC
Remedy Migrator. You can sort and select the objects according to the type of customization in
BMC Remedy Migrator.
To view the customization type of an object in BMC Remedy Migrator

1. Open a server window or a file containing objects:
a. To open a window for a server, select File > New Server Window, and select a
server.
b. To open a window for a file, select File > Open, and select a .def or .migrator file.
2. To see the Customization Type column, scroll the object list in the right pane.
The following values appear for the objects in the list:
Value
Description
Custom
Identifies a custom object
Page 2163 of 4705
Home
Value
Description
Overlaid
Identifies an origin object that has an overlay object
Overlay
Identifies an overlay of the origin object
No value
Identifies an origin object that does not have an overlay object. The customization type column is blank.
Migrating using command-line interface

The command-line interface (CLI) is a standalone application that delivers BMC Remedy Migrator
functionality without a graphical interface. You can use the command line to set migration options,
migrate objects and data, compare information between migrations, and generate difference reports
. In addition, you can use the CLI to compare information, including data and between migrations (
which you cannot do with the graphic user interface).
The BMC Remedy Migrator CLI can be useful when performance is critical for large migrations or
when making a quick comparison of objects to determine what to include in a patch release.
Because the CLI does not require a lengthy caching process, you can perform migrations or
comparisons of large files more quickly.
The CLI also provides Configuration Management Database (CMDB) and IT Service Management (
ITSM) support. CMDB support enables application developers to supply a class name from which
BMC Remedy Migrator can determine the required data and BMC Remedy AR System objects that
make up that class name. The ITSM mapping document includes support for mapping to an entry
ID as a foreign key, and the ability to inject data during a migration.
The CLI application, migratorcli.exe, is stored in the same directory as the main BMC Remedy
Migrator product at installation.
The BMC Remedy Migrator CLI currently supports a single-thread design, but you can supply
multiple instructions within a single migration. The CLI provides full support for object reservation to
ensure that BMC Remedy Migrator either ignores newer or reserved objects on the destination, or
blocks their update, depending on requirements.
Migrations using the CLI are executed in the same order as in the graphic user interface (GUI),
using the same processes. Backups can be configured using the Configuration file. The BMC
Remedy Migrator CLI can generate both Differences and Results reports; however, Results reports
are the only reports generated through the CLI that can be opened in the BMC Remedy Migrator
GUI.
Note
Because the CLI does not use the Windows registry, any options you set through the GUI
are ignored in the CLI.
Page 2164 of 4705
Home

Examples of CLI migration commands
Multiple migrations or comparisons using one instruction file
Migrating using a package file
Migrating using a Differences report
XML files for processing commands
BMC Remedy Migrator Log files overview
Command line options
Metadata mappings and CMDB
Metadata mappings and BMC Remedy ITSM
Form mapping data options
Enabling filters and escalation
Creating a configuration file by using BMC Remedy Migrator
Examples of CLI migration commands

In each of the following compare (-c) examples, a comparison result report is generated named
Specified Object Comparison.xml.
Note
You cannot create a comparison result report for the association object.
If the --<object type> command is not included, the example is an all-object migration/
comparison. The name of the comparison result file is All Object Comparison.xml.
Warning
If the comparison result file already exists, it is overwritten with the new file.
Specified form migration/comparison

migratorcli -m -s <sourceLocation> -d <destinationLocation> --form "Sample:Cities"
-g "Migrator Configuration.xml" -u Demo
migratorcli -c -s <sourceLocation> -d <destinationLocation> --form "Sample:Cities"
All Form migration/comparison
Page 2165 of 4705
Home
Warning
The "" must be specified for all items; otherwise, BMC Remedy Migrator generates an
error.
migratorcli -m -s <sourceLocation> -d <destinationLocation> --form "" -g "Migrator

Configuration.xml"
-u Demo
migratorcli -c -s <sourceLocation> -d <destinationLocation> --form "" -g "Migrator
Configuration.xml"
-u Demo
Specified form and all filters migration/comparison

This example show how a you can specify multiple object types on the command line. This
examples includes a single form and all filters. More object types can be added if needed.
migratorcli -m -s <sourceLocation> -d <destinationLocation> --form "Sample:Cities" filter ""

migratorcli -c -s <sourceLocation> -d <destinationLocation> --form "Sample:Cities" filter ""
Specified CMDB migration/comparison
Note
In this command sequence, the --metatype is required, because it defines the mapping to
use within the mapping file CMDBMetaData.xml file.
migratorcli -m -s <sourceLocation> -d <destinationLocation> --metadata "BMC_Person" -metatype "CMDB"

-y "CMDBMetaData.xml" -g "CMDBConfiguration.xml" -u Demo
migratorcli -c -s <sourceLocation> -d <destinationLocation> --metadata "BMC_Person" -metatype "CMDB"
All CMDB migration/comparison
Note
Page 2166 of 4705
Home
In this command sequence, the -- metatype is required because it defines the mapping to
use within the mapping file CMDBMetaData.xml.
migratorcli -m -s <sourceLocation> -d <destinationLocation> --metadata "" --metatype "

CMDB"
migratorcli -c -s <sourceLocation> -d <destinationLocation> --metadata "" --metatype "
CMDB"
All object migration/comparison

migratorcli -m -s <sourceLocation> -d <destinationLocation> -g "Migrator
Configuration.xml" -u Demo
migratorcli -c -s <sourceLocation> -d <destinationLocation> -g "Migrator
Deployable applications instruction file
Note
To execute this and the next three examples, you can use the following migration or
comparison command sequences:
migratorcli -m -s <sourceLocation> -d <destinationLocation> -i <

instructionFileName>
migratorcli -c -s <sourceLocation> -d <destinationLocation> -i <
instructionFileName>
-g "Migrator Configuration.xml" -u Demo{*}

- <instructions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:
noNamespaceSchemaLocation=
"Migration Instructions.xsd"> - <instruction enabled="true" name="ExampleAppDeployment">
- <special-instructions>
- 
<special type="deploy" name="Sample" enabled="true" />
<special type="deploy" name="Home Page" enabled="true" />
</special-instructions>
</instruction>
Page 2167 of 4705
Home
</instructions>
CMDB instructions
This example shows how you can migrate or compare a specific class within the CMDB system and
remember to include the CMDBMetaData.xml mapping file on command line.

"Migration Instructions.xsd"> - <instruction enabled="true" name="ExampleCMDB">
- 
<special type="meta-data" name="BMC_Person" owner="CMDB" enabled="true" />

</instruction>
</instructions>
Data instruction file

This example shows how you can migrate or compare data between one or more forms where a
query or all data can be included.

"Migration Instructions.xsd"> - <instruction enabled="true" name="ExampleData">
- <data-instructions>
- <data enabled="true" source-form="User" destination-form="User" unique-field-id="1"
type="data"
mode="search" merge-option="update" ignore-required-fields="true"
ignore-pattern-matching="true"
count="0" disable-related-workflow="false">{
<qualification>'Login Name' != $NULL$</qualification>
<ports enabled="true" list="390635" fast="390620" />
</data>
- <data enabled="true" source-form="Group" unique-field-id="1" type="data" mode="all"
merge-option="update" ignore-required-fields="true" ignore-pattern-matching="true" count
="0"
disable-related-workflow="false">
</data>
</data-instructions>}
</instruction>
</instructions>
Note
Page 2168 of 4705
Home
BMC Remedy Migrator updates the migration status after completion of the migration
process for each schema. If a schema record failed to migrate, BMC Remedy Migrator
updates the status as completed with errors, but displays the accurate status for the
remaining schemas. This helps you to get the up-to-date migration status even if there is
failure during the migration process or if the migration is interrupted manually.
Truncating data on forms

When the destination field size is less than the source field size, an error might appear during
migration. To avoid the issue, you can enable data truncation on forms. There are two methods for
handling data truncation:
Setting form level data truncation
Setting field level data truncation
Setting form level data truncation

You can use the enable-truncation="true" option in the instruction.xml file to enable data
truncation on all data fields on the form where the size of a destination field is less than the size of
the field in the source form. If you do not set the option to true, BMC Remedy Migrator assumes
false, which is the default.
Setting field level data truncation
You can enable data truncation for selected fields on the form by using the <truncate> option in the
<data> tag of the instruction.xml file. To enable the feature, specify the field IDs in the <truncate
> tag as shown in the following code sample:
<data enabled="true" source-form="TestForm"
destination-form ="TestForm" type="data" mode="search"
<qualification> 1=1 </qualification>
<unique-fields> <field Id = "1"/> </unique-fields>
<ports enabled="true" list="LIST_PORT" fast="FAST_PORT"/>
<truncate>
<field Id = "destination field ID1"/>
</truncate>
</data>
You can set the field level data truncation for character fields only. If you do not specify the
character field IDs, BMC Remedy Migrator ignores the fields and continues the execution without
an error or termination. The field level data truncation occurs only when the destination field size is
less than the source field size.
Note
Page 2169 of 4705
Home
If you specify a field ID that is not present on the destination form, BMC Remedy Migrator
displays a warning message indicating that the field is missing on the destination schema.
When you enable the field level data truncation feature, BMC Remedy Migrator behaves as follows:
When you do not add the field list --When you do not specify the field IDs in the <truncate>
tag, but enable the form level data truncation, BMC Remedy Migrator evaluates each field on
the destination form to decide if the data needs to be truncated. If the field requires
truncation, BMC Remedy Migrator truncates data in that field.
When you add the field list-- When you specify the field IDs in the <truncate> tag, but do not
enable form level data truncation, BMC Remedy Migrator truncates data for the specified
fields in the list. BMC Remedy Migrator maintains the field mappings that are specified in .
arm file.
When you enable both field level and form level data truncation --When you specify the field
IDs in the <truncate> tag, and also enable the form level data truncation, BMC Remedy
Migrator ignores the specified field level data truncation and only considers form level data
truncation. Each field present on the destination form is evaluated to decide if the data needs
to be truncated. If you specify a field ID that is not present on the destination form, BMC
Remedy Migrator does not display an error message, but continues the execution.
Multiple migrations or comparisons using one instruction file

This example show how you can migrate or compare objects, data and or special items in one
instruction.

noNamespaceSchemaLocation="Migration Instructions.xsd">
- <instruction enabled="true" name="Example">
- <object-instructions type="specified">
- <objects type="Form" enabled="true" mode="specified">
- 
<object name="Sample:Cities" destination-name="Example:Sample:Cities" />
</objects>
- 
<objects type="Active Link" enabled="true" mode="all" />
- 
<objects type="Filter" enabled="true" mode="all" />
</object-instructions>
<objects type="Association" enabled="true" mode="all" />
</object-instructions>
- 
<special type="related" name="Group" enabled="true" />
<special type="related" name="User" enabled="true" />
Page 2170 of 4705
Home
- <data-instructions>
- 
- <data enabled="true" source-form="Sample:Cities" type="data" mode="number"
merge-option="update" ignore-required-fields="true" ignore-pattern-matching="true" count
="5" disable-related-workflow="false">
</data>
</data-instructions>
</instruction>
</instructions>
Migrating using a package file

This example shows how a package.xml file can be used to execute a series of migration
instructions. Those instructions are executed in the order in which they appear in the file.
Note
To execute this example, you can use the following migration or comparison command
sequences: migratorcli -m -s < sourceLocation> -d < destinationLocation> -x <
package_filename> -g "Migrator Configuration.xml" -u Demo migratorcli -c -s <

sourceLocation> -d < destinationLocation> -x < package_filename> -g "Migrator

- <package xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:
noNamespaceSchemaLocation="Migration Package.xsd" configuration="">
<instructions file="ExampleApplicationDeployment.xml" type="all" command="migrate"
enabled="true" />
- <instructions file="ExampleCMDBInstruction.xml" command="compare" type="specified">
- 
<instruction name="ExampleCMDB" />
</instructions>
<instructions file="ExampleDataInstruction.xml" type="all" command="migrate" enabled="
true" />
</package>
Migrating using a Differences report

This example uses a command with a Differences report as input for a migration and a comparison.
Note
Page 2171 of 4705
Home
The migration/comparison extracts all objects and data that are different or missing and
migrate/compare them between the specified source and destination. The specified
source and destination do not need to be the same as those used to generate the
difference report. Also, you do not need to include the CMDB meta mapping document if
the Difference report was created for one or more CMDB-based classes, because the
report contains only objects and data.
migratorcli -m -s <sourceLocation> -d <destinationLocation>

--difference <difference_report.xml> -g "Migrator Configuration.xml" -u Demo
migratorcli -c -s <sourceLocation> -d <destinationLocation>

--difference <difference_report.xml> -g "Migrator Configuration.xml" -u Demo
XML files for processing commands

The BMC Remedy Migrator CLI uses four types of XML files as instruction sets to identify migration
options and execute the migration or reporting specified. These files are included in the
command-line sequence. You can use third-party XML editors to work with these files. The
following table lists and describes these files.
Note
The source and destination are not stored in any of these XML files. As a result, these
files can be reused as needed for comparisons or difference reporting.
XML files used in BMC Remedy Migrator command-line interface

XML file
BMC Remedy Migrator CLI function
Package
Can be used to assemble multiple sets of instructions within one migration.
Configuration
Specifies migration, logging, mask, differences, change history, backup, and prefix options. For more information
about options, see Options.
Instruction
Contains a single set of instructions for a migration. With the compare command, this file also can contain
multiple named sets where the name is used to name the result file as well as the difference file.
Difference
Enables migration of all objects found to be different or missing between source and destination.
Metadata
mapping
Used for migrations that include CMDB and ITSM.
Page 2172 of 4705
Home
The BMC Remedy Migrator CLI also makes XSD schema files available that can be used to
validate XML documents.
How BMC Remedy Migrator uses XML interpreters
BMC Remedy Migrator Log files overview

When commands are executed through the command line, BMC Remedy Migrator can generate
log files that are stored in the Migrator directory. You can specify logging options such as the level
of detail for log files and well as their format (such as plain text, XML, or HTML). The logging
Page 2173 of 4705
Home
structure is based on the Apache logging design.

When you migrate, compare or delete a large amount of data, BMC Remedy Migrator might
generate a very large log file. It is difficult to open, view and analyze the migration result in the large
file. Splitting the file into multiple smaller files enables you to verify the result easily.
You can specify a file size limit in the configuration.xml file to split the log files. You can set the
size limit in bytes, kilobytes (KB), megabytes (MB), and gigabytes (GB) as shown in the following
code samples:
To limit the file size to 1 byte set, <filesize limit="100" unit = "BYTES">
To limit the file size to 1 megabyte set, <filesize limit="1" unit = "MB">
When the file size exceeds the configured value, the BMC Remedy Migrator splits the file and
creates a new file. The files are named in the filename_index.filetype format and are stored in the
Migrator directory.
When the size of the Remedy_Contract_Management.html file exceeds the specified limit, a new
file is created. For example, the split files of the Remedy_Contract_Management.html file are
named as follows:
Remedy_Contract_Management_1.html
Remedy_Contract_Management_2.html
Command line options

The following table describes the command options available through the BMC Remedy Migrator
CLI. Many commands provide a choice of two formats: abbreviated (a dash and a single letter), or
detailed (two dashes and a descriptive string).
Migration commands and options
Abbreviated
Detailed
Function
-s
--source
The server or file serving as the source.
-d
--destination
The server or file serving as the destination.
-e
--sourceForm
For data migrations, the start of a data block that determines the data to be compared or
migrated.
-q
--qualification
A string that represents the qualification used to obtain the data.
--count
The maximum number of items retrieved in a migration. When this count is reached, no further
comparisons or migrations take place. A count of zero is the same as having no limit.
--list
Specifies use of the List port on the source, if the source is a server. The port number is the List
port.
--fast
Specifies the use of the Fast port on the destination, if the destination is a server.
Page 2174 of 4705
Home
--fieldid
The integer value that uniquely identifies a field. By default, the ID is 1 for the entry ID, but can be
changed to some other unique value, which is usually associated with a unique index on the
same field for the form being migrated.
--disable
Specifies whether related workflow should be disabled in the target form during a migration.
--fieldmap
The name of the file (.arm or .armx ) that contains field mappings, if field mapping is enabled for
this data migration.
-x
--package
If a package XML file is included in this migration, the name of the file.
-u
--user
The user name required to log in to the server. The default user name is Demo for both source
and destination.
--dst_user
The user name required, if any, for logging into the destination. If a user name is not specified
with this command, BMC Remedy Migrator defaults to the -u or the --user command.
--password
The password required, if any, for logging into the server. The default is " " (no password) for
both source and destination. If a password is not specified, the command is ignored.
-dst_password
The password required, if any, for logging into a destination server. BMC Remedy Migrator
defaults to the -p or --password command if no password is specified for this command.
-authentication
The authentication, if any, used to log in to the server. The default is "" (no authentication). If no
authentication is required, this command is not required.
-t
--tccport
The TCP port number, if any, for connection to the AR System server.
-r
--rcpport
The RCP port number, if any, used for connection to the AR System server.
--dst_tcpport
The TCP port number, if any, for connection to the destination server.
--dst_rcpport
The RCP port number, if any, used for connection to the destination server.
--layout
The format used for the generated log files. The options are:
-p
-a
0: XML
1: HTML
2: Simple
3: Console
--level
The level of detail to be provided in generated log files. The options are:
0: Off
1: Fatal
2: Error
3: Warning
4: Information (default)
5: Debug
--logfile
The name of the log file generated if the specified layout is HTML or XML. Ignored for Simple
layout type.
-m
--migrate
Migrate all specified instructions from source to destination.
-c
--compare
Compare all instructions specified between source and destination. With this command, you can
specify what is to be compared with the following flags: -- different: items that are different -same: items that are the same -- missing: items that are missing
-g
--configure
The name of the configuration XML file used in the command.
--instruction
The name of the instruction XML file used in the command.
Page 2175 of 4705
Home
--xslt
The name of the XSLT transformer file used to transform Difference reports from .xml format to
any format you specify (such as HTML).
--xsltx
The file extension to be applied to the transformed file. Defaults to ' .html' if an extension is not
specified.
--form
The type of object to be migrated. To migrate objects of a specific type, enter the object type in
--activelink
the command line, followed by either two empty quotes ("") to migrate all objects of that type, or
the act
--filter
--escalation
-activelinkguide
--filterguide
--association
--application
--packinglist
--webservice
--menu
--dsomap
--dsopool
--flashboard
--alarm
--variable
--image*
-pluginmodeule
-plugindefinition
--metadata
Metadata mappings and CMDB

The BMC Remedy Migrator CLI includes metadata mappings to support CMDB and Atrium
applications. These mappings are defined as XML elements and can be specified in the
CMDBMetaData.xml and CMDBMetaDataEnableDelete.xml files, described in Mapping files.
For more information about working with CMDB and Atrium applications, see the Atrium core
documentation.
Important
Page 2176 of 4705
Home
To prevent possible issues with migrations, be sure that both the source and destination
are using the same CMDB version. Also, because BMC Remedy Migrator does not back
up metadata, migrate critical files to a . migrator file first for safekeeping. You can then
restore these items by migrating from the source backup file to the destination.
In this topic:
Mapping files
Mapping types
Metadata XML document structure
Mapping files
The following mapping files contain the actual mapping details and define how the various CMDB
forms relate to each other:
CMDBMetaData.xml When this file is used, extra attributes and indexes that are not
found on the source are not deleted on the destination.
CMDBMetaDataEnableDelete.xml When this file is used, BMC Remedy Migrator
performs a full synchronization of source and destination, deleting any extra attributes and
indexes on the destination that are not found on the source.
Note
When migrating or comparing CMDB classes, use the supplied CMDBConfiguration.xml
file. This file is identical to the Migration Configuration file, with some different
configuration options.
Mapping types
The mapping design consists of the following mapping types :
BMC Remedy AR System form-to-form data mappings
BMC Remedy AR System object mappings
Form-to-form data mappings

In form-to-form data mappings, you can map multiple forms to each other in the following
relationships:
one to one
one to many
many to many
Page 2177 of 4705
Home
Within each of these relationships, you can define the fields used to link the entries from the forms.
Every referenced form included in the mapping must be defined within the metadata mapping
design.
Object mappings
In object mapping, you can define how one or more forms map to one or more objects, the object
type (such as a form), and how the object name is calculated. For example, you might have a
mapping includes this information for a field:
Field '8'
Text ':'
Field '5364918'
The field name would be calculated as:
The contents of Field 8 + ':" + the contents of field 5364918.
If Field 8 = Sample and field 5364918 = City, the field name would be calculated as Sample + ':' +
City, or Sample:City.
Metadata XML document structure

The following section uses sample entries to explain the metadata XML document structure.
<meta-data xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:
noNamespaceSchemaLocation="Migration Meta Data.xsd">
The main root element can contain multiple*<meta>* items for each major metadata type, such as
CMDB.
meta name
<meta name="CMDB" identifier-form="OBJSTR:Class" description="This is the meta-data
for the CMDB application design">
meta name is the root element for a specific meta-data design such as CMDB and contains all the
form and object mappings that are specific to this element.
meta name The name of the metadata item. It is used as the "owner" within the
instruction XML document when attempting to migrate or compare metadata items within
special items.
identifier-form The main form that contains the true name of the metadata. For CMDB,
this is the form that contains the class name. This is known as the root form from which all
other forms are mapped.
description Text that describes the document.
Page 2178 of 4705
Home
form name
<form name="OBJSTR:Class" unique-field-id="1" name-field-id="8" extends-form="
form-name">
form name identifies a specific form and how the data on that form relates to other definition forms
or BMC Remedy AR System objects or both.
form name The name of the form on the AR System server.
unique-field-id The unique identifier for the field. By default, 1 is used.
name-field-id The field that contains the unique name of the entry. It is typically used
only when the mapping item is the main identifying form. This is the field that is searched
when a name is specified within the instruction document.
extends-form The name of the base form. Entries are mapped using the unique IDs of
this form and the form mapping that is defined for the extends form.
object type
<object type="Form" cascade="all">
For BMC Remedy AR System object mapping, this element and its children identify the object to
which this form mapping maps.
object type The BMC Remedy AR System object that does not include metadata.
cascade The action to take if the parent entry is deleted. Options are:
all Perfoms both creation and deletion of entries.
create-orphan Creates only entries found on the source but are missing from the
destination. Does not delete extra entries found on the destination.
delete-orphan Deletes extra entries found on the destination but not on the source
. Does not create extra entries found on the source.
<field id="1"/> and <text value=":"/>
These items are contained within the <object> element, and are used to identify the
fields and text that make up the name of the BMC Remedy AR System object. The
name is built based on the contents of the fields and the text value.
one-to-many form
<one-to-many form=" formName" local-key-id="3" foreign-key-id="2" cascade="all">
One-to-many mapping is used when a single entry in the main form is related to many entries within
the specified form.
one-to-many form The name of the external form where many entries match one entry
locally.
Page 2179 of 4705
Home
local-key-id The field ID of the local key used in the external form to make multiple
entries from the local form.
foreign-key-id The unique field ID used on the remote form. It is not required, becaus the
unique-field-id defined on the form can be used.
Cascade The action to take if the parent entry item is deleted. Options are:
all
create-orphan (not currently supported)
delete-orphan
The*<local-keys>* and <foreign-keys> can be used if multiple fields are used for
each corresponding attributes. These elements override the corresponding attributes.
many-to-one form
<many-to-one form=" formName" local-key-id="3" foreign-key-id="2">
This mapping type is used to define mapping of multiple entries in the local form to a single entry in
the foreign form. Because this mapping has no cascade option, deleting or creating entries in this
form does not affect the external form.
many-to-one form The name of the external form, where one entry matches many local
entries.
foreign-key-id The unique field ID used on the external form. This ID is not required
because the unique-field ID defined on the form can be used.
one-to-one form
<one-to-one form=" formName" local-key-id= "" foreign-key-id="">
In this mapping, every entry in the local form maps to one entry within the specified external form.
Cascade is not defined for this mapping type.
one-to-one form The name of the external form where one entry matches one entry
locally.
because the unique-field ID defined on that form can be used.
many-to-many form
Page 2180 of 4705
Home
<many-to-many form=" formName" local-key-id="3" foreign-key-id="5" mapping-form=""

source-field-id="2" destination-field-id="1">
This mapping allows mapping of multiple entries in the local form to multiple entries in the external
form. This mapping uses an intermediate form in which the unique fields from the local form are
mapped to the unique fields on the external form.
many-to-many form The name of the external form where many entries matches many
local entries
because the unique-field ID defined on that form can be used.
mapping-form The name of the intermediate form used in the mapping.
source-field-id The field ID in the mapping form that contains the value of the
unique-field ID of the source entry. This value comes either from the local-key-id field or the
unique-field-id.
destination-field-id The field ID in the mapping form that contains the value of the
unique-field-id of the destination entry. This value comes either from the foreign-key-id field
or the unique-field-id of the external form.
The <source-fields> and <destination-fields> can be used to override the attributes and where
multiple fields can be defined for each. The source and destination field IDs must be defined for the
mapping to succeed.
Important
If you have migrated hierarchical groups (groups that include both parent and child groups
), the Differences report might show a difference between source and destination. This
could be because a child group was migrated but not its parent. To resolve this difference,
migrate both parent and child groups.
Metadata mappings and BMC Remedy ITSM

The BMC Remedy Migrator CLI provides support for BMC Remedy ITSM through XML documents
that enable mapping to an entry ID as the foreign key, and the ability to inject data during
migrations.
Warning
Using BMC Remedy Migrator CLI with BMC Remedy ITSM applications might introduce
inconsistencies in the application data. Instead, BMC recommends that you use the Data
Management Tool with BMC Remedy ITSM applications to ensure consistency.
Page 2181 of 4705
Home
XML mapping documents for BMC Remedy ITSM

The following BMC Remedy ITSM mapping documents are available:
ItsmMetaData.xml
ItsmMetaDataEnableDelete.xml
A configuration file, ItsmConfiguration.xml, is also available, with the Group Data Merge option
set to Replace.
The COM:Company form serves as the root in the BMC Remedy ITSM mapping document. The
following table outlines the forms handled by the BMC Remedy ITSM mapping document.
Forms and BMC Remedy ITSM mapping

Form
Target form
Mapping type
Local field ID
Foreign field ID
COM:Company
n/a
n/a
n/a
n/a
COM:CompanyAlias
COM:Company
one to one
1000000072
FIN:ConfigCost CentersRepository
COM:Company
many to one
1000000001
1000000001
FIN:CostCenterUDA Associations
COM:Company
many to one
490009000
179
CTM:Region
COM:Company
many to one
1000000001
1000000001
SIT:SiteCompanyAssociation
COM:Company
many to one
1000000001
1000000001
SIT:Site
SIT:SiteCompany Association
one to many
1000000074
SIT:SiteAlias
SIT:Site
one to one
1000000074
SIT:SiteGroup
COM:Company
many to one
1000000001
1000000001
CTM:People
COM:Company
many to one
1000000001
1000000001
CTM:People
SIT:Site
one to one
1000000074
CTM:LoginID
CTM:People
many to one
1000000080
User
CTM:People
one to many
101
CTM:SupportGroup FunctionalRole
CTM:People
many to one
CTM:SupportGroup Association
CTM:People
many to one
CTM:PeoplePermissionGroups
CTM:People
many to one
1000000080
CTM:LoginID
CTM:People
many to one
1000000080
CTM:PeopleWallet
CTM:People
many to one
1000000080
CTM:PeopleHRAttendance Mgmt
CTM:People
many to one
1000000080
CTM:PeopleHR TimeManagement
CTM:People
many to one
1000000080
Page 2182 of 4705
Home
Form
Target form
Mapping type
Local field ID
Foreign field ID
CTM:PeopleHR TimeManagement
CTM:PeopleHR AttendanceMgmt
many to one
1000002139
CTM:PeopleEducation
CTM:People
many to one
1000000080
CTM:PeopleTravelProfile
CTM:People
many to one
1000000080
CTM:PeopleBenefitInfo
CTM:People
many to one
1000000080
CTM:PeopleITSkills
CTM:People
many to one
1000000080
CTM:PeopleWorkLog
CTM:People
many to one
1000000080
NTE:CFG-Notification Events
CTM:People
many to one
1000000080
CTM:PeopleOrganization
COM:Company
many to one
1000000001
1000000001
PCT:ProductCatalog
PCT:Product Company
one to many
1000000097
Association
PCT:ProductCompany Association
COM:Company
many to one
1000000001
1000000001
PCT:ProductCompany Association
PCT:ProductCatalog
many to one
1000000097
CTM:SupportGroup
COM:Company
many to one
1000000001
1000000001
CTM:SupportGroupAlias
CTM:SupportGroup
many to one
1000000079
CTM:SupportGroup Assignments
CTM:SupportGroup
many to one
1000000079
CTM:SYSAccessPermission Groups
COM:Company
many to one
1000000001
1000000001
PCT:ProductAlias
PCT:ProductCatalog
many to one
1000000097
PCT:ProductModel-Version
PCT:ProductCatalog
many to one
1000000097
PCT:ProductCatalogAlias
MappingForm
PCT:ProductCatalog
one to many
CFG:GenericProdService Assoc
PCT:ProductCatalog
many to one
1000000097
CFG:GenericProdServiceAssoc
PCT:ProductModel Version
many to one
1000000799
CFG:GenericCompany ModuleAssoc
COM:Company
many to one
1000000001
1000000001
CFG:ServiceCatalog
CFG:ServiceCatalog Assoc
one to many
1000000096
CFG:ServiceCatalogAssoc
COM:Company
many to one
1000000001
1000000001
CFG:ServiceCatalogAssoc
CFG:ServiceCatalog
many to one
1000000096
CTM:PeopleTemplateSG
CTM:SupportGroup
many to one
1000000097
CTM:PeopleWorkLog
CTM:People
one to many
1000002674
CTM:PeopleWorkLog
CTM:People
many to one
1000000080
NTE:CFG-NotificationEvents
CTM:SupportGroup
many to one
1000000079
Page 2183 of 4705
Home
Mapping to a foreign entry ID field

When BMC Remedy Migrator migrates or compares data based on the mapping document, it
checks the entry ID maps on a per-form basis if the foreign field ID is an entry ID. If BMC Remedy
Migrator finds an entry for that entry ID value in the source entry, it obtains the destination value
from the map, and replaces the field value in the entry being migrated or compared.
Injecting data
In the mapping document, you can define characters to inject into each entry being migrated or
compared for the mapping item. This injection can be added within the < insert-value-fields >
element, as shown.
<form name="COM:Company" unique-field-id="179" type="update" disable-related-workflow="

false">
<insert-value-fields>
<field-value id="1000000076" value="LOAD"/>
</insert-value-fields>
<name-fields>

<field id="1000000001"/>

<field id="260000032"/>
</name-fields>
</form>
Child elements can be added within the < insert-value-fields > element to specify field ID and
value pairs to insert into an entry before that entry is modified or compared on the destination.
Form mapping data options

The following data migration options are available in the mapping document:
merge-type (default: update)
disable-related-workflow (default: false)
ignore-pattern-matching (default: true)
ignore-required-fields (default: true)
disable-related-association (default: false)
<data enabled="true"
source-form="FIN:ConfigCostCentersRepository"
destination-form="Groups"
unique-field-id="1"
type="data"
mode="search" merge-option="update"
ignore-required-fields="true"
ignore-pattern-matching="true"
count="40"
disable-related-workflow="false">
Page 2184 of 4705
Home
</data>
Note
For BMC Remedy ITSM, metadata migration is supported only with those companies for
which an instance ID is the same on both the source and the destination. When a
metadata migration is performed for the first time, the company name or company ID used
in the source should not exist on the destination. Also, metatdata migration for BMC
Remedy ITSM is not supported for sample company data provided with the installed
product.
Enabling filters and escalation

BMC Remedy Migrator includes an option to enable filters and to execute escalation on the
destination side of a data migration. This functionality allows you to execute a workflow for specific
forms to trigger special use case migrations.
The new option is activated in the instruction.xml file, by using the
disable-related-workflow attribute in the <data> tag. You can set the following values to
the attribute:
true No filters are triggered for the form.
false Specified filters are triggered for the form.
When the disable-related-workflow attribute is activated, the attribute must have a value of
false. This is shown in the following code sample:
<data enabled="true" source-form="TestForm2" type="data" mode="search" merge-option="

update" disable-related-workflow="false"> </data>
To start an escalation for a particular form, you must provide the escalation name in the <data> tag
. Use the <escalation> tag to provide the escalation name that is triggered during data migration.
You can add multiple <escalation> tags within a single <data> tag. This is shown in the following
code sample:
<data enabled="true" source-form="TestForm2" type="data" mode="search" merge-option="

update" disable-related-workflow="false"> <escalation name"TestForm2Esc1"/> </data>
Note
If an escalation error occurs during the migration, the error must be fixed manually.
Page 2185 of 4705
Home
Creating a configuration file by using BMC Remedy Migrator

You can generate a configuration file ( Migrator Configuration.xml) by using BMC Remedy
Migrator to use in the BMC Remedy Migrator CLI commands.
To create a configuration file by using BMC Remedy Migrator

1. Start BMC Remedy Migrator.
2. Go to Tools > Create Configuration File.
3. Select a location to save the file and click Save.
Working with migration scripts

This section describes the scripting process and explains how to set up and run a migration script.
It describes how you can modify, schedule, change, and delete migration scripts:
Modifying migration scripts
Scheduling scripted migrations
Scripting overview
Migration Script window overview
Creating and saving migration scripts
Opening and running migration scripts
Modifying migration scripts

You can perform any of the following modifications to a migration script from the Migration Script
window:
Change the object elements.
Add or remove a destination server.
Change the name of a destination server.
Add a description of the script.
Add Before commands, After commands, or both.
If migrating between servers, change login information for the source or destination server.
Migration Script window
Page 2186 of 4705
Home
When performing scripting procedures, use the following mouse shortcuts:

If BMC Remedy Migrator is not running, double-click a script file from its saved location to
launch BMC Remedy Migrator and open the script in a window.
Right-click an object in the right pane of a server window to open specific menu options
available for that object.
Top tree options in the left pane of the script window, for example Forms and Groups,
cannot be accessed by way of a right-click. If you go deeper within the tree view by clicking
on objects, you can access lower-level objects by right-clicking.
Click the Server tree view, then double-click Script Files, to view the files that are stored in
the Script Files directory.
Right-click a migration status line in the migration status pane under the All or Scheduled
tabs to open a menu containing options for changing a scheduled migration.
Changing object elements in a script
Adding or removing a server in a script
Editing server options for a script
Modifying and removing objects in a script
Adding Before or After commands and descriptions
Changing object elements in a script

Perform the following steps to change the object elements in a script.
To change object elements in a script

1. Select File > Open or File > Recent Files to open the migration script whose objects you
want to change.
2.
Page 2187 of 4705
Home
2. In the left pane of the migration script window, select AR System Objects, then select the
type of object you want to modify.
3. In the right pane, right-click on the object to modify.
4. From the pop-up menu that appears, select an action.
Note
The available selections in the menu depend on the type of object you have
selected. For example, if you selected a regular form, the Data Mode, Number of
Entries, and Search Criteria selections are not available.
5. If you are prompted to confirm your selection, click Yes to proceed, or Cancel to stop the
modification.
6. Select File > Save to save the modified script.
Adding or removing a server in a script

Perform the following steps to remove a server in a script.
Warning
If you remove a server, all objects associated with that server are removed.
To add or remove a server in a script

1. In the right pane of the Migration Script window, click the migration script for which you want
to add or remove a server.
2. In the left pane, click Servers.
3. Perform either of the following actions:
To add a source or destination server to the list of servers associated with the script
1. Select Servers > Add Server.
2. In the Login dialog box, select a server and enter your login name along with your
password, and click OK.
To remove a destination server from the list
1. In the right pane of the script window, select the server you want to remove.
2. Select Servers > Remove Server, or right-click on the listed server and select
Remove Server.
3. In response to the confirmation prompt, select Yes to remove the server, or No to
cancel the server removal.
Page 2188 of 4705
Home
Editing server options for a script

You can add any number of servers to a script. For example, you might have an existing script that
moves objects from a development server to a quality assurance server. You can edit the script by
removing the development server and adding a production server, along with reassigning all
scripted objects' source and destinations based on the new servers. This ensures that all objects
originally migrated to quality assurance are migrated to the production server.
To edit server options for a script

1. Open the migration script whose server options you want to change.
2. In the right pane of the script window, select the server whose options you want to change.
3. From the Servers menu, select the option you want to change:
Change Login Information Displays the Login dialog box, from which you can enter a new
user name and password, or change server account information for the selected server.
Add Server--Displays the server list. You can select a server to add to the script. See Adding
or removing a server in a script .
Add Migrator File Displays the Open dialog box with the list of .migrator files in the
Scripts directory. You can select a file to add to the script.
Remove Server Enables you to delete a server from the script.
Remove File Enables you to delete a file from the script.
Change History Option Displays the Change History Merge Option. See Setting the
change history options.
Change History String Displays the Change History String dialog box, from which you can
change the string used when change history diaries are merged. See Setting the change
history options.
Default Prefix Options Displays the Prefix dialog box, from which you can change prefix
information. See Migrating objects to a same server.
Use Definition Files for Backup Use definition ( .def) files as a backup file type. See
Backing up destination server.
Use Migrator Files for Backup Use .migrator files as a backup file type. See Backing up
destination server.
Back Up All Objects/Back Up Specific Objects Enables you to back up all files on a
destination server, or selected files. See Backing up destination server.
Back Up Directory Enables you to select a directory for storage of backup files. See
Backing up destination server.
Modifying and removing objects in a script

Use the following procedures to modify objects in a script. You can change the source, destination,
prefix options, or destination name. You can also remove an object from a script.
In this topic:
Page 2189 of 4705
Home
To change the source or destination in a script

To change the prefix options in a script
To change the destination name
To remove an object from a script
To change the source or destination in a script

1. In the Migration Script window's left pane, click AR System Objects.
2. In the right pane, click the object you want to modify.
3. Select Objects > Change Source or Objects > Change Destination.
To change the prefix options in a script

1. In the right pane, click the object whose prefix options you want to change.
2. Select Objects > Prefix Options.
3. In the Prefix dialog box, change the options. See Migrating objects to the same server.
To change the destination name

1. In the right pane, click the object whose destination name you want to change.
2. Select Objects > Destination Name.
3. In the Destination Name dialog box, enter the new destination name.
To remove an object from a script

1. In the right pane, click the object you want to remove from the script.
2. Select Objects > Remove Object.
3. In response to the prompt, click Yes to confirm the removal, or No to cancel it.
Adding Before or After commands and descriptions

Before and After commands enable you to add executable commands to a migration script, such as
verifying that servers are running before a migration begins, sending email notifications related to a
migration, or sending files to a remote server after a migration.
Use the following procedure to add Before or After executable commands, or to add notes or a
description to your scripted migration.
Warning
If a script has a Before or After command (or both), the command must return a value of
zero (0) for the script to work correctly. If the command returns any value other than zero,
BMC Remedy Migrator assumes that the command has failed. If the Before command
fails, the execution of the script stops and no objects are migrated. If the After command
fails, the objects are migrated.
Page 2190 of 4705
Home
To add descriptions and Before or After commands

1. If the Description window (located at the bottom of the Script window) is not open, select
View > Description Bar.
Description bar for a migration script
2. (optional) Click the Description button and type a description for the command or script.
3. Click the Before Command or After Command button and type a Run command line in the
window (for executable file types such as .exe,.bat, or .com ).
The Before command runs before a scripted migration occurs. The After command occurs
after a scripted migration is complete.
4. Run the script to verify that the command you created works.
Scheduling scripted migrations

After you have created a migration script, you can set up a date and time for the migration to occur,
as well as a user or group to notify upon completion. (Notifications are sent by way of the BMC
Remedy AR System Notification API and routed through an alert system within the AR System
server or other mechanism, depending on your configuration.) This is helpful for migrations that you
perform regularly, during or after business hours. For example, you can schedule a scripted
migration to run during off-peak hours when server usage is at a minimum.
To test a scheduled migration script immediately, select Script > Execute Migration Script.
Important
If BMC Remedy Migrator is not running when a migration script is scheduled to begin,
BMC Remedy Migrator starts the migration immediately the next time it is activated.

Scheduling migrations
Changing an existing migration schedule
Scheduling migrations
BMC Remedy Migrator uses the date and time on the client machine for running scheduled
migrations. BMC Remedy Migrator must also be running at the scheduled time for the migration to
start.
Page 2191 of 4705
Home
To schedule a scripted migration

1. Select Script > Schedule Migration Script.
2. In the calendar, click the button to the right of the Migration Script field.
3. In the dialog box, select a saved BMC Remedy Migrator script file, and click Open.
4. In the c alendar, use the arrows to select a month and then click a date on the calendar for
the migration to take place.
Use the > and < buttons to change the month.
Use the >> and << buttons to change the year.
Scheduling a migration
5. In the Time to schedule field, enter or select the hour and minute at which the migration
should begin.
6. (optional) In the Notify User on Completion text box, enter a user or group to notify on
completion.
BMC Remedy Migrator interfaces with BMC Remedy AR System by way of the Application
Programming Interface (API), which must first be set up to send the type of notification you
want to use.
7. Click OK.
The scheduled migration appears in the migration status pane of the Script window.
Changing an existing migration schedule

Use the following procedure to change an existing migration schedule.
Page 2192 of 4705
Home
To change an existing migration schedule

1. In the migration status pane of the Script window, click the Scheduled tab and select the
scheduled migration you want to change.
2. Select Script > Edit Scheduled Migration to display the Schedule Item dialog box.
3. Make any of the following changes:
In the calendar, select a month, and then click a date on the calendar for the
migration to take place.
In the Time to Schedule text box, select the hour and minute you want the migration
to begin.
(optional) In the Notify User on Completion text box, type in a user or group to notify
on completion. BMC Remedy Migrator interfaces with the BMC Remedy AR System
by way of the Application Programming Interface (API), which must first be set up to
send the type of notification you want to use.
4. Click OK.
Scripting overview
You can use migration scripts to create customized migrations between one or more servers, at a
scheduled time. For example, you can select which objects to migrate by moving those objects
from server 1 to server 2, then move all or some of the same objects to server 3. You can then
schedule this script file to run at any time in the future.
How migration scripts handle multiple servers
Page 2193 of 4705
Home
Migrations within a script are executed in server pairs , not in the order in which they are created.
For example, you might have a scripted migration from two source servers (Source Server 1 and
Source Server 2) to three destination servers (Destination Server 1, 2, and 3).
When the script is executed, BMC Remedy Migrator performs the following tasks:
First, it gets a list of all the source servers and then a list of all the destination servers.
Next, it loops through each source server.
Lastly, it loops through each destination server for a source server to determine if any
objects need to be migrated between the two servers. If so, BMC Remedy Migrator migrates
all of those objects. If not, BMC Remedy Migrator continues to the next server pair, until all
the server pair combinations have been checked.
Migration Script window overview

The left pane of the Migration Script window contains elements for easier referencing and
modification of scripts.
Migration script elements
Page 2194 of 4705
Home
The list can include elements such as:

Servers Lists the servers associated with the script.
Migrator Files Lists the .migrator files associated with the script.
Fields Presents form fields that are scripted for migration.
Views Supplies the number of views scripted.
Data Lists the data records contained within a form scripted for migration.
Special Migrations Lists migrations in which an entire object type is migrated, or
applications being deployed through migration.
You can drag and drop entire object types (such as forms or active links) from the
source tree view to a destination. Doing so migrates all the objects of that type. You
can then run the script at any time and BMC Remedy Migrator migrates all of the
objects of that type (including new objects after script creation) that are found on the
source.
You can also deploy applications by way of migration, by selecting an application,
right-clicking on it, choosing Deploy Application from the menu, and selecting a
destination for the application.
Creating and saving migration scripts

This section describes how you can create and run migration scripts. Use the following tips for
faster creation of a migration script:
In Scripting mode, dragging and dropping objects from a source server to a destination
server window automatically creates a new migration script (or adds to an existing one).
Double-clicking a script file from its saved location launches BMC Remedy Migrator and
opens the script in a window.
BMC Remedy Migrator allows you to have only one Scripting window open at a time. If a
Scripting window is already open, BMC Remedy Migrator adds to it.
To create a migration script

1. If you have more than one source server, make sure you are logged on to and have server
windows open for all the servers included in the scripted migration.
2. Select Migrate > Scripting Mode.
3.
Page 2195 of 4705
Home
3. Perform any type of object, field, or data migration between any licenses servers, between a
server and a file, or between files.
A migration script window opens as soon as you script your first object, field, or data type. If
you have several objects to script, you can minimize the window or resize the script window
and continue migrating.
4. When you have completed your script, select File > Save As.
5. Select a destination path and type a file name, making sure to save the file as a .mgrscript
file.
Tip
Store your scripted files in the Migrator Script directory. This directory gives you
access to the files from the Server Tree view by clicking the Scripts icon.
6. Click Save.
7. Close the script window.
Opening and running migration scripts

You can open and run a migration script any time, whether it is scheduled or unscheduled.
To open and run a migration script

1. Select Script > Execute Migration Script.
2. In the BMC Remedy Migrator Scripts dialog box, select the script you want to run and then
click Open.
BMC Remedy Migrator runs the scripted migration. To view a saved scripted file, open the
Script Files directory in the left pane, and double-click the script name.
3. Select the scripted file and click the Execute Migration Script toolbar icon to run the scripted
migration.
Note
To view a progress indicator of an executing migration, select the All tab in the
migration status pane. For more information about using the migration status pane,
see Managing migrations.
You can also open or delete a migration script by right-clicking on a script and selecting the
delete option from the pop-up menu.
Migration script menu
Page 2196 of 4705
Home
Using migration reports

This sections explains how to use migration reports:
Migration Result reports
Dependency reports
Differences reports
Migration Result reports

Migration Result reports provide details about how a migration was performed: the start and end
times, the source and destination points, what was migrated, the options that were in place at the
time of the migration, and so on.
Working with Migration Result reports
Customizing a Migration Result report
Resolving reported failures
Reports based on form data
Migration Result report
Page 2197 of 4705
Home
The Results report includes these categories:

Overall migration statistics--Data that pertains to the entire migration, including name of the
report, the date and time at which it was generated, the version of BMC Remedy Migrator
used, the status of the migration (whether it was completed or interrupted), and the number
of objects of each type that were migrated and (if any) failed to migrate.
The settings selected for the migration, including the server used for the migration, change
history settings, and any prefixes that were selected to be ignored for the migration.
Statistics for each type of object included in the migration, including migration results and
workflow changes, if any.
Information from the source is listed on the left side of the report; information for the destination is
listed on the right side.
Icons in the first column indicate whether or not the migration was successful.
A green check mark indicates that the object was migrated successfully.
A red X indicates that errors occurred during the migration.
Page 2198 of 4705
Home
A yellow Yield sign indicates a warning.

A green arrow pointing to the right indicates that the object is still in the queue to be migrated
.
Working with Migration Result reports

A Migration Result report shows statistical information about a completed migration. BMC Remedy
Migrator saves the report automatically.
In this topic:
Saving a Migration Results report
Removing a Migration Result report
Viewing a Migration Result report
Printing a Migration Result report
The following table outlines some options available when working with Migration Result reports.
Options for working with Migration Result reports

Action
Procedure
Resize a Migration Result report to

your screen
Select View > Zoom and enter a percentage to shrink or enlarge the report. This zoom
percentage is also used when printing a report.
Select colors
Select Tools > Options (see Customizing a Migration Result report).
Display an object type in a report
Double-click a Migrator file to launch a report from its saved location.
Create an image of the report to view

in another application
Select Edit > Copy. Open the other application and select Edit > Paste. You cannot edit
this file.
Saving a Migration Results report

BMC Remedy Migrator automatically saves a Migration Result report on completion of a migration.
You can view the report from the Migration status pane.
After BMC Remedy Migrator performs a migration, the saved Migration Result report appears by
name in the Migration status pane under the Completed tab until you remove it. If the Directories
option is set to the default for migration results, BMC Remedy Migrator also saves the Migration
Result report in the Result Files folder, located in the left pane of the server or file window.
Removing a Migration Result report

1. Open the Migration status pane.
2. Select the Completed tab.
3. Right-click the report you want to remove, and select Delete Migration.
Removing the Migration Result report within the migration status pane also removes the
report from the Result Files folder.
Page 2199 of 4705
Home
Viewing a Migration Result report

1. In the migration status pane, click the Completed status tab to find the migration you are
looking for.
2. Double-click the migration whose report you want to view.
BMC Remedy Migrator generates and displays the Migration Result report. BMC Remedy
Migrator stores migration result reports in a Results File directory, which you can access
from the left pane of the window.
Printing a Migration Result report

When printing a Migration Result report, you can change the report size to fit your paper
dimensions. Select View > Zoom, then enter a percentage to shrink or enlarge the report.
Set the viewing or printing colors in a Migration Result report from the Tools menu under Options.
For information about changing the colors in a result report, see Customizing a Migration Result
report.
You can print a Migration Result report using either of the following methods:
By printing the report in the same format as viewed on your screen
By exporting the report to HTML
To print a Migration Result report

1. Select File > Print in the report window.
2. In the Print dialog box, select a printer.
3. Click OK.
To export a Migration Result report to HTML

1. Select File > Export to HTML.
2. Select a directory path, type a file name, and click Save.
3. Open the saved HTML file in any HTML editor to print, edit, or reformat the report.
Customizing a Migration Result report

You can customize a Migration Result report using the Migration Results options. The Migration
Results category is listed on the left pane of the dialog box.
For migration statistics reports, you can select these migration result options:
Display Specifies which types of objects to show or hide in a report.
Colors Sets the colors for displaying migration results.
Result color options

The result color options enable you to select colors for tables in a Migration Result report.
Page 2200 of 4705
Home
To select color options for Migration Result reports

1. Select Tools > Options to open the BMC Remedy Migrator Options dialog box.
2. Under Category, select Migration Results > Colors.
Result color options
3. For each server object for which you want to change the color:
a. Click the object name.
b. From the color picker that appears, select a color, and click OK.
4. Click OK.
Result display options

The result display options enable you to make a Migration Result report as detailed or as simple as
you like, depending on the type of migration result statistics you need.
To select display options for Migration Result reports

2. Under Category, select Migration Results > Display.
Migration Results display options
Page 2201 of 4705
Home
3. To select the options for each item, click the item name, then select Show or Hide from the
drop-down list.
4. Click OK.
Resolving reported failures

If you see a failure reported after your migration, some might not have migrated properly. To view
migration results, look at the migration status pane or generate a migration result report (see
Migration Result reports).
You can restore the changed objects on a destination server by opening the appropriate BMC
Remedy Migrator backup file (see Backing up destination server) and migrating it to the destination
server.
Reports based on form data

Using the AR System Report Console, which provides a single interface for all reporting functions,
users can create and run nicely formatted reports based on the data stored in AR System forms.
The new Web report type is supported by reporting components that are installed with BMC
Remedy Mid Tier.
In addition, users can use the traditional AR System reports or Crystal Reports, a reporting
package that you can integrate with AR System.
Users can also use the Reporting Console to run existing Web reports, AR System reports, and
Crystal reports, including those defined by others or installed with BMC applications if they have the
necessary permissions.
Page 2202 of 4705
Home
Dependency reports
This section describes how to create, use, and customize Dependency reports.
Creating and using Dependency reports
Working with Dependency reports
Resizing and viewing a Dependency report
Customizing a Dependency report
A Dependency report shows the interdependencies between workflow objects, and helps you
determine which workflow objects are required by a specific workflow object. For example,
Dependency reports determine what should be moved to a production (destination) machine to
ensure that the application is migrated to the correct destination.
The Dependency report is divided first into servers, then direct and indirect dependencies, then into
object types. When creating a report using packing lists, the Dependency report goes outside a
packing list and finds all dependent objects.
A BMC Remedy Migrator Dependency report shows upward or downward object dependencies.
Upward Dependencies Displays a list of objects that require the specified object. For
example, if you generate an upward dependency report for a form, the report lists the active
links, filters, escalations, and other objects that use that form. If you generate an upward
dependency report for groups or roles, the report lists the forms or other server objects that
use those groups and roles.
Downward Dependencies Displays a list of objects that the specified object requires.
When a downward dependency report is created for a form, the objects for that form are not
displayed in the report. When a downward dependency report is created for a form and
related objects, the objects are displayed.
Dependency report example (partial view)
Page 2203 of 4705
Home
The report display lists direct and indirect dependencies for the selected objects:
Direct dependencies include those objects that are required by the object for which the
report is generated. For example, the dependency report for the Administrator Preferences
form lists the menus and groups that comprise the direct dependencies. For a packing list,
direct dependencies would include all of the objects included in the packing list.
Indirect dependencies include those objects required by objects listed in the Direct
Dependency list.
Creating and using Dependency reports

Use the following procedure to create and use the dependency reports.
Page 2204 of 4705
Home
To create a Dependency report

1. Click the object type under BMC Remedy AR System Objects in the left pane of a server
window.
2. In the right pane, select the objects you want to review.
To select more than one object, hold down the Ctrl or Shift key when making your selections.
3. Right-click your selection to display a pop-up menu, or select the View menu.
4. Select Downward Dependencies or Upward Dependencies to display the Dependency report
in a window.
The object dependencies are shown in the default colors or the colors you selected from the
Dependency report options.
Working with Dependency reports

You can view object dependencies before and after a migration to make sure you migrate all
dependent objects and to verify that the correct objects exist on the correct server. You can migrate
from the report view, as well as save or print the report.
In this topic:
Saving a Dependency report
Printing a Dependency report
The following table outlines some techniques to use when working with Dependency reports:
Options for working with Dependency reports

Action
Procedure
Resize a report
Select View > Zoom and enter a percentage to shrink or enlarge the report. This zoom
percentage is also used when printing the report.
Select colors
Select Tools > Options (see Customizing a Dependency report).
Select migration and printing options
Right-click in the right pane of the Dependency report window to display the options
menu.
Refresh dependency report

information
Select the report window and press F5.
Display an object in a report in BMC
Double-click a Migrator file to launch a report from its saved location.
Remedy Migrator
Create an image of the report to view
in another application
Select Edit > Copy. Open the other application and select Edit > Paste. You cannot edit
this file.
Add new object to a report
Drag the object starting at the source view (the server window used to select the
workflow objects).
Scroll to an object in the list view (

right pane)
Select the object name in the tree view (left pane). You can also click an object in the list
view to select the object in the tree view.
Page 2205 of 4705
Home
Saving a Dependency report

1. Right-click the Dependency report you want to save.
2. Select File > Save As to display the Save As dialog box.
3. Select a destination path and type a file name, being sure to save the file as a .mgrtdep file.
4. Click Save.
Printing a Dependency report

When printing an active report, use the zoom percentage to size the report to fit your paper
dimensions. Select View > Zoom and then enter a percentage to shrink or enlarge the report.
For information about changing the colors in a report before printing, see Customizing a
Dependency report.
To print a Dependency report

1. Select File > Print.
2. From the Print dialog box, select a printer, and click OK.
The report is printed in the same format as it is viewed on your screen.
To create an HTML file from a Dependency report

2. Select a directory path where you want the file saved, and enter a file name.
3. Click Save.
Resizing and viewing a Dependency report

When viewing Dependency reports, you can resize the report to fit your workspace. Select View >
Zoom, and enter a percentage to shrink or enlarge the report. If you need more viewing space, hide
the migration status pane.
Objects in the right pane are listed in the same order as they appear in the left pane. In the list view
of the Dependency report, dependent objects are listed in alphabetical order within each server
listing. For migrations, servers are also listed in alphabetical order.
Objects listed in the report as "Unable to locate object objectName on server" and "Object
objectName lies on server. Unable to retrieve information." might be residing on a different server
or might be missing. If there is more than one server referenced in the report, these servers are
listed in alphabetical order.
Customizing a Dependency report

BMC Remedy Migrator uses colors to correlate objects that are dependent on the specified objects.
You can customize a Dependency report by selecting object colors.
Page 2206 of 4705
Home
To select color options for Dependency reports

2. Under Category, select Dependencies > Colors.
Selecting dependencies color options
3. For each object dependency to be correlated (for example, all forms that are dependent on
each other):
a. Click the object type.
b. From the color picker, click the box for the color you want.
c. Click OK.
4. Click OK to save your selections.
Differences reports
Differences reports compare objects between source and destination. You can identify object
differences and migrate all differences, or only specified differences. You can use differences
reports to compare objects between two servers, between a server and a .migrator file, or between
two .migrator files. The Differences report provides the following report views:
Comparison view
Page 2207 of 4705
Home
Object Details view

Related topics
You can switch between the views by clicking the tabs at the bottom of the report.
Comparison view
By default, the Comparison view appears when you create a Differences report. The Comparison
view provides the following information:
Main settings The names of the source and destination file or servers
Created on The date and time the report was created
Total results For the items being compared, the number of objects that are the same, the
number of objects with differences, the number of missing objects, and the total number of
objects being compared.
The remainder of the report provides details about each type of object (for example, regular forms,
vendor forms, or menus). For each object, the report specifies:
Name of the destination object
Results (either the same as the destination or different)
Action required What needs to be done to resolve the differences
Source timestamp and destination timestamp The time stamps for the source and
destination
Destination modified status Whether the destination is newer or the same.
Note
When comparing application objects that contain different workflow objects, the
Differences report does not show differences among those applications. This is because
applications do not actually contain objects in them; they only contain references to those
objects. Applications are standalone objects similar to other BMC Remedy AR System
objects.
Differences Report comparison view
Page 2208 of 4705
Home
Object Details view

The Object Details view lists the details of each object being compared. For objects that have
changed, the name of the user who made the change, and the date and time of the change, are
displayed.
Any change in value of an object property in a view overlay is listed in the Object Details view of the
differences report. The Changed Field List is displayed in the Property List section of the
differences report.
For the fields that were added to the view by using the Add Field To View Overlay menu option,
the differences report lists the field IDs with their changed property values. If a property is added to
a single view, the field ID is listed in the Common display properties for View. If the field was added
to multiple views, the Common display properties for View lists all the changed fields for each view.
Information for the source appears on the left; information for the destination appears on the right.
Page 2209 of 4705
Home
You can change the color settings for the Differences report. See Differences color options.
Differences report Object Details view
Notes
BMC Remedy AR System and BMC Remedy Migrator use field IDs, not field
names, to determine differences between source and destination environments.
For example, if the source form has a field name of Field_ABC, and the destination
form has a field name of Field_XYZ, with the same field ID, BMC Remedy Migrator
replaces instances of the form Field_XYZ with Field_ABC on the destination
server.
Page 2210 of 4705
Home
For objects with a lock type of Hidden, the object details are not displayed.
You can view object differences before and after a migration to make sure you migrate all the
objects correctly. You can also migrate from the report view, and save or print the report.
For information about creating, using, and customizing Differences reports, see:
Creating and using Differences reports
Working with Differences reports
Customizing a Differences report
Differences display options
Differences color options
Mask options
Creating a Detailed Difference Report
Comparing objects in BMC Remedy Migrator
Related topics
Adding a field to a view overlay
Creating and using Differences reports

You can use a Differences report before a migration to see which objects are different and might
need to be corrected. After a migration, you can use the report to verify which objects migrated
correctly.
Note
If some items still show up in the Differences report as separate, verify that the migration
mask options for the issue items have been set correctly.
To review object differences in a new Differences report

1. Open the window or windows from which you want to obtain differences information.
2. Select File > New Differences Window.
A new window appears with a blank Differences report.
3. Select the objects you want to include, and drag them to the new Differences window.
4. In the Destination Type dialog box, select a destination, either a server or a .migrator file.
a. If you select Server, select a server name from the Select Destination Server list. If
you select the same server as your destination server, the Prefix dialog box appears.
Enter a prefix name, and click OK.
b. If you select Migrator file, select a .migrator file from the list that appears.
5.
Page 2211 of 4705
Home
5. To save the Differences report, select File > Save, and enter a file name.
The file is saved as a .mgrdif file.
To review object differences by selecting object types

1. In the left pane of a window, click the object type under BMC Remedy AR System Objects.
2. In the right pane of the window, select the specific objects you want to review.
3. Right-click your selection and select Differences from the menu, or select View > Differences
.
4. Select a destination, either a server or a .migrator file.
a. If you select Server, select a server name from the Select Destination Server list. If
you select the same server as your destination server, the Prefix dialog box appears.
Enter a prefix name, and click OK.
b. If you select Migrator file, select a .migrator file from the list that appears.
The Differences report appears.
5. To save the report, select File > Save, and enter a file name.

In this topic:
Viewing a Differences report
Saving a Differences report
Printing a Differences report
You can use these techniques when working with Differences reports.
Action
Procedure
Customize what a report displays
Select Tools > Options, open the Differences tree view, and select
the Display option.
Resize a report to your screen
Select View > Zoom and enter a percentage to shrink or enlarge

the report. This zoom percentage can also be used when printing
a report.
Select colors for reports
Select Tools > Options. See Customizing a Differences report.
Select migration and printing options
Right-click in the right pane of a Differences report window and

select options from the menu.
Refresh Differences report information
Select the report window and press F5.
Display a previously saved Differences report
Select the saved report from the directory where it is stored, and
double-click to open it.
Create an image of the report to view in another application
Select Edit > Copy. Open the other application and select Edit >
Paste. You cannot edit the copied file.
Add new object to a report
Drag the object from the source server or form detail list view.
Page 2212 of 4705
Home
Action
Procedure
Scroll to an object in the list view (right pane)
Select the object name in the tree view left pane. You can also
click once on an object in the list view to select the object in the
tree view.
Compare objects between servers, between .migrator files,
Right-click the objects and select Differences.
between a server and a .migrator file, or between two

objects on the same server
Put forms and related objects into a Differences report
Select them and hold down the Ctrl key as you drag the objects
into the report.
Navigate between differences and missing items
Click the Previous or Next Differences icons (yellow icons with red
arrows) or Previous or Next Missing icons (yellow icons with blue
arrows) in the toolbar.
Viewing a Differences report

You can change the size of a difference report to fit your workspace.
Select View > Zoom, and enter a percentage to shrink or enlarge the report.
Note
Clicking the Object Details tab does not display anything. To view object details, open the
BMC Remedy AR System Objects left pane and double-click an object to show its detail in
the right pane. This action opens the Object Details tab.
You can look at fields and views all the way to their base level by clicking down into the Report tree
view. Also, right-clicking a field or view from the Report tree view displays a pop-up menu with the
option to Show Object Details. For example, when comparing forms, to view field level differences
in a report, expand the Forms tree view and right-click to select Show Object Details. You can then
double-click a specific field in the list view to see a more detailed set of differences.
Differences report tree view
Page 2213 of 4705
Home
Saving a Differences report

Use the following procedure to save a Differences report
To save a Differences report

1. Right-click the Differences report you want to save.
3. In the Save As dialog box, enter or select a destination path and a file name, being sure to
save the file as a .mgrdif file .
4. Click Save.
Printing a Differences report

When printing an active report, you change the size of the report to fit your paper dimensions.
Select View > Zoom, then enter a percentage to shrink or enlarge the report.
To change colors when viewing or printing a Differences report, select Tools > Options. For
information about changing the colors in a report, see Customizing a Differences report.
You can print a Differences report using either of the following methods:
By printing the report in the same format as viewed on your screen
By exporting the report to HTML
To print a Differences report

1.
Page 2214 of 4705
Home

2. From the Print dialog box, select a printer.
3. Click OK.
To export a Differences report to HTML

2. Select a directory path where you want the file saved, and enter a file name.
3. Click Save.
Customizing a Differences report

The following table lists ways you can customize the display, color, and masking options in a
Differences report.
Customizing options for a Differences report
Option
What it does
Display
Specifies whether to display all objects that are the same, different, or missing.
Colors
Establishes the colors for differentiating between objects. The default colors are:
Green--objects that are the same
Red--objects that are different
Blue--Objects missing on the destination
Gray--table headers
Masks
Specifies which object properties are to be compared when generating, viewing, or printing a Differences report.
Differences display options

Using the Differences display options, you select which objects to display in a Differences report.
The default setting for the display options is set to all options checked.
To select display options for Differences reports

1. Select Tools > Options to display the BMC Remedy Migrator Options dialog box.
2. Under Category, click Differences, and select Display.
Differences report display options
Page 2215 of 4705
Home
3. Select which objects to display:

All objects that are the same
All different objects
All missing objects
4. Click OK.

You can select the colors for comparing objects in a Differences report.
To select color options for Differences reports

2. Under Category, open the Differences and select Colors.
3. For each object difference category, click the arrow to the right of the color box and select a
color, or accept the default colors shown:
Green for displaying all objects that are the same.
Red for displaying all different objects.
Blue for displaying all missing objects.
Gray for tables.
4. Click OK.
Page 2216 of 4705
Home
Mask options
Mask options enable you to specify object properties that are compared when generating, viewing,
or printing a Differences report. If the option is enabled for an object property, it is compared in the
Differences report; if disabled, the object property is not compared and appears as the same in the
Differences report.
Note
If the mask option for an object property is disabled, the detailed Differences report
displays the header for that property group in green color regardless of the actual
difference in the value of that property. Even though the mask option for that object
property is disabled, a red X symbol is displayed against the property if its values differ,
otherwise a green check mark is displayed.
If you change the options while a report is open, you can refresh the report display by pressing F5.
You can synchronize the Differences report mask settings so that they match those for migration
mask settings.
To select mask options in Differences reports

2. Under Category, click Differences, and select any of the object types listed in the following
table to display the Differences mask options.
Options for comparing preferences for Differences reports
Select this option
To compare
Forms
Form properties (Opens field and view properties.)
Fields
Field properties
Views
View properties
Active Links
Active link properties
Filters
Filter properties
Escalations
Escalation properties
Containers
Application, guide, packing list, and web services properties (including application
state)
Menus
Character menu properties
Distributed Maps
Distributed maps properties
Note
BMC Remedy Migrator does not migrate DSO fields, only DSO maps.
Page 2217 of 4705
Home

Select this option
To compare
Plug-in modules
Properties of plug-in modules
Plug-in definitions
Plug-in definitions
Distributed Pools
Pools (threads) pending distributed operations
Flashboards Flashboards Data

Sources Flashboards Variables
Flashboards Alarms
Flashboards, Flashboards data source, Flashboards variable, and Flashboards

alarm properties (depending on whether you own and have installed the BMC
Remedy Flashboards 5.0 or later)
3. Select the object properties that you want to compare on the report.
To change an option, click the name, and select Enabled or Disabled from the drop-down list
.
4. Click OK.
To set the Mask options back to the BMC Remedy Migrator defaults, click Set Default. To
cancel your changes, click Cancel.
Note
There are no separate masking options for the field property changes made in a
view overlay. The masking options set for the Views > Property List are inherited by
the field properties in a view overlay.
To synchronize settings with migration mask settings, click Synchronize Migration Masks.
Page 2218 of 4705
Home
Creating a Detailed Difference Report

From the comparison of two sets of objects, even on different servers or in different files, BMC
Remedy Migrator can create a report that specifies only the differences that are not permitted in
overlays. The report filters all differences that are legal for BMC Remedy Migrator to migrate or
differences that need an overlay created.
A difference that is not permitted in an overlay is a change to a property of the origin object. Such a
property change must be resolved before it can be migrated.
You can compare objects by mapping the origin objects on the source server (or file) to the overlay
objects on the destination server (or file), or by mapping the overlay objects on the source server (
or file) to the origin objects on the destination server (or file).
To create a Detailed Difference Report

1. In the tree view in the left navigation pane, select the root node (server name) or select items
in the objects list, and right-click.
Note
When you select the root node, all objects on the server are used to create the
report. When you select a set of items from the objects list, only those selected
objects are used.
2. From the menu, select Differences Not Permitted on Overlays > Select Destination and
continue with this step, or select a server from the server list and skip to step 3.
If you select Differences Not Permitted on Overlays > Select Destination , a Destination
Type dialog box appears that enables you to select either Server or Migrator File to use for
the object comparison.
If you selected Server, perform the following steps:
a. In the Login dialog box, enter the password for the current user.
b. From the server list, select a server.
If you selected the root node in step 1, browse and select an existing
BMC Remedy Migrator instruction file from the Detailed Difference
dialog box.
The instruction file provides a list of objects for which to generate a
detailed difference report.
In the Detailed Difference dialog box, click Generate Difference Report
.
Page 2219 of 4705
Home
If you selected a set of items from the objects list in step 1, in the
Source - Destination Mapping dialog box, select either Map Origin To
Overlay or Map Overlay to Origin, and then click OK. (If you click OK
without selecting a map type, the report is created by mapping Overlay
to Overlay or Origin to Origin.)
If you selected Migrator File in step 2, perform the following steps:
a. In the browse dialog box, browse and select an existing .migrator file.
b. Select the source-destination mapping method to use for the report, either Map
Origin to Overlay or Map Overlay to Origin, and click OK. (If you click OK
without selecting a map type, the report is created by mapping Overlay to
Overlay or Origin to Origin.)
A new Differences Not Permitted in Overlays report based on the current
server and the .migrator file contents is created.
3. If you selected a server from the list in step 2, browse to and select an instruction file to
provide a list of objects for which to generate the detailed difference report, and click
Generate Difference Report.
Note
The report is generated in the .csv and .xml formats.
Comparing objects in BMC Remedy Migrator

Using BMC Remedy Migrator, you can perform the following comparisons of origin and overlay
objects:
Compare overlay objects at the source with origin objects at the destination
Compare origin objects at the source with overlay objects at the destination
Compare origin objects with overlay objects on the same server
To compare objects in BMC Remedy Migrator

1. In the objects list, select one or more items, and right-click.
2. From the menu, select Differences > Select Destination.
3. In the Destination Type dialog box, select the option to use for the object comparison:
Server: Perform the following steps:
a. In the Login dialog box, enter the password for the current user.
b. From the server list, select a server.
c. In the Source - Destination Mapping dialog box, click either Map Origin To
Overlay or Map Overlay to Origin, and then click OK to generate the
comparison report.
Migrator File: Perform the following steps:
a.
Page 2220 of 4705
Home
a. In the browse dialog box, browse and select an existing .migrator file and click
Open.
b. In the Source - Destination Mapping dialog box, click either Map Origin To
Overlay or Map Overlay to Origin, and then click OK to generate the
comparison report based on the current server and the .migrator file contents.
To create a Migrator Instruction file to use for comparison

1. In the objects list, select one or more items, and right-click.
2. From the menu, select Create Instruction File.
3. (Optional) Select the source-destination mapping method to use for the report:
Map Origin to Overlay
Map Overlay to Origin
4. In the Save As dialog box, specify a file and location, and save the instruction file.
Enabling social collaboration in BMC Remedy

AR System
The following social collaboration features enable you to use Twitter and RSS feed clients to
receive alerts and feeds respectively, and also provides guidelines for using and resolving issues
with chat.
Alerts through Twitter As an administrator, you can configure a twitter account to
receive any specific alerts as tweets. For more information about receiving alerts through
Twitter and mapping a user to a twitter account, see Receiving alerts through twitter.
RSS feeds As an administrator, you can define or publish RSS feeds that allows end
users to consume those feeds from within the RSS feed clients. For more information about
configuring the RSS feed and subscribing to RSS feeds, see Configuring RSS feeds.
Chat option When resolving an incident, you can discuss the issue with one or many
people using the chat option. You also have the option to save the chat conversation and
continue to work on the issue later. For more information about using and configuring the
chat option, see Configuring Chat.
Receiving alerts through Twitter
Configuring RSS feeds
Configuring chat
Receiving alerts through Twitter

Consider the following example:
Amy is a BMC Remedy AR System user who wants to receive alerts through a Twitter account.
Page 2221 of 4705
Home
Amy first creates a Twitter account. She then logs on to the BMC Remedy AR System server as an
administrator and makes sure that the Notify action in BMC Remedy Developer Studio is set to
Alert. Using the new AR System Alert Twitter User Authorization form, Amy maps her user name to
her twitter account. Amy starts receiving alerts through Twitter.
1. If you do not already a Twitter account, create one.
Every user who wants to receive alerts through Twitter, must have a Twitter account.
Note
If you are configuring Twitter, you must have administrative rights.
2. Make sure that the Notify action in BMC Remedy Developer Studio is set to Alert.
For more information, see Notify action.
3. As an administrator, map the user to a Twitter account in BMC Remedy AR System.
For more information, see Mapping the user to a Twitter account .
You can now receive BMC Remedy ITSM Suite alerts through your Twitter account. For more
information, see Receiving BMC Remedy ITSM Suite alerts .
Mapping the user to a Twitter account
Configuring the proxy server settings
Configuring to receive BMC Remedy ITSM Suite alerts
Mapping the user to a Twitter account

This topic provides instructions for mapping the user to a Twitter account.
Follow the steps in this section only if you have not installed BMC Remedy ITSM. If you have
installed BMC Remedy ITSM, follow the steps in the Configuring the Twitter integration section.
Note
Ensure that internet connectivity is available on the computer where you are mapping the
user to a Twitter account and also on the computer where the plug-in server is running.
Additionally, ensure that access to the Twitter account from BMC Remedy AR System is
not blocked by any firewall.
Page 2222 of 4705
Home
To map the user to a Twitter account

1. Log on to BMC Remedy AR System as an administrator and open the AR System Alert
Twitter User Authorization display-only form.
AR System Alert Twitter User Authorization form
2. In the User Name field, select the user for mapping to a Twitter account.
AR System Alert Twitter User Authorization form fields
Field name
Description
User Name
The menu lists the users from the BMC Remedy User form.
Note
If the user information is on an LDAP directory, the user name can be entered manually.
Access Key
This is a read-only field. The value is automatically displayed when you enter a pin number in the
PIN field.
Access Token
Secret
This is a read-only field. The value is automatically displayed when you enter a pin number in the
PIN
This field is activated only if the user is not already mapped to an existing Twitter account.
PIN field.
3. If the user has not been mapped to a Twitter account, the Twitter page opens:
Note
If the AR Server system clock is not synchronized with your time zone, Twitter
displays the following error message:
Error in plugin : 401:Authentication credentials (http://
dev.twitter.com/pages/auth) were missing or incorrect. Ensure
that you have set valid conumer key/secret, access token/
secret, and the system clock in in sync. Failed to validate
oauth signature and token Relevant d (ARERR 8753)
Synchronize the system clock with your time zone, and click Apply.
Page 2223 of 4705
Home
a. Enter the Twitter user name and password.

b. Click OK.
4. Enter the authorization PIN number displayed on the web page in the PIN field.
Note
If the user is already mapped to a Twitter account, the PIN field remains
deactivated. No further action is required.
With Twitter4j API, the user gets only one chance to enter correct PIN in the first
attempt. If the user enters the wrong PIN in the first attempt, that PIN expires and
the user has to generate a new PIN. For more information, see https://
dev.twitter.com/discussions/18138 (http://www.mail-archive.com/
twitter-development-talk@googlegroups.com/msg09097.html).
The values for the Access Key and Access Token Secret fields are automatically
displayed.
5. Click Apply.
An entry is created in the AR System Alert User Registration form. For more information about this
form, see Registering users for alerts. The mapping is now complete.
Configuring the proxy server settings

For Twitter notifications to work correctly, it is necessary to have internet access to Twitter and
Twitter4j websites from the client computer and from the computer where AR plugin server is
running. If your organization does not provide direct internet access, the requests will be routed
through a HTTP/HTTPS proxy server. In this case, the required proxy information must be provided
during configuration in the new AR System Proxy Server Settings form that can be accessed
through BMC Remedy Mid Tier.
Fields in AR System Proxy Server Settings form

Fields
Description
AR Server
Fully-qualified name (FQDN) of the computer where AR plugin server is running.
Proxy Server Host
Name or IP address of the HTTP/HTTPS proxy server that allows connection to the internet.
Proxy Server Port
The proxy server port number.
Proxy Server User Name
(Optional) If the login credentials are required to connect to the proxy server.
Proxy Server Password
(Optional) If the login credentials are required to connect to the proxy server.
Note
Page 2224 of 4705
Home
Only one entry must be made in this form for one BMC Remedy AR System server. If
multiple entries are made, any one of those entries may be picked up by the Twitter
plug-in.
Configuring to receive BMC Remedy ITSM Suite alerts

This topic provides instructions for configuring to receive BMC Remedy ITSM Suite alerts through
your Twitter account.
To receive BMC Remedy ITSM Suite alerts
Note
Before you begin, follow the steps given in the Receiving alerts through Twitter section.
1. Click the Twitter button provided on the BMC Remedy ITSM landing console for:
BMC Service Desk
2. Follow additional configuration steps in Receiving BMC Remedy ITSM broadcasts on Twitter
.
Note
To display the Twitter button on the BMC Remedy ITSM landing console, see Enabling
chat, Twitter notifications, and RSS feeds .
Configuring RSS feeds

Steven is an administrator who works in the IT department of a company. He wants to subscribe to
RSS feeds so that his entire team can receive RSS feeds through the RSS feed clients. He logs in
and configures RSS feeds by using the AR System Feed Definition form. Steven then selects the
required links from the mid tier and copies the link to his favorite RSS feed client. He and his team
now start receiving RSS feeds through that RSS feed client.
Page 2225 of 4705
Home
Prerequisites
You must configure the mid tier to make sure that the Fully Qualified Domain Name (FQDN) is
specified for the AR System server name. To do this, open the BMC Remedy Mid Tier
Configuration Tool and click AR Server Settings. Make sure that the domain name is specified for
the AR Server Name.
For more information about configuring the AR Server Settings, see Configuring the AR Server
Settings page.
Notes
If the domain name is not specified for the AR Server Name, an internal error is displayed
when you try to access RSS Feed.
If an internal error is displayed even after specifying the correct domain name in the mid
tier, check the entry in the AR System Server to Key Map form. The entry in this form
must be a FQDN of the AR Server Name, the same as configured in the mid tier. If there
is a mismatch, correct the entry in the AR System Server to Key Map form to match the
value in the mid tier. Make sure that the FQDN of the remote AR System server can be
resolved using the Domain Name System (DNS) from the central mid tier server and from
the remote mid tier server.
If you are running a server group with a load balancer, make sure that the entry in the AR
System Server to Key Map form matches the load balancer server name that is provided
in Mid Tier Configuration Tool.
If you are running a server group without a load balancer (that is, both the primary and
secondary AR servers are added in the Mid Tier Configuration Tool), make sure that there
are two entries in the AR System Server to Key Map form. An entry for the primary AR
server is already created during installation. Make a copy of that entry for a secondary AR
server, changing only the Server Name to match the mid tier configuration. If there are
more secondary servers, you must create additional entries for those secondary servers.
To enable RSS feeds

1. Open the AR System Feed Definition form and enter the required information, and save the
form.
For more information, see Defining RSS feeds through the AR System Feed Definition form .
Note
Page 2226 of 4705
Home
If you are configuring RSS feeds, you must have administrative rights. However, to
which RSS Feeds a user can subscribe to depends on the subscribers who are
listed in the permitted subscribers list.
2. As an administrator, subscribe to the RSS feeds.

For more information, see Subscribing to RSS feeds.
You can now receive BMC Remedy ITSM Suite RSS feeds through RSS feed clients. For
more information, see Receiving BMC Remedy ITSM Suite feeds .
Defining RSS feeds by using the AR System Feed Definition form
Subscribing to RSS feeds
Configuring to receive BMC Remedy ITSM Suite feeds
Defining RSS feeds by using the AR System Feed Definition form

This topic provides instructions for defining RSS feeds by using the AR System Feed Definition
form.
To define RSS feeds

1. Log on to the BMC Remedy AR System as an administrator and open the AR System Feed
Definition form.
2. On the Feed Definition tab, provide the required information to define the RSS feed.
AR System Feed Definition Form, Feed Definition tab
AR System Feed Definition form, Feed Definition tab fields
Page 2227 of 4705
Home
Field name
Description
Status
Shows the status of the RSS feed, which can be one of the following values:
Draft Work in progress.
Active Ready for use.
Mark as Deleted Not available for use.
Feed Name
Enter the name of the RSS feed.
Description
Provide a description of the RSS feed.
Server
Specify the BMC Remedy AR System server name from which you want to receive RSS feeds.
Note: If you want to receive RSS feeds from remote BMC Remedy AR System servers, add those server
names using this field. Ensure that these remote servers are added to mid tier and that you specify the
same names. If this field is left blank, RSS feeds are generated from the local server.
Form
Specify the BMC Remedy AR System form from which you want to receive the RSS feed.
Article Title
Specify the title of the RSS feed, also known as, an article.
Article
Description
Provide a description of the RSS feed.
Qualification
Specify the qualification criteria for the RSS feed.
Sort By
Specify sorting criteria for RSS feeds.
Retain for (
seconds)
Specify the number of seconds you that want to retain the RSS feed before updating the feed. The
default value is 900 seconds.
Permitted
Subscribers
Specify groups who want to receive the RSS feeds.
Drill Down
VUI
Specify the name of the view for the form from which you want to receive the RSS feed.
Request ID
Request ID.
Submitter
Submitter name.
Create Date
Date of creation.
Assigned To
Name of the person to whom the RSS feed has been assigned.
Last
Modified By
Name of the person who last modified this form.
Modified
Date
Last modified date.
Force
Refresh
Disregards the Retain for (seconds) field value. Every time a request is raised, the mid tier retrieves the
information from the BMC Remedy AR System server.
Note: This might impact the BMC Remedy AR System server.
3.
Page 2228 of 4705
Home
3. Save the form.
Subscribing to RSS feeds

This topic provides instructions for subscribing to RSS feeds.
To subscribe to an RSS feed

1. Click the following link:
http://<MidtierServer>:<MidtierPort>/arsys/plugins/feeddvm/params?server=<
ServerOnWhichYouHaveConfiguredRSSFeed>&user=Demo&pwd=&action=display
For example:
2. In the password dialog box, enter your password and authentication string (if any):
Password for RSS feed
3. From the list of displayed links, right-click the link and copy the link to any RSS feed client.
For example, see the following image:
Links for RSS feeds
You are now subscribed to receive RSS feeds through the RSS feed client.
Page 2229 of 4705
Home
Configuring to receive BMC Remedy ITSM Suite feeds

This topic provides instructions for configuring to receive BMC Remedy ITSM Suite feeds through
RSS feed clients.
To receive BMC Remedy ITSM Suite feeds
Note
Before you begin, follow the steps given in the Configuring RSS feeds section.
1. Click the RSS Feed button provided on the BMC Remedy ITSM landing console for:
BMC Service Desk
2. Follow the additional steps mentioned in Subscribing to RSS feeds.
Note
To display the RSS Feed button on the BMC Remedy ITSM landing console, see
Enabling chat, Twitter notifications, and RSS feeds .
Configuring chat
Jack is assigned a ticket and he is not sure what he needs to do to resolve the ticket. Because Jack
has administrative rights, he installs and configures a chat server so that he can get immediate
answers. He configures the BMC Remedy AR System server to work with the chat server and
maps the required BMC Remedy AR System users to the chat server. By using the chat window,
he then invites his colleagues to discuss the issues mentioned in the ticket. After getting the
answers, he resolves the ticket.
1. Install and configure a chat server.
For information about installing and configuring the Openfire chat server, see Installing and
configuring the Openfire chat server.
Note
Page 2230 of 4705
Home
Any Extensible Messaging and Presence Protocol (XMPP) compliant chat server
can be used as a chat server. As a convenience, BMC has provided a validated
example of this integration utilizing the Openfire chat server for customers who
want to use this option.
2. Configure the BMC Remedy AR System server to work with the chat server.
For more information, see Configuring the BMC Remedy AR System server to work with the
chat server.
3. Map the BMC Remedy AR System users to the chat server.
For more information, see Mapping the BMC Remedy AR System users to the chat server .
4. Start a chat conversation.
For more information, see Starting a chat conversation.
5. Add BMC Remedy AR System users who are not present in the Friends list.
For more information, see Adding BMC Remedy AR System users not present in the Friends
list.
Installing and configuring the Openfire chat server
Configuring the BMC Remedy AR System server to work with the chat server
Mapping the BMC Remedy AR System users to the chat server
Starting a chat conversation
Adding BMC Remedy AR System users who are not present in the Friends list
Chat notifications
Using the chat option through BMC Remedy ITSM Suite
Section 508 support for chat
Installing and configuring the Openfire chat server

This topic provides instructions for installing and configuring the Openfire chat server.
Prerequisites
To configure the Openfire database
To configure the Openfire chat server to work with BMC Remedy AR System server
Prerequisites
Download the latest Openfire installer from http://www.igniterealtime.org/downloads. Ensure that
Openfire is installed and functional before proceeding to the following section.
For documentation related to Openfire, see http://www.igniterealtime.org/projects/openfire/
documentation.jsp.
Note
Page 2231 of 4705
Home
Openfire is an independent component of BMC Remedy AR System and is not directly

coupled with a specific AR System component such as the AR System server or the mid
tier. Therefore, you can install Openfire on any computer. You can either install it on the
mid tier computer, AR System server computer, or on an independent computer. However
, as the Openfire server can be directly accessed from the user's browser, it is good to
install it on the mid tier computer.
If you have a single server or a server group setup, only one instance of Openfire needs
to be installed. Openfire service is not fail-safe and hence only a single instance is
required and supported.
To configure the Openfire database

The following procedure provides instructions for configuring the Openfire database:
1. Manually create the database. For more information, see the Openfire Database Installation
Guide.
Note
BMC recommends that you create a new database with new database users (for
example, openfire) instead of creating Openfire database tables in the BMC
Remedy AR System database.
2. (For Oracle database only) When using Oracle database for Openfire, the following error is
displayed in the Openfire logs:
org.jivesoftware.openfire.group.Group - ORA-01400: cannot insert
NULL into ("SYSTEM"."OFGROUPPROP"."PROPVALUE")
java.sql.SQLException: ORA-01400: cannot insert NULL into ("SYSTEM".
"OFGROUPPROP"."PROPVALUE")
This error occurs because the Oracle database treats the empty string as NULL and the
default OfGroupProp table PROPVALUE column setting is NOT NULL. To resolve this
issue, alter the table to allow NULL values as shown in the following figure:
NULL values
Page 2232 of 4705
Home
3. After the installation is complete, start the OpenFire server using one of the following options
:
Navigate to the OpenfireInstallDir/bindirectory and run one of the following files:
For Microsoft Windows openfire.exe
For Linux openfire
OR
Create the Openfire service as per the instructions given in the Openfire Installation
Guide and start the service.
To configure the Openfire chat server to work with BMC Remedy AR System server
1. Open the Openfire Administration Console (default location http://127.0.0.1:9090) and follow
the setup steps given below in the Setup wizard:
a. Choose the language.
This setting is only for setting the language for web-based administration portal and
not for messaging.
b. Under Server settings, provide the host name where Openfire is installed and enter
the appropriate values for the ports.
Make sure that the Openfire host name is the same as the XMPPServerName
property specified during the Configuring the BMC Remedy AR System server to work
with the chat server procedure.
Note
The Server Name specific to Server Properties in Openfire Server
Information page must be either fully qualified server name or an IP
address which is accessible from any client browser.
To change the Server Name, perform the following steps:
Page 2233 of 4705
Home
1. Open the Openfire Server Information page.

2. Select Server Properties.
3. Click Edit Properties, to change the server name.
The Server name should also be changed in Data Visualization Definition
form to match the change exactly.
Ensure that you restart the Openfire Server after you finish editing the
Openfire Server Information page.
c. Under Database Settings, choose Standard Database Connection. Select the

database name created in step 3 above from the drop-down menu for the Database
Driver Presets field and enter the JDBC connection settings and the database user
settings.
For example, if the server is MS SQL server and it is hosted on ofserver, that is, the
same host name as that of the DB name ( openfire) and the DB user (ofuser), the
values would be:
Database Driver Presets: 'Microsoft SQLServer'
(Automatically populated once preset is selected) JDBC Driver Class:
net.sourceforge.jtds.jdbc.Driver
(Provide the hostname:port and the database name ) Database URL: jdbc:jtds
:sqlserver://DatabaseServer:1433/openfire;appName=jive
Username: ofuser
Note
The remaining values can be changed according to your requirement.
2. Under Profile Settings, choose the Default option.

3. Under Administrator Account, enter a valid password for the user admin.
The Openfire chat server configuration is complete.
Configuring the BMC Remedy AR System server to work with the chat server
This topic provides instructions for configuring the BMC Remedy AR System server to work with the
chat server:
Note
Make sure that you are configuring a separate chat server for every BMC Remedy AR
System server.
Page 2234 of 4705
Home
This section also contains information about:

Configuring the Openfire server in a reverse proxy environment
Encrypting chat communications
To configure the BMC Remedy AR System server to work with the chat server
1. Open the Data Visualization Definition form.
2. Select the ChatConfig Definition Name and manually modify the information in the Simple
Definition field.
a. The description of the required definition properties are:
XMPPServerName Name of XMPP server, that is, the Openfire server name
.
useHTTP If you want to connect to the chat server via HTTP or HTTPS, set
the value to true. You must specify the appropriate port number for HTTP or
HTTPS connections in the XMPPServerPort property.
XMPPServerPort Port number to be used for connecting to the chat server
. If the connection is not over HTTP, usually the port number is 5222. For
HTTP or HTTPS connections, the default values are 7070 and 7443
respectively. These numbers may vary depending upon the actual setup.
XMPPPortIsSecure Whether the connection to the chat server must be
encrypted or not. This property must be set to true for HTTPS connections. For
non-HTTPS connections, you can set this value as either true or false. For
more information, see Encrypting chat communications.
XMPPServerHasARAuthPlugin Whether the XMPP server has the AR
Authentication plugin installed. For more information, see Mapping the BMC
Remedy AR System users to the chat server .
autoCreateChatUserMapping The Openfire user names must follow
special rules, such as having no space or the user name consisting of
lowercase letters. All BMC Remedy AR System user names might not always
comply with the naming convention of the Openfire server. When this property
is set to true, the BMC Remedy AR System user name is automatically
converted to the Openfire compliant name, by removing spaces and
unnecessary characters. This converted user name is then used to log on to
the Openfire server. The entry of the corresponding converted name is created
on the AR System Chat User Mapping form in the Chat ID field. If you want to
login to the OpenFire server using third party clients such as Pidgin or Spark,
use the converted chat ID from the AR System Chat User Mapping form. For
more information, see Mapping the BMC Remedy AR System users to the chat
Page 2235 of 4705
Home
server.
For example:
The typical values for using the Openfire server through HTTP are:
XMPPServerName=<Openfire Server Name>
useHTTP=true
XMPPServerPort=7070
XMPPPortIsSecure=false
XMPPServerHasARAuthPlugin=true
autoCreateChatUserMapping=true
The typical values for using the Openfire server through non-HTTP are:
XMPPServerName=<Openfire Server Name>
useHTTP=false
XMPPServerPort=5222
XMPPPortIsSecure=false
XMPPServerHasARAuthPlugin=true
autoCreateChatUserMapping=true
Note
For XMPPServerName, provide the name of only one server in the
server group that is configured as the chat server and not the Load
Balancer alias name.
b. The following is the description of the optional properties that are not available in the
Simple Definition field by default. However, you can add them explicitly to
troubleshoot any issues with chat:
debug Set this property to "true" to enable the client side Flash logging and
any messages traced through Flash plugin of the chat component that are
logged on the client side, that is, on the machine where the browser is running.
Note that the debugger version of Adobe Flash player plugin is required in the
browser for the logging to work. This plugin can be obtained from the Adobe
website. These messages are typically stored in a file path defined in the
mm.cfg file within the user's profile.
debug_midtier Similar to the debug property, set this property to "true" to
enable the client side Flash logging. However, in this case, all the messages
are logged in the midtier log files if the midtier settings have the Log Category
Page 2236 of 4705
Home
enabled for the Data Visualization field and the Log Level is set to "Fine".
For example:
The typical values for using the Openfire server through HTTP are:
debug=true
debug_midtier=true
3. Save the Data Visualization Definition form and restart mid tier.
4. In BMC Remedy Developer Studio, on any BMC Remedy AR System regular form, add a
Data Visualization field.
5. Go to Display properties for that field and specify the Module type as Chat.
6. Save the form and open the form in mid tier.
The following Chat information is displayed on the form:
Chat icon on a regular form
Chat icon Displays the status of the user. For example, Online (green), Busy (red), Away (yellow
), or Offline (white). This Chat icon also has animation to display notifications.
Chat drop-down on the regular form
Drop-down icon Opens a drop-down menu that can be used to perform the following actions:
Change status
View and respond to new notifications
Open or focus on running conversations
Note
For BMC Remedy ITSM Suite, a Chat icon is provided on the BMC Remedy ITSM
landing console. For more information, see Using the Chat option through BMC
Remedy ITSM Suite.
Page 2237 of 4705
Home
Configuring the Openfire server in a reverse proxy environment

If you are using a reverse proxy setup for accessing an application, you need to add some rules to
the reverse proxy configuration so that the HTTP traffic for chat is correctly re-directed. The
example in this topic shows the configuration of the Openfire server when configuring reverse proxy
for the Apache server.
To configure the Openfire server for reverse proxy

1. Add the following entries in the Apache httpd.conf file:
ProxyPass
/crossdomain.xml
http://:port/crossdomain.xml
ProxyPassReverse
/crossdomain.xml
http://:port/crossdomain.xml
ProxyPass
/http-bind/
http://:port/http-bind/
ProxyPassReverse
/http-bind/
http://:port/http-bind/
2. Modify the ChatConfig entry as follows:

XMPPServerName = <The HTTP server name>
XMPPServerPort = 80 (for HTTP) OR 443 (for HTTPS)
XMPPPortIsSecure = false (for HTTP) OR true (for HTTPS)
In such cases, the browser communicates with the Openfire server using the http server
name and not the OpenFire server name.
3. Make sure that the host name specified in the Openfire configuration is changed to match
the name that the browser uses to access the server:
a. Open the Openfire Administration Console (default link is http://:9090) and login as an
administrator.
b. On the Server Information page, scroll down and click Edit Properties.
c. Enter the server name in the Server Name field and click Save properties.
d. Restart the Openfire server.
4. After the Openfire server host name is changed, add the proper certificates to the Openfire
server for that domain name.
For more information, see the Openfire SSL Guide (http://www.igniterealtime.org/projects/
openfire/documentation.jsp).
Note
To generate self-signed certificates for the changed domain name, go to .
Page 2238 of 4705
Home
Encrypting chat communications

When the chat connections are not secure, the plain text messages that are exchanged between
the browser and the chat server can be read by a person who is wire-tapping. This happens when
the XMPPPortIsSecure property is set to false. For more security and for encrypting the
communication, set the value of the XMPPPortIsSecure property to true.
For secure HTTP communication, set the value of the useHTTP and XMPPPortIsSecure
properties to true and the value of the XMPPServerPort property as the HTTPS port number of the
chat server (this value is usually 7443).
Note
When using HTTPS for chat, make sure that BMC Remedy Mid Tier is also running under
HTTPS.
For secure non-HTTP communication, set the value of the useHTTP property to false and the value
of the XMPPServerPort property to the TCP port of the chat server (this value is usually 5222 for
the Openfire server).
Ports used by the Openfire chat server

By default, the Openfire server communication is done on ports 5222, 5223, 7070, or 7443. When
you have a firewall, make sure that the communication is allowed for these ports for the Openfire
server.
Mapping the BMC Remedy AR System users to the chat server

There are two ways to map the BMC Remedy AR System users to the chat server:
To use the Openfire AR Authentication plugin (arauth.jar) for mapping
To use the AR System Chat User Mapping form for mapping
To use the Openfire AR Authentication plugin ( arauth.jar ) for mapping

The Openfire AR Authentication plugin allows BMC Remedy AR System users to get authenticated
automatically on the Openfire server.
Follow the steps given below to install the Openfire AR Authentication plugin:
1. Stop the Openfire process.
2. Go to https://communities.bmc.com/communities/docs/DOC-19158 and copy the arauth.jar
file to the OpenfireInstallDir/lib directory.
Note
Page 2239 of 4705
Home
The BMC Remedy AR System Authenticator Plugin is tested with Openfire

3.7.1.
If you are using Openfire 3.9.x version or later, and if you have issues with
the Status Display of the users, perform the following steps.
Steps (Click here to expand)
a. On the Openfire Admin console (typically available at http://
127.0.0.1:9090/), login as an administrator.
b. Navigate to User/Groups > Groups and click BMC Remedy AR
System Users link.
c. On the Contact List (Roster) Sharing, select Enable contact list
group shared.
d. On the Enter contact list group name field, enter BMC Remedy AR
System Users and click Save Contact List Settings.
e. Stop the Openfire server.
f. Start the Openfire server.
3. Copy the arapi<version-number>.jar, and the arutil<version-number>.jar files from <mid

tier installation directory>\WEB-INF\lib to the OpenfireInstallDir/lib directory.
4. Start the Openfire Server.
5. Open the Openfire Administration Console (http://<hostname>:9090) and then select Server
> System Properties.
a. Click the Edit icon for the provider.auth.className property and change the
value to org.jivesoftware.openfire.auth.HybridAuthProvider
b. Click Save Property and add the following properties under the Add new property
section:
Name: hybridAuthProvider.primaryProvider.className
Value: org.jivesoftware.openfire.auth.DefaultAuthProvider
Name: hybridAuthProvider.secondaryProvider.className
Value:
com.bmc.arsys.social.chat.openfire.auth.ARAuthProvider
c. (When using third-party applications) To connect to the Openfire server on behalf of
BMC Remedy AR System user, add the following AR Server entries under the Add
new property section:
Name: arsProvider.password.<ARServerName>
Value: <Remedy-App-Service-Password property value in the
ar.cfg file of that server>
Name: arsProvider.port.<ARServerName>
Value: <ARServerPortNumber>
Note
Page 2240 of 4705
Home
You can add multiple servers if you are using the same Openfire
server for other BMC Remedy AR System servers.
6. Stop and restart the Openfire server and ensure that you are able to log on to Openfire
Administration Console using Openfire admin credentials. Then, log on to Openfire server by
using the BMC Remedy AR System user name and password with external chat clients. For
example, pidgin.
Note
If the Openfire server has installed this AR Authentication Plugin, change the value
of the XMPPServerHasARAuthPlugin property to true in the ChatConfig
Definition Name as specified in the Configuring the BMC Remedy AR System
server to work with the chat server section.
Tip
If you are unable to log on to the Openfire Administration Console using Openfire
administrator credentials, try the following step to resolve the issue. Log on to the
database which you have configured with the Openfire server and open the
ofProperty table. Change the value of propValue column to
org.jivesoftware.openfire.auth.DefaultAuthProvider in the row where name
column value is provider.auth.className. After making these changes, log on to
the Openfire Administration Console using Openfire admin credentials and carefully
examine existing properties from step 5 above and make necessary corrections.
To use the AR System Chat User Mapping form for mapping

Using the AR System Chat User Mapping form, you can create the Openfire users manually (or use
existing users) and map them to the BMC Remedy AR system users. The mapped user is used to
log on to the Openfire server.
Note
When BMC Remedy AR System users are mapped to the Openfire users, do not install
the AR Authentication plugin on the Openfire server.
1. For mapping the BMC Remedy AR System user names that are not XMPP compliant to the
Chat user names, open the AR System Chat User Mapping form in a browser.
Page 2241 of 4705
1.
Home
Note
The user names that do not contain spaces, capital letters, or a combination of
letters from a to z and numbers from 0 to 9 are XMPP compliant. For the BMC
Remedy AR System user names that are not XMPP complaint, provide the
appropriate XMPP compliant user name, so that this mapped user name can be
used for logging on to BMC Remedy AR System from external clients.
2. Provide the required information in the AR System Chat User Mapping form as follows:
AR System Chat User Mapping form fields
Field name
Description
AR User ID
Manually type the BMC Remedy AR System user ID.
Note
Ensure that the ID is a valid XMPP ID that contains no white spaces and consists of only a-z
lowercase letters and 1-9 digits.
Chat User
ID
The chat server user ID.
Chat
The chat user password.
Password
Chat
Provider
A reference field for future use. For the current version, set the value to Openfire (or any other XMPP chat
server that you are using).
3. Save the form.

Before starting a chat conversation, you should have already performed the steps from the
Configuring the BMC Remedy AR System server to work with the chat server section.
To start a chat conversation

1. Click the Chat icon to open the Start Conversation window.
Start Conversation window
Page 2242 of 4705
Home
2. Select the required users from the Friends list and click the Start Conversation icon.
3. On the Conference window, type in the message to start chatting.
Conference window
Page 2243 of 4705
Home
4. (Optional) Click the Invite Users icon on the Conference window to invite more users to an
existing chat conversation.
Adding BMC Remedy AR System users who are not present in the Friends list
On the regular form where you have configured the BMC Remedy AR System server to work with
the chat server, create an active link that executes on the CHAT_SET_CONTEXT_REQ Event type
. For more information about events, see the following tables.
This active link sends an event to the AR System Chat Data Visualization field with Event type as
CHAT_SET_CONTEXT_RESP and Event Data as given below:
ContextUsers= ACommaSeparatedListOfBMCRemedyARSystemUsers;ContextGroups=
ACommaSeparatedListOfGroupIDs;DisplayName=SubjectOfTheChatConversation;
For example:
ContextUsers= John,Max,Amy;ContextGroups=1,2
ContextGroups=1,2;DisplayName=Resolving an IT ticket;
ContextUsers=John,Max,Amy;ContextGroups=1,2;DisplayName=Resolving an IT ticket;
List of events sent from the AR System Chat Data Visualization field to the parent form
Event name
Description
DVF_ON_READY
Page 2244 of 4705
Home
Event name
Description
The Data Visualization Field (DVF) is loaded and is ready to interact. This is not
specific to the chat DVM. No response expected.
CHAT_SET_CONTEXT_REQ
Sent to the parent form for the parent form to supply any contextual information.
If the parent form chooses to provide this information, it later raises a
corresponding event, CHAT_SET_CONTEXT_RESP.
CHAT_SESSION_START
Sent to the parent form to provide information on the chat progress. No response
expected.
CHAT_INVITATION_SEND
Chat invitation sent. No response expected.
CHAT_USER_JOIN
A person is joining a chat session. This event occurs as many times as anyone
joins a chat session. No response expected.
CHAT_USER_LEFT
A person is leaving a chat session. This event occurs as many times as anyone
leaves a chat session. No response expected.
CHAT_INVITE_RECVD
A person is receiving a chat invitation. This event occurs as many times as

anyone receives a chat session invitation. No response expected.
CHAT_DATA_AVAILABLE
When the chat widget has a chat conversation transcript available, this event is
raised prior to chat session end, so that the parent form has an opportunity to
save the transcript.
CHAT_SESSION_END
End of the chat session. No response expected.
CHAT_GET_SESSION_TRANSCRIPT_RESP
Provides a specific chat session transcript to the parent form.
List of events sent from the parent form to the AR System Chat Data Visualization Field
Event name
Description
CHAT_SET_CONTEXT_RESP
Raised by the parent form's workflow during or after processing the

CHAT_SET_SESSION_REQ event. No response expected.
FORM_EVENT_LOGOUT
Indicates to the DVF about things happening on the host form or the application.
This is not specific to the chat DVM.
CHAT_GET_SESSION_TRANSCRIPT_REQ
Gets the chat session text transcript that is accumulated in the chat widget's buffer
. This request event causes the DVF to raise the
CHAT_GET_SESSION_TRANSCRIPT_RESP event.
When you create an active link that runs on the Event type CHAT_SET_CONTEXT_RESP, the
Start Conversation window is displayed as follows:
Note
Click here to view a .def file sample that uses the above information through the BMC
Remedy AR System form, "ChatTestForm" and it's related active links. Import this .def file
using BMC Remedy Developer Studio and access the "ChatTestForm" from BMC
Remedy Mid Tier to view it.
Page 2245 of 4705
Home
Start Conversation window
To add users to the Friends list, hover the pointer over the user name that is not present in your
Friends list and click the Add to Friend list icon that appears to the left of the user name.
Add user to Friend list on the Start Conversation window
Note
BMC Remedy AR System does not allow searching and adding friends without context.
For example, to see how BMC Remedy ITSM Suite has defined context users, see
Initiating a chat conversation.
Page 2246 of 4705
Home
Chat notifications
Chat notifications are received when:
You receive a conference request
You receive a message
Notifications are displayed in the drop-down menu and at the bottom right of your browser window
as shown below:
Chat notification window
You can respond using the Notification icon or the drop-down menu. When you receive any
notification, the Chat icon animates.
Using the chat option through BMC Remedy ITSM Suite

This topic provides instructions for using the chat option through BMC Remedy ITSM Suite.
To chat using BMC Remedy ITSM Suite

1. Click the Chat icon provided on the BMC Remedy ITSM landing console for:
BMC Service Desk
2. Follow the additional steps documented in Using chat.
Note
To display the Chat icon on the BMC Remedy ITSM landing console, see Enabling chat,
Twitter notifications, and RSS feeds.
Section 508 support for chat

The chat functionality supports section 508. This functionality has been tested on the following:
Microsoft Internet Explorer 8
JAWS screen reader, version 11
English language only
Page 2247 of 4705
Home
Note
Since JAWS is a Microsoft Windows product, the section 508 support is limited to PC
clients.
Pre-requisites
Make sure that you follow all the recommended required accessibility settings to work with the BMC
Remedy Mid Tier. For more information, see:
Making your application accessible - Section 508 compatibility
JAWS settings for the Web
Supported shortcuts
On any form, such as the BMC Remedy ITSM Landing Console, which is connected to the chat
server and where the Chat Data Visualization field is available, the chat functionality supports the
following list of shortcuts:
Ctrl + Alt + C Opens the Start Conversation window
Ctrl + Alt + O Opens the Chat options that further allows navigation to:
Change the status
Active notifications
Active chat sessions
Ctrl + Alt + N Opens and activates the next active chat session, if one is available
Using chat
When you are connected to a chat server, the Chat Status and the Chat Options icons are
displayed as shown in the following figure:
BMC Remedy ITSM Landing Console---Icons
Page 2248 of 4705
Home
Since the Chat Status icon and the Chat Options icon, both, are listed in the JAWS anchor links,
you can access them using the standard JAWS shortcuts. For example, INS+F7. You can also
access them using the keyboard shortcuts. For example, Ctrl+Alt+C and Ctrl+Alt+O. respectively.
For more information about using the chat functionality from BMC Remedy ITSM Suite, see Using
chat.
Using the Chat Options icon

You can use the Chat Options icon for the following:
Opening the status menu using the Tab and Enter keyboard keys or using the right or left
arrow keys.
Using the up or down arrow keys to navigate across the status and using the Enter or
Space keyboard keys to select a status (JAWS announces the new status of the user.).
Navigating to the notifications and active chat sessions using the up or down arrow keys.
Accepting or rejecting pending notifications using the Enter or Space keyboard keys.
Opening or exiting the active chat sessions using the Enter or Space keyboard keys.
Note
If JAWS is not running with the forms mode as "On", there may be inconsistent
results while accessing items using the right, left, up, or down keyboard keys. Make
sure that you use either the Enter keyboard key or the INS+Z key to switch "On"
the forms mode, that is, to switch off the virtual PC cursor. This is valid for the
complete chat functionality when JAWS is running.
JAWS also announces any pending notifications after every 20 seconds until they
are accepted or rejected. This announcement for the no-vision user is to mimic the
blinking chat icon for a user with vision.

The Start conversation window has the list of friends, context users, and context groups with
users within each group. It also has a Start Conversation icon and a Subject Text field, where the
default focus is set. Once the focus is on one of the groups or friends, use the following keys for
navigation:
The Tab keyboard key to navigate between the Start Conversation icon, Subject Text field
, and the list of friends.
The up or down keyboard keys to navigate between the friends and the group lists.
The Space keyboard key to toggle the selection of a friend before initiating a chat
conversation.
Page 2249 of 4705
Home
The Space keyboard key to toggle the expand or collapse of a group.

The Enter keyboard key on a friend to start a chat conversation with selected friends.
The A keyboard key when the focus is on a friend from context groups or context users to
add to friends list.
The Esc keyboard key to hide this window.
Opening the Chat Conversation window

Open the Chat Conversation window in one of the following ways:
Start a new chat conversation from the Chat Conversation window by selecting one or
more friends or a context users.
Accept a chat invite from another user.
Open a previously active chat session from the chat options.
The behavior and accessibility in all these scenarios is the same. JAWS announces the active chat
window title and sets focus on the chat typing area. Make sure that JAWS has the forms mode as "
On" for the appropriate navigation to allow typing in the chat typing area.
On the Chat Conversation window:
Use the Tab keyboard key to navigate between the chat text area, conversation history table
, and the Invite Chat icon that is available only for one-to-many chat.
Use the Enter keyboard key with the focus on the chat typing area to send the message to
the participants.
Use the Shift+Enter keyboard keys to put a carriage return character in the chat typing area.
Use the Esc keyboard key to minimize the Chat Conversation window and access it later
using the Chat Options icon.
Use the Shift+Esc keyboard keys to exit from the chat session.
Use the Ctrl+Alt+N keyboard keys to navigate to the next active chat session, if available.
For more information about chat conversation, see the following sections:
Starting a chat conversation (BMC Remedy AR System)
Initiating a chat conversation (BMC Remedy ITSM Suite)
Using the Chat notifications window

The Chat Notification window is displayed when a chat request from another user is received.
JAWS announces the notification as an alert. The default focus is set on the Accept button. Use
the Tab keyboard key to change the focus to the Reject button and the Enter or the Space
keyboard key to perform the action according to the focus.
Refer to following links to get more details on chat notifications:
Chat notifications (BMC Remedy AR System)
Chat notifications (BMC Remedy ITSM Suite)
Page 2250 of 4705
Home
Note
For information about the section 508 support for the chat functionality known issues, see
Accessibility known issues in version 8.1.00.
Displaying a BMC Remedy AR System form in

a portlet
This section describes how to write a portlet for a JSR 168-compliant portal server that displays a
BMC Remedy Action Request System (AR System) form view. For example, the portlet window can
show a table or a data visualization field of a form.
Required knowledge
Tested platforms
Solution architecture
Portlet structure
Authentication solutions
Best practices
Related topics
Required knowledge
To create a portlet to display a form view, you must be able to:
Create a view in AR System.
Display a view in a browser using a mid tier URL.
Write a portlet in Java using the JSR 168 API. (An example portlet is included with AR
System 7.0.01.)
Deploy a portlet in your portal server and administer the portal server.
Tested platforms
The methods described in this topic are illustrated in unsupported sample portlet code that you can
find in the samples/portal directory in the mid tier installation directory.
For UNIX:
/usr/ar/mid-tier/samples/portal
Page 2251 of 4705
Home
For Windows:
C:\Program Files\AR System\Mid-Tier\samples\portal
The sample has been verified using:

AR System 7.0.01
Portal servers:
BEA WebLogic Portal 8.1 on HP HP-UX, Linux, and Microsoft Windows Server 2003
IBM WebSphere Portal 5.1 on Microsoft Windows Server 2003
IBM WebSphere Portal 6.0 IBM AIX
Liferay 3.6.1 and Tomcat on IBM AIX, Linux, Microsoft Windows Server 2003, and
Sun Solaris
Solution architecture
To display a form view, the AR System portlet must reference the view in the AR System mid tier,
so to display AR System content in a web portal, you must have:
A browser to display the web portal.
A portal server with a portlet container and web server to host the portal and the portlet.
An AR System mid tier to display the form view in an IFRAME element in the portlet within
the portal in the browser.
An AR System server to provide the view to the mid tier.
Components and communication
Page 2252 of 4705
Home
Portlet structure
Portlets are similar to servlets. The JSR 168 API is based on the servlet API and many portlet
containers are extensions to servlet containers. But while a servlet produces a complete web page,
a portlet produces an HTML fragment that the portal displays in a portlet window, aggregating it
with other portlets.
A portlet usually has an EDIT mode. In EDIT mode, the user can set portlet preferences that can
control the content and appearance of the portlet in VIEW mode. The portal can save the
preferences so the user does not need to enter them for every use. A portlet can also have a HELP
mode.
When you design the AR System portlet, you must decide which proprieties of the portal the user
can control and which will be fixed or determined another way. For example, will the user be able to
choose which AR System form, view, table, flashboard, or other data visualization field to display?
If the user cannot set or change any properties, the portlet does not need an EDIT mode. You must
also determine if it needs a HELP mode.
Because the AR System mid tier serves the form view displayed in the portlet, to achieve basic
aggregation integration, you must include a reference to the view in the portal VIEW mode HTML
fragment. Do this by including an HTML IFRAME element that references the URL of the form view
in its src attribute. In the simple case, the fragment can consist of only the IFRAME element. An
example of an IFRAME element follows.
<IFRAME id=Portlet1 width=100% height=100% scrolling=no
Page 2253 of 4705
Home
title="Table of requests assigned to you"

src="http://armt.ankelotez.com/arsys/servlet/ViewFormServlet?
server=arsys.ankelotez.com&form=AgentConsole&view=RequestTable">
Your portal cannot display the RequestTable form view. </IFRAME>
See Installing old and Administering BMC Remedy Mid Tier for more information about
ViewFormServlet as used in the example.
Because the view in the portlet is displayed by the mid tier, it might not be consistent with the portal
style. You can set the appearance properties of the view to hide the web toolbar, to make the view
color consistent with the portal, and to provide content for the web header and footer. You can also
change the AR System style sheets in the mid tier to make the form view more consistent with the
portal style. See Installing old and Administering BMC Remedy Mid Tier.
Authentication solutions
Because the portal and the mid tier have separate authentication, AR System portlets might require
the user to log in twice and log out twice. This section describes ways to handle mid tier login and
logout.
To log in, the user must first log in to the portal and then log in to the AR System mid tier. To log
out, the user should log out of the portlet before logging out of the portal.
Login integration
A portlet solution can handle login to the mid tier in the following ways:
Require separate logins No integration between the portal or the portlet and the mid tier
is required. After logging in to the portal, the user must also log in to the mid tier. The mid tier
displays the login form in the servlet before it displays the referenced view.
Allow guest users to access your AR System server If you permit guest users, you
can grant the Public group access to the form and specify the guest user authentication
information in parameters to ViewFormServlet and log in the user automatically.
Save authentication information in portlet preferences If the portlet gets the user
name and password from the user in EDIT mode and saves them in portlet preferences, the
portlet can specify the user authentication information in parameters to ViewFormServlet and
log in the user automatically in VIEW mode. The portlet can encrypt and decrypt the
password to provide more secure storage in the portlet preferences.
Use the same single sign on (SSO) solution If the portal server and the AR System
server use the same SSO solution for user authentication, you can configure them so that
individual logins are not required.
Customize the portal login If you can customize your portal server, you can modify the
portal login to perform the mid tier login before it runs any portlets. In this case, the login
process on the portal server logs in to the mid tier instead of the portlet fragment in the portal
on the browser computer. The portal login process must have access to the required
authentication information.
Page 2254 of 4705
Home
Use portal authentication information You can code the portlet to log in the user
automatically if:
You configure your portal and AR System server to use the same authentication
information.
You can customize your portal server.
You create portal server interfaces that the portlet can use to get the user name and
password used to log in to the portal.
For example, the Liferay portal server can be customized by changing
/portal-ejb/src/com/liferay/portal/service/impl/ UserServiceImpl.java in
the Liferay 3.6.1 installation directory. Replace
if (user.getPassword().equals(encPwd)) { authResult =
Authenticator.SUCCESS;
with
if (user.getPassword().equals(encPwd)) { user.setPassword(password);
user.setPasswordEncrypted(false); authResult = Authenticator.SUCCESS;
For the example code that gets the password from the Liferay portal, see the sample portlet code in
the mid tier installation directory at /samples/portal/src/com/arsys/portal/
LiferayARPortlet.java.
Logout integration
A user must log out of the BMC Remedy mid tier to release the license. A portlet solution can
handle logout from the mid tier in the following ways:
Require separate logouts No integration between the portal or the portlet and the mid
tier is required. Include a logout button on the form view displayed in the portlet as described
in Installing and Administering BMC Remedy Mid Tier . Users logs out of the mid tier using
the button before they log out of the portal.
Customize the portal logout If you can customize your portal web page, you can
change the logout behavior, so the portal logout button performs the mid tier logout before it
performs the portal logout. This does not affect portal users who are not using your AR
System portlet because the logout is ignored.
Customize the portlet API JSR 168 does not include a call to the portlet when the portal
exits. If you can customize your portal server, you can add this capability to the API and use
it in your AR System portlet to log out of the mid tier.
As an example of customizing the portlet API, you can customize the Liferay portal server by
making the following changes:
1.
Page 2255 of 4705
Home
1. Add the following method and the required import to /portal-ejb/src/ com/liferay/
portal/servlet/PortletContextPool.javain the Liferay 3.6.1 installation directory:
public static Set getAllPortletID() { return
Collections.unmodifiableSet(_instance._portletContextPool.keySet());
}
2. Compile /samples/portal/src/com/arsys/portal/LogoutCallback.java in the
mid tier installation directory into the /portal-ejb/classes directory in the Liferay 3.6.1
installation directory.
3. Append com.remedy.arsys.portal.LogoutCallback to the logout.events.post property in the /
portal-ejb/classes/ portal.properties file in the Liferay 3.6.1 installation
directory. For example, the modified property might be:
logout.events.post=com.liferay.portal.events.LogoutPostAction,
com.liferay.portal.events.GarbageCollectorAction,
com.remedy.arsys.portal.LogoutCallback
Best practices
Consider the following recommendations when you design and code the portlet. See the Form and
Application Objects guide and the Installing and Administering BMC Remedy Mid Tier guide for
more information.
Target use case

The most effective view for an AR System portlet contains only a table field or a flashboard or other
data visualization field plus trim fields and active link control fields required for effective formatting
and function. Avoid user input in the portlet view. For example, a flashboard that summarizes the
status of interesting requests or a small table that lists relevant requests can be effective portlets.
For user interaction, provide a button or other active link control that opens a more complete view in
a separate browser window, not in a portlet. The user must complete the interaction in the separate
window before logging out of the mid tier in the portal window.
Custom view
Create a separate view for the portlet. Set the Appearance properties of the view to hide the web
toolbar.
Limitations
Be aware of the following possible limitations of AR System portlets:
Like other portlets, an AR System portlet reinitializes when the browser Refresh command is
run (or the portal web page is reloaded). For example, if you type in fields in a form and
refresh the portal page, your entries are lost. For portlets that display status as
recommended in Target use case, this is usually not a problem.
Page 2256 of 4705
Home
If a portal contains more than one AR System portlet, some portlets might not display their
content the first time they appear after AR System login. To prevent this problem, use an
SSO solution or customize the portal login, as described in Login integration. Otherwise, if
an AR System portlet does not initially display its content, use the browser refresh function to
reload the portal.
Similarly, when the portal is open in Microsoft Internet Explorer, a change in another portlet
might cause an AR System portlet to blank out its content. To display the AR System portlet,
use the browser refresh function to reload the portal.
Related topics
Defining and managing form views
Page 2257 of 4705
Home
This section guides developers and application programmers through the process of developing or
customizing a BMC Remedy AR System application, from navigating the BMC Remedy Developer
Studio interface to moving the application to production and distributing the application.
Goal
Understand the AR System navigator, BMC Remedy Developer Studio perspectives, and how to work
with existing objects or create new objects.
Create and define packing lists. Use version control and understand the development modes.
Instructions
Application
development
with BMC
Remedy
Developer
Studio
Navigating the
BMC Remedy
Developer
Studio interface
Setting up the
development
environment
Learn how to define a local and deployable application.
Use BMC Remedy AR System objects to develop an application, including forms, panels, tables,
images, menus, and fields. Learn how to choose the types of fields. Understand how to embed web
content through Data Visualization fields and add graphics to the application with flashboards.
Defining and managing

an application
Developing the
application
interface
Adding graphics
to an application
with flashboards
Use access control for a deployable application. Learn how to grant permissions to the application and
their objects.
Securing your
application
Configure workflow forms and build qualifications and expressions.
Defining workflow to
automate processes
Learn about the mid tier application development guidelines.
Mid tier application

development guidelines
Understand how administrators connect a BMC Remedy AR System application to BMC Remedy
Approval Server
Adding approvals to an
application
Learn some guidelines to enhance performance of applications
Building performance
into applications and
workflow
Understand how to customize the application using overlays and custom objects. Customize the
interface, the home page, and entry points.
Customizing
applications
using overlays
and custom
objects
Page 2258 of 4705
Home
Goal
Instructions
Customizing the
interface for
multiple
consumers
Localize an application.
Localizing an
application to other
languages
Learn the methods by which BMC Remedy AR System supports Section 508 accessibility requirements.
Making your application

accessible (Section 508
compatibility)
Learn how to test and debug an application. Make adjustments to the UI, workflow, and server
environment to maximize performance.
Testing and debugging

a BMC Remedy AR
System application
Move the application to production and distribute the application. Learn how to use BMC Remedy
Developer Studio to export the application, install it on the production server, and add and license users
.
Learn to publish a web service to make BMC Remedy AR System functionality available over the web
by creating a web service object, associated forms, and optional workflow.
Moving to
production
Distributing an
application
Publishing the BMC

Remedy AR System
functionality as a web
service
Application development with BMC Remedy

Developer Studio
A BMC Remedy AR System application is a tool that you create to track data, processes, and
issues. An application is an entity that consists of forms, workflow, and related objects that you
have created in BMC Remedy AR System server. Forms collect and display data, and workflow
directs the actions of the application.
Page 2259 of 4705
Home
Forms make up the basic user interface elements and "building blocks" of an application. Forms
contain fields where users enter or update information. Whenever information is added or updated
in a field, the database is updated. Each form corresponds to a set of tables in the database, and
each field corresponds to a column in the database table. Depending on its purpose, an application
can contain one form, or a set of forms.
Workflow objects (active links, filters, escalations, active link guides, and filter guides) tie together
events (for example, user actions and changes to data) and actions (for example, changes to data
and other interaction with the user) to define the behavior of the application. Workflow is executed
when a specified condition occurs, such when a user tabs into or enters information into a field, an
amount of time has passed, the status of an item changes, or a process runs.
For descriptions of the key components that make up BMC Remedy AR System applications, see
Application development overview.
This section describes the details about developing BMC Remedy AR System applications with
BMC Remedy Developer Studio. Topics include:
Determining what your application needs to track
Determining what to track
Determining how your application should work
Designing effective and more usable applications
Designing the user interface effectively
Resources for product design and usability
Providing accessibility for users with disabilities
About the Sample application
Determining what your application needs to track

To determine what your application needs to do, gather requirements from those in your
organization who provide information for, and manage, the business process your application
intends to serve. This could include users, project managers, business analysts, and administrators
.
During your analysis, identify transition points in the process, where data moves from one state to
another. Because BMC Remedy AR System applications can control transitions and enforce
business rules, you need a clear understanding of what the application must do for accurate
execution of the business process.
Gather the following information:
What kinds of information do users need?
What is the life cycle of the data? How long must data be stored? (Indefinitely, for N months
or years)? What happens to data after this point?
What types of information can be tracked together?
Page 2260 of 4705
Home
Where does the data come from? Other systems? User input?
Where could redundant data entry occur?
Where can data be just referenced or displayed instead of entered or modified?
Where can data be reused?
The number of forms that you create depends on the smallest unit of data that you want to track
and how you want that data to relate to other types of data. For example, to keep ALL data about
assets in a single form, the asset form needs fields for information about manufacturers. To avoid
duplicating information about manufacturers for EACH asset, your application could have a form for
assets, and link it to a separate form for manufacturers through workflow and logical joins.
For example, a complete trouble ticket application might consist of a main form that contains the
caller ID, issue description, and work log information and several secondary forms that are linked to
the main form to manage caller information or aging tickets.
For complete descriptions of the key components that make up BMC Remedy AR System
applications, see the Key Concepts section.
Determining what to track

What you track depends on your business processes and rules that deal with data and events.
Gather requirements for an application from users, managers, and other administrators who have a
stake in the business process and how the application supports it.
When analyzing a business process and business rules, identify transition points in the process,
where data moves from one state to another. Consider how groups of people in your organization
handle the data during state transitions. Because the BMC Remedy AR System application that you
develop can control transitions and enforce business rules, you need a clear and correct
understand of them.
When analyzing your data tracking needs, gather the following information:
What is the life cycle of the data: data capture, data storage, data retrieval, data update, data
archival, and data retirement?
What types of information can be tracked together?
Where does the data come from? Other systems? User data entry?
Where could redundant data entry occur?
Where can data be just referenced or displayed instead of entered or modified? Where can
data be reused?
What kinds of reports and information do users need from your application?
Following normal business practices, when will the application's data become irrelevant?
You can address these questions when designing your application and deciding how many forms
define the processes that you identified. The number of forms that you create depends on the
smallest unit of data that you want to track and how you want that type of data to relate to other
Page 2261 of 4705
Home
types of data. For example, to keep all data about assets in a single form, your asset form needs
fields to accommodate information about manufacturers. Instead, to avoid duplicating information
about manufacturers for each asset, your application could have a form for assets, and link it to a
separate form for manufacturers through workflow and logical joins.
Determining how your application should work

When designing filters, escalations, and active links that define the workflow process for your
application, consider the following issues:
What is your current workflow process? Create a flowchart that describes your current
problem-solving process (for example, see the following figure).
What events in your process trigger specific actions? Can you use shared workflow?
Workflow process example

Designing effective and more usable applications

Usability studies show that users prefer to complete major tasks quickly and accurately.
User-friendly applications provide the following benefits:
Improve user task completion rates by 25-50%
Reduce technical support time by 20-30%
Reduce training time by 30-40%
Reduce user frustration level by 0-50%
The following tips can help you design better applications:
Target common tasks Design around the three or four most common tasks that users
are likely to perform. If you have several types of users (for example, managers and support
personnel), design separate forms, tabs, or views for each type.
Page 2262 of 4705
Home
Group elements Group information that belongs together in the same area. For example,
keep all customer address information in one area. Label each section clearly. Use white
space to separate the grouped information.
Emphasize elements Place important elements, such as required fields, at the top of
grouped sections. Place optional or less important elements at the bottom. Buttons should
immediately follow the section upon which they act.
Simplify the interface To increase your user success rates:
Reduce the steps required to accomplish the most common user tasks.
Reduce the amount of text and font types, design elements (such as buttons and
fields), and graphics. Consider eliminating elements that are not required.
Create smaller tables.
Plan your design around the tasks that users must accomplish and the fields required
to accomplish those tasks. As a general rule, 80% of optional fields can be eliminated.
Create contrast Choose a light background color that makes black text easy to read.
Avoid light-colored text and dark, multicolored, or textured backgrounds. Use headings, bold
text, and light-colored cells and borders to make important elements stand out.
Align elements Align fields and field labels. Misaligned fields create visual confusion and
draw the user's attention away from the tasks they must perform.
Be consistent Keep language simple and consistent. For example, use Postal Code or
Zip Code, but not both. Use similar field lengths and button types for similar actions.
Provide feedback Provide a message or clearly change the way the interface appears
after a user performs an action. For example, if the user performed the wrong action, supply
an error message that explains why the action did not succeed and what the user must do
next.
Test your application Customers can provide useful feedback on your application from a
user's point of view. Test your application with a cross-section of customers that reflects your
intended audience.
Designing the user interface effectively

This section offers tips for designing the layout of the forms in your applications. By following
standard UI design practices, you can help your users understand how to fill out forms more easily.
The following figure illustrates a form with a poorly designed user interface. This form:
Is "packed" with a large number of fields, all of which must compete for the user's attention.
Is poorly organized, providing the user with no visual clue as to the relationship of the data or
the logical flow of actions.
Does not provide enough visual distinction between field labels and labels that group
sections of fields.
Does not align fields consistently.
Does not label items consistently (for example, sections along the bottom are not labeled).
Has a button (Clear Table button) that does not follow the appropriate section.
Page 2263 of 4705
Home
Poorly designed interface

The following figure shows a well-designed interface. This form:

Includes only the fields necessary to perform the tasks for which the application was created.
Arranges the fields so that related data is grouped logically, and makes groups of related
data visually distinct.
Makes important fields stand out from the background, enabling users to accomplish tasks
quickly.
Well-designed interface
Resources for product design and usability

For more information about usability design principles, talk to a usability consultant or see the
following books and websites.
Books
Designing Web Usability: The Practice of Simplicity , by Jakob Nielsen
GUI Bloopers 2.0: Common User Interface Design Don'ts and Dos , by Jeff Johnson
Don't Make Me Think: A Common Sense Approach to Web Usability , 2nd Edition, by Steve
Krug
Page 2264 of 4705
Home
The Humane Interface: New Directions for Designing Interactive Systems , by Jef Raskin
About Face 3: The Essentials of Interaction Design , by Alan Cooper, Robert Reimann, and
David Cronin
The Design of Everyday Things, by Donald A. Norman
Designing Visual Interfaces: Communication Oriented Techniques , by Kevin Mullet and
Darrel Sano
Universal Principles of Design, by William Tidwell, Kritina Holden, and Jill Butler
Websites
User Interface Engineering (http://www.uie.com)
Usability Professionals Association (http://www.upassoc.org)
Neilsen Norman Group (http://www.nngroup.com)
Jacob Nielsen's website (http://www.useit.com)
Boxes and Arrows (http://www.boxesandarrows.com)
UX Magazine (http://www.uxmag.com)
UXmatters (http://www.uxmatters.com)
The Usability Post (http://www.usabilitypost.com)
Usability.gov (http://www.usability.gov)
Providing accessibility for users with disabilities

The mid tier supports users who need assistive technology such as JAWS (Job Access with
Speech). For more information about accessibility in a browser, see Making your application
accessible - Section 508 compatibility.
About the Sample application

To see examples of various forms, fields, and workflow actions, install the Sample application with
the BMC Remedy AR System server. The application implements a class registration system and
includes forms to add classes, to register for a class, and to view enrollments. Forms in the sample
application are enabled for browser access. Help text in the forms and workflow explains how the
application works.
Opening the Sample application

Follow the procedures given below to open the Sample application:
In a browser
1. In a browser, enter the IT Home page URL for a server where the Sample application is
installed
(http:///arsys/home). If necessary, log on as an administrator.
2. In the navigation panel of the IT Home page, click the AR Sample Application Console link
.
3.
Page 2265 of 4705
Home
3. In the AR Sample Application Console, explore the Sample application forms by clicking the
links in the navigation panel and the arrow button under the bar chart.
In BMC Remedy Developer Studio

1. Log on to BMC Remedy Developer Studio as an administrator on a server where the Sample
application is installed.
2. In the AR System Navigator, expand the Applications branch under the appropriate server.
3. To explore the objects in the Sample application, double-click Sample, and expand the
panels in the Sample object list.
4. To explore the Sample application attributes and properties or modify the application:
a. Right-click Sample and select Edit Application.
b. Expand the panels.
c. View the Properties tab.
Navigating the BMC Remedy Developer Studio

interface
This section provides information about navigating the BMC Remedy Developer Studio interface.
About BMC Remedy Developer Studio
Event Navigator
Creating objects
Finding objects
Using associations
Using working lists
Printing from BMC Remedy Developer Studio
Clearing BMC Remedy Developer Studio cache
Creating reports for selected objects
Differences between BMC Remedy Administrator and BMC Remedy Developer Studio
Page 2266 of 4705
Home
About BMC Remedy Developer Studio

BMC Remedy Developer Studio is an integrated development environment (IDE) for BMC Remedy
AR System applications. It provides all the application development functions of the previous BMC
Remedy Administrator tool with a modern, powerful, easy-to-use interface. (The AR System
Administration Console provides the server administration functions that BMC Remedy
Administrator provided before release 7.1.00.)
BMC Remedy Developer Studio is an Eclipse application, which uses perspectives to organize
windows into layouts. In BMC Remedy Developer Studio, you work with two perspectives:
Developer perspective Contains tabs and editors to find, create, and modify objects on
BMC Remedy AR System servers.
Editor perspective Contains only the tabs and editors you need when you are editing an
object.
For more information, see Working with perspectives.
The following figure shows the Developer Perspective of BMC Remedy Developer Studio.
BMC Remedy Developer Studio and the Developer perspective
The Developer perspective has several parts:
Page 2267 of 4705
Home
Parts of BMC Remedy Developer Studio window

Area
Description
AR System
Navigator
Contains a tree of objects for each BMC Remedy AR System server that BMC Remedy Developer Studio is
Object list
tab
Contain lists of server objects. To open an object list, double-click a node in the AR System Navigator. Use these
Editor tab
Contain editors where you can create and modify BMC Remedy AR System server objects. For information
about modifying objects using the BMC Remedy Developer Studio editors, see Working with existing objects.
Outline tab
Displays a structural outline of the object that you are working on (for most editors). For forms, the Outline tab
connected to. Use the items in the tree to create and access objects on the server. See Understanding the AR
System Navigator and Using the Outline tab.
lists to find objects to examine or modify. See Using object lists.
includes a Zoom Overview button that displays a reduced-size picture of the form. Use the outline to select
items in an object. When you select an item in the outline, it is also selected in the editor, and vice versa. When
editing a form, use the Zoom Overview to position the form editor on a part of the form. For more information,
see Using the Outline tab.
Properties
tab
Displays the properties of the object that you are working on or the properties of a form view or a field in a form.
Use this tab to view or change the properties of objects, form views, and fields. See Modifying object properties.
Messages tab
Displays messages about the work that you are doing in an editor. Double-click a message to go to the relevant
location in the editor. See Using the Messages tab.
Progress tab
Shows the progress of long operations, such as an export or import. You can continue working while the
operation runs.
Displays a list of related fields and objects. Right-click an object in an object list, and select Show Relationships
Relationships
tab
to display related fields and objects. Double-click an item in the Relationships tab to edit the object and go to
the relevant location in the editor. See Viewing and sorting related objects.
Search
Results tab
Displays a list of server objects that contain text that you specify. Select Search > Search option to find objects
that satisfy your search criteria. You can use the Search Results tab like an object list. See Using the Search
menu option. This tab does not appear until you select the Search menu option.
Analyzer tab
Displays the results of the analysis of one or more objects. Right-click an object in an object list, and select
Analyze to analyze objects. Double-click an item in the Analyze tab to edit the object and go to the relevant
location in the editor. For more information, see Using Analyzer to find problems in your applications. This tab
does not appear until you use the Analyze command.
Perspective
bar
Provides a convenient way to switch perspectives. For more information, see Working with perspectives.
Status bar
Displays information about the user logged in and about the object being edited.
If you cannot find a tab, it might be minimized or closed. To open a minimized tab, click the Restore
icon (
) in the window margin. If the tab is closed, use the Window > Show View menu to open
it.
Notes
BMC Remedy Developer Studio does not support large DPI fonts, which are
configured in the Properties dialog box of Windows computers.
Page 2268 of 4705
Home
In the BMC Remedy Developer Studio user interface, tables often seem to have an
empty column on their right side. This illusion occurs when the right column
separator for the last data-filled column is visible. The separator enables you to
resize the last data-filled column. You can drag the separator until the "empty"
column is no longer visible.

You can log on to a BMC Remedy AR System server from any computer on the network that has
access to the server. To use BMC Remedy Developer Studio, you must be a BMC Remedy AR
System server administrator or subadministrator. (See Access control in BMC Remedy AR System .
)
BMC Remedy Developer Studio stores local preferences and other configuration information in the
workspace directory. (The default workspace location is C:\Documents and Settings\<userName
>\DeveloperStudio\workspace.) To maintain different sets of local preferences and other
configuration information, create two or more workspace directories.
To start BMC Remedy Developer Studio and log on to BMC Remedy AR System
servers
1. Select Start > Programs > BMC Software > AR System > BMC Remedy Developer
Studio.
2. To change the location of your workspace in the Workspace Launcher, click Browse, select
or create a directory, and click OK.
3. To clear all local preferences, configured BMC Remedy AR System servers, and other local
preferences and start BMC Remedy Developer Studio in its initial state:
a. Exit BMC Remedy Developer Studio.
b. Delete the workspace directory.
c. Restart BMC Remedy Developer Studio.
4. In the Workspace Launcher dialog box, click OK to open the Login window.
5. In the User Name field, enter the name of a BMC Remedy AR System server administrator
or subadministrator, such as Demo.
A BMC Remedy AR System user name is case-sensitive, which means you must type Demo,
not demo or DEMO.
Note
During initial installation, the Demo user is created without a password. To keep
BMC Remedy AR System server secure, add a password for Demo as soon as
possible. (See Adding and modifying user information.)
Page 2269 of 4705
Home
6. Enter the password of the BMC Remedy AR System user.

7. (Optional) If you are required to specify an authentication string or a preference server, click
Options.
a. Enter an authentication string. Whether you need an authentication string depends on
how your server validates users. For most situations, this field is not used. For more
information, see Setting up an authentication alias.
You can also define use of an External Authentication (AREA) plug-in. For more
information, see AREA plug-ins introduction and AREA plug-in API functions.
You must inform clients whether an authentication string is needed when logging in
and what that string should be. For most situations, this field is not used and remains
empty.
b. In the Preference Server field, type the name of your preference server. If the
preference server does not use the default TCP port, type the port number in the
Preference Server TCP field.
A preference server is the BMC Remedy AR System server on which the AR System
preference forms are installed. This server stores your administrator and user
preferences in a central location where they can be accessed from any client
computer. You define a server as a preference server during or after installation.
If you always log on from the same computer, leave this field blank to store your
preferences locally in the workspace directory.
For more information, see Centralized preferences.
8. If you have already configured BMC Remedy AR System server to connect to, click Login (
and skip the rest of this procedure ).

9. Click Edit Server List.
To sort the server list, click the Servers column heading.
10. In the Server List dialog box, click Add.
11. Click Enter a server name in the Servers column, and type the server name.
To prevent BMC Remedy Developer Studio from connecting to a server, clear the server's
check box.
12. Enter the Server Alias for the server so that you can identify the servers where multiple
servers are added.
13. If the server does not use the default TCP port, click in the TCP column and type the port
number.
14. Repeat steps 10 through 13 for each server BMC Remedy Developer Studio must connect
to.
15. Click OK.
16. In the Login dialog box, click Login.
Note
By default, BMC Remedy Developer Studio opens in Best Practice Customization
mode. For more information, see Development modes.
Page 2270 of 4705
Home
To change the current login

1. Select File > Login.
2. In the Login dialog box, change the server list, user name, password, and other information
as described in the section above.
3. Click Login.
You can use the File > Switch Workspace command to select another workspace and log
on using it.

In BMC Remedy Developer Studio, you can access most menu options in multiple ways, including
the use of right-click pop-up menus, main menu options, and menu bar icons. For example, to add
an If Action to an active link, filter, or escalation, you can access the menu choices by any of these
three methods:
Right-click the If Actions panel heading, and then select Add Action.
Select the Workflow > Add If Actions main menu option.

Click the down arrow next to the Add If Action icon in the menu bar.
The procedures in this section describe using the right-click menu whenever it is available.
Page 2271 of 4705
Home
Event Navigator
BMC Remedy Developer Studio provides an Event Navigator view for a form, which helps you in
the following ways:
Displays in a tree structure the form events and field events that have workflow associated
with them, thus outlining the events related to the form and its fields.
Synchronizes itself with the active Form editor when the Link with Form Editor option is
enabled.
Enables you to view the workflow associated with an event easily.
Note
The Event Navigator view can only be launched for one form at a time. For more
information, see Launching the Event Navigator.
The Event Navigator view

The top-most parent node in the tree structure is the form node, which represents the form whose
event navigation is being viewed. Only those events that have workflow associated with them are
listed. When you open this view for the first time or switch to a different form's view, all the nodes
are collapsed. You must expand each non-leaf node to view its details.
Note
The Event Navigator lists only those events that have workflow in the Enabled state
associated with them.
Page 2272 of 4705
Home
The first child node is Form Events, which lists the events and escalations associated with the form.
The time-based event nodes under Form Events might vary based on the number and type of
escalations.
The second child node is either Field Events or Fields, depending on whether the View by Events
or View by Fields option is set. Use the first two icons in the tab group toolbar to specify your choice
; they are mutually exclusive. For more information, see Tab group toolbar buttons in the Event
Navigator.
Note
When viewing by events, a field can appear under multiple event nodes depending on the
events on which the workflow is fired.
The Show Workflow context menu is enabled only for the leaf nodes, whether it is a field or an
event.
Relevant changes to the form, like addition or deletion of fields or workflow associated with the form
or its fields, are reflected immediately in the Event Navigator.
Tab group toolbar buttons in the Event Navigator

The following buttons are available in the Event Navigator:
View by Events (
) Click to display the list of fields sorted by events. Expand the
individual event nodes to view the fields to which they belong.
View by Fields (
) Click to display the list of events sorted by fields. Expand the
individual field nodes to view the related events.
Link with Form Editor (
) The Link with Form Editor button on the tab group toolbar
works as follows:
When selected, it links the Event Navigator with the active Form editor. This is useful
when you want to watch the event navigation for a form being edited. When you
select a field or event node in the Event Navigator, the appropriate field in the Form
editor gets selected. If you switch a different form in the Form editor, the Event
Navigator displays the events of the currently active form. If you reload the Event
Navigator for a different form by using the Show Event Navigator menu in the Object
List view, then the events for the new form are displayed. However, because Link with
Form Editor is selected, switching to the previous form in the Form editor displays its
events again.
Page 2273 of 4705
Home
When cleared, the automatic synchronization is switched off, and you need to manually
launch the Event Navigator from a form being edited. See Launching the Workflow
Execution Viewer. If the Form editor view is not open, then the state of the Link with Form
Editor toggle button has no effect. The Event Navigator displays the events of the form from
which you trigger the command.
Launching the Event Navigator

You can launch the Event Navigator by using the Window menu, but to use the view, you should
open in the context of a form or field.
To launch the Event Navigator regardless of a form

1. Select Window > Show View > Other.
2. In the Show View dialog, either type Event Navigator as the filter text, or expand BMC
Remedy Developer Studio, select Event Navigator, and click OK.
To launch the Event Navigator for a particular form

1. Select the form in the Object List view.
2. From the context menu, select Show Event Navigator.
Note
The Show Event Navigator menu is only available in the Object List view for
forms. This menu is disabled if you select multiple forms in the Object List view.

You can set an active link to execute when a user clicks a button in a form or selects a menu item
from a top-level menu. (The active link can be linked to a button or a menu item, but not both.) If an
active link is executed from a menu item, you can also execute the same active link through a
corresponding toolbar button.
Note
Menu bars are not supported by browsers (they were supported by BMC Remedy User,
which is no longer supported). For more information, refer to the BMC Remedy Action
Request System Behavioral Differences Between BMC Remedy User and Browser
Clients white paper.
The following sections discuss how you can use buttons and menu bar items to execute active links
:
Page 2274 of 4705
Home
Understanding the working of buttons and menu items with active links
Creating accelerator keys for your menu items
Associating active links with buttons and menu items
Deleting buttons and menu items
Understanding the working of buttons and menu items with active links
Buttons and menu items are fields in BMC Remedy AR System server; you can use them in
workflow as in any other field. For example, an active link can show, hide, enable, or disable
buttons and menu items. Because these fields do not have data behind them and they are used to
control workflow, they are called control fields.
You can associate more than one active link with a button or menu item. A good use of this
capability is to define active links that execute based on current conditions, such as the platform on
which the tool is running.
For example, you can define an active link to execute only if the tool is running on a computer. You
can then associate another active link with the same field--this time defining the active link so that it
executes only if the web client is running. Users on either platform can then perform the same
action to execute the appropriate active link for their platform.
Active links as buttons or menu items
To add a button to a form, see Creating button fields section.
Creating accelerator keys for your menu items

You can designate one character of a menu or menu item as an accelerator key. For example, if
you create a menu item called "Print Report," you can designate the letter R, and the R is
underlined when the user presses the Alt key.
Page 2275 of 4705
Home
When creating accelerator keys, do not choose a letter that other menus on the menu bar use. Do
not duplicate the choices for menu items in your menu.
To designate a character as an accelerator key

1. Select the menu or menu item in the Edit Menu Bar dialog box.
2. In the Properties tab, click the Label property, and enter an ampersand (&) before the
character.
Associating active links with buttons and menu items

The Active Links property of a menu item enables you to select which active links are executed with
a button or menu item (and any corresponding toolbar button). For these active links, the user must
belong to a group with permission for the active link and the button or menu item:
If a user has access to all active links associated with a button or menu item, but not to the
button or menu item itself, the button or menu item is not displayed in the form.
If the user has access to the button or menu item, but not to any of its active links, clicking
the button or menu item does not execute the active link.
For more information about setting button permissions, see Assigning permissions.
To associate active links with buttons and menu items

1. Open the form with which you want to work.
2. Complete one of the following actions:
For a button, select the button so that its properties appear in the Properties tab.
For a menu item, select Form > Edit Menu Bar, and then select the menu item.
3. In the Properties tab, click Active Links, and click the ellipsis (...) button that appears in
the Value column.
4. In the Active Links dialog box, select which active links you want to view:
All Active Links Displays all of the active links in the specified form.
Available Active Links Displays only those active links in the specified form that
are not assigned to a button or menu item.
5. Move the active links you want associated with the button or menu item to the Selected
Active Links list.
6. Click OK, and save the form.
Deleting buttons and menu items

Buttons and menu items that are deleted from a form are deleted from the database.
To delete a button
1. Open the form.
2. Right-click on the button and select Delete.
Page 2276 of 4705
Home
To delete a menu item

1. Open the form.
2. Select Form > Edit Menu Bar.
3. Select the item, and click Delete.
To delete a toolbar button

1. Open the form.
2. Select Form > Edit Menu Bar.
3. Select the menu item from which you want to delete a toolbar button.
4. In the Properties tab, set Has Toolbar Item to False.

The following modifier keywords can help verify whether a user has pressed the Shift, Alt, or
Control keyboard modifier keys:
$SHIFT_KEY$
$ALT_KEY$
$CTRL_KEY$
The Keywords section provides a description about the keywords. In BMC Remedy Developer
Studio, you can define workflow that uses the modifier keywords on any type of field and with any
execution options. For example, you might want to create workflow on a control field such as push
button, URL-style button, or image button. You can also define similar workflow for a table field.
Example of using a modifier keyword
The following procedure describes an example of how to use the $SHIFT_KEY$ keyword (one of
the modifier keywords) so that workflow verifies whether the Shift key was pressed. (Similarly, you
can use other modifier keywords for the Alt or Ctrl keys.)
In this example procedure, the workflow opens a BMC Remedy AR System form in a new window
when the user presses the Shift key while clicking on a Control field in BMC Remedy Mid Tier.
Note
$SHIFT_KEY$ is not limited to the workflow that is defined to open a form in a new
window.
To use the $SHIFT_KEY$ keyword in workflow

1. Add a workflow object to a form or use an existing workflow object, such as a button.
2.
Page 2277 of 4705
Home
2. Create an active link and associate the workflow object with a form .
3. Define the execution options for the active link.
4. Under Execution Options, click the Field ellipsis button and select the control field you chose
in step 1.
5. Under the Run If Qualification section, enter a qualification with that verifies whether the
Shift key was pressed (for example, $SHIFT_KEY$ = 1.)
This qualification validates whether the Shift key is pressed. If the $SHIFT_KEY$ keyword is
used, the value is set to 1 when the Shift key is pressed while starting the workflow from a
control field (in this case). Any other value represents that the Shift key is not pressed.
6. Add an Open Window If action.
Select a window type.
For the Target Location field, select New.
7. Add an Open Window Else action.
Select a window type.
For the Target Location field, select Current.

Use the AR System Navigator (see the following figure) to open object lists and create objects.
AR System Navigator
Page 2278 of 4705
Home
The AR System Navigator contains a tree for each connected server. The following server icons
signify information about the server:
Server icons
Icon
Represents
Disconnected server
Server, logged in as administrator
Server, logged in as subadministrator
Page 2279 of 4705
Home
For information about subadministrator access to objects, see Subadministrator security role.
The AR System Navigator gives you access to:
Working Lists Lists of server objects that you use to complete an application
development or maintenance task.
Use the special Reserved Objects working list to access reserved objects. For information
about object reservation, see Version control in BMC Remedy AR System .
For more information, see Using working lists.
Applications Applications defined on the server.
See Working with applications and packing lists and Defining and managing an application.
Packing Lists Functional units that contain an administrator-defined grouping of
information. For example, if an application contains ten forms, each form and its related
workflow can be organized in its own functional unit, or packing list.
See Working with applications and packing lists and Packing lists.
All Objects All of the object types that you can define in BMC Remedy Developer Studio,
for example, forms, active links, and so on.
Double-click an item (such as Forms) to open an object list. From the object list, you can
access the objects of that type.
See Using the Outline tab and Working with existing objects.
Note
Working lists, applications, and packing lists provide another way to access server
objects found under All Objects. Using these containers can reduce the time to find
objects that you need to access.

Perspectives define the window's layout in BMC Remedy Developer Studio. Use Eclipse
commands to:
Customize an existing perspective.
Use the alternative Editor perspective to view only the tabs and editors you need when you
are editing an object. (See Editor perspective.)
Create a custom perspective.
This section describes the following topics:
Arranging tabs in a perspective
Editor perspective
Working with custom perspectives
Page 2280 of 4705
Home
Arranging tabs in a perspective

The default layout of the Developer perspective includes five groups of tabs arranged around the
editor area. Each tab group has command buttons that apply to the tab in the group that is selected
.
To open a closed tab

Select Window > Show View and select the view (tab) from this submenu.
The Analyzer, Progress, Relationships, and Search Results tabs open automatically
when needed.
To access a tab in a tab group that is not visible

1. Click the Show List button at the right of the tabs.
2. In the list of views or editors, click the one to show.
The views whose tabs are not visible are shown in boldface in the list.
To change the order of tabs in a tab group

Click and drag the tab to its new location.
To move a tab to another area in the window

1. Click and drag the tab until the mouse pointer becomes an arrow.
The arrow points to the location for the tab.
2. Drop the tab when the grey drag frame is where you want the new tab group.
Editor tab groups must be in the editor area.
Use this procedure to work with editors or object lists side by side or one above another.
To move a tab from one tab group to another

Click and drag the tab into the destination tab group.
The following figure shows the result of dragging the Properties tab into the tab group with
the Outline tab.
Outline and Properties tabs in one tab group
Page 2281 of 4705
Home
To minimize or maximize a tab group

Click Minimize or Maximize.
Toolbars, called shortcut bars, in the margins of the application window represent the
minimized tab groups. When you maximize a tab group, the other tab groups are minimized.
Tip
You can control where the shortcut bar for a tab group appears in the window
margins by dragging it to the location you prefer. For example, you can drag all the
shortcut bars to the status line so that the left and right margins do not get wider
when you minimize a tab group.
To work in a minimized view tab group

1. Click the tab's icon (not the Restore icon) for the tab that you want to use.
The tab opens temporarily.
2. Perform the operations in the open tab.
3. Click the tab's Minimize button to minimize the view again.
If you click any other tab or editor, the temporarily opened tab minimizes again.
Use this procedure to work in the Outline or Properties tab when you have an editor
maximized.
To restore a tab group

Click Restore in the minimized tab group toolbar.
If all other tab groups are minimized when one is maximized, clicking any Restore button
restores them all.
To detach a tab
1. Right-click the tab and select Detached.
2. Move and resize the detached window as needed.
Use this procedure to work in a maximized editor with the Outline or Properties tab in a
separate window on your desktop.
The following figure shows the Property tab detached with the form editor maximized.
Form editor maximized with Property tab detached
Page 2282 of 4705
Home
To reattach a detached view

Right-click the tab and select Detached to clear the check mark.
If the tab does not return to its previous position, use To move a tab from one tab group to
another and To reset the perspective to its default layout .
To reset the perspective to its default layout

1. Select Window > Reset Perspective.
2. Click OK in the confirmation dialog box.
Resetting the Developer perspective closes all object list views.
Editor perspective
BMC Remedy Developer Studio includes an Editor perspective, used for editing objects.
Editor perspective
Open the Editor perspective and switch to it when you need a large editor area. This perspective
has the Properties tab in the top right corner, the Outline in the bottom right corner, and the
Messages and Relationships tabs and the AR System Navigator in a tab group in the bottom left.
Working with custom perspectives

Use the following procedures to save, open, and switch to custom perspectives.
Page 2283 of 4705
Home
To save a custom perspective

1. Select Window > Save Perspective As.
2. In the Save Perspective As dialog box, give the perspective a name and click OK.
To open a perspective
1. Select Window > Open Perspective > Other.
2. In the Open Perspective dialog box, select the appropriate perspective and click OK.
Note
When you start BMC Remedy Developer Studio, it opens the perspectives that
were open when you last exited. If the perspective that has the input focus does
not display the AR System Navigator, BMC Remedy Developer Studio does not
display the Login dialog box. To display the Login dialog box, switch to a
perspective that displays the AR System Navigator or open it in the current
perspective.
One way to use a custom perspective is to set it up for specific work and switch to it when
you need it. For example, you can set up a Form Edit perspective as shown in the Form
editor maximized with Property tab detached figure and switch to it to edit a form.
To switch to another open perspective

Click the icon or name of the perspective in the Perspective bar in the top left corner of the
BMC Remedy Developer Studio window.
Creating objects
In addition to the File > New menu, the AR System Navigator provides a direct way to create an
object on a specific server or in a specific application.
To create an object on a server

1. In the server branch, open the All Objects branch.
2. Right-click the appropriate object type, and select the appropriate New menu command.
The object editor opens.
3. Modify the object.
For more information, see Modifying object properties and the sections listed in the following
table.
Where to learn how to create and modify objects
Page 2284 of 4705
3.
Home
See:
To create:
Setting up the development environment

Applications
Forms
Images
Menus
Packing lists
Active links
Active link guides
Escalations
Filters
Filter guides
Publishing the BMC Remedy AR System functionality as a web service
Web services
Creating associations
Associations
Adding graphics to an application with flashboards
Flashboards
Flashboard alarms
Flashboard variables
Distributed mappings
Distributed pools
To create an object in an application

1. In the Applications branch, right-click the name of the application and select New Object >
New objectType.
2. Complete any initial dialog boxes.
The object editor opens.
For more information, see Modifying object properties and the guides listed in the following
table.
For information about creating applications, see Working with applications and packing lists .
The Save objectType As dialog box appears.
4. Type the name of the object.
Object names must be unique for each BMC Remedy AR System server. Names can be as
many as 80 characters, including spaces.
Note
There are no other restrictions on names, but it is helpful to establish naming
conventions for your work and to make names descriptive.
5. Click OK.
Page 2285 of 4705
Home
To create a workflow object from the forms object list

1. Right-click a form in the forms object list.
2. Select New Workflow > workflowObject.
The workflow objects you can select are:
Active Link
Filter
Escalation
Active Link Guide
Filter Guide
3. Enter the information in the workflow object's editor.
For more information about creating workflow, see Defining workflow to automate processes.

The following sections describe some basics about working with objects:
Opening an object for editing
Renaming objects
Modifying object properties
Updating change history
Providing help text
Modifying the attributes of two or more objects
Exporting objects
Deleting objects
Opening an object for editing

This section introduces the BMC Remedy Developer Studio editors. See the Where to learn how to
create and modify objects table for references to the detailed documentation of the editors.
When you work on a form in the form editor, the editor and the associated views might look like the
following figure.
Note
The Palette on the right side of the form editor controls the editor cursor for selecting and
creating fields. The Select and Marquee options on the Palette enable you to select one
or more fields at a time. If you use the Select option, press the CTRL key to select
subsequent fields. If you use the Marquee option, press and hold the left mouse button as
you drag across multiple fields to select them.
Page 2286 of 4705
Home
Form opened for editing in BMC Remedy Developer Studio

When you open a workflow object, the object appears in the editor area (see the following figure).
The workflow object is organized by panels that contain information about the object. To open and
close a panel, click the heading.
Filter opened for editing in BMC Remedy Developer Studio
To open an object for editing

Double-click an object in any of the following places:
An object list
The Relationships tab
The Search Results tab
If you change an object and do not save your changes, the name of the object on the
editor's tab has an asterisk before it.
To close all editors

Right-click the tab for any editor and select Close All.
Page 2287 of 4705
Home
When you exit BMC Remedy Developer Studio, all editors are closed.
Renaming objects
Follow the steps given below to rename an object:
1. If the object is open for modification, close the editor.
2. In an object list or the Search Results tab, right-click the object and select Rename.
3. In the Rename dialog box, type the new name and click OK.
Object names must be unique for each BMC Remedy AR System server. Names can be as
many as 80 characters, including spaces. Application and packing lists have a single set of
names, so you cannot create an application and a packing list with the same name.
When you rename an object, all references in any related object (for example, an active link
attached to a form) are automatically updated.
Modifying object properties

The Properties tab (see the following figure) displays the properties of the object, field, or form
view in the active editor. Read-only properties are shown with a grey background.
Properties tab for a field in Best Practice Customization mode
If you are working on a form, click in any empty area of the form to see the properties for the form's
view. Click a field to see the properties for a field. For more information, see the following sections:
Setting form view properties
Field properties
To switch the Properties tab between the category and single list layouts
Click the Show Categories toggle button.
Page 2288 of 4705
Home
To sort the properties alphabetically by name

Select the Sort Properties toggle button.
To return the properties to their default order, click the Sort Properties toggle button again.
To pin the property view to the current selection

Select the required field and click the Pin this property view to the current selection
button.
For example, if you select the Submitter field and then click on the Pin this property view
to the current selection button, the property details for the Submitter field will be displayed
, even if you select another field. If you open another property view and pin any other field
using this button, you can compare the properties of these two fields.
To modify a property
1. Select the property in the Properties tab.
2. Edit the value in the Value column.
For numeric and short text values, type the value in the Value column.
For properties with a list of valid values, click the arrow and select a value from the list
.
For long text and other complex values, click ellipsis (...) to open a dialog box and
specify the value.
3. Press Enter or click elsewhere to accept the new value. Press Esc to cancel the property
change.
Changes to object properties are saved to the server when you save the object.
For references to the detailed documentation of the editors and the dialog boxes for the
various properties, see Where to learn how to create and modify objects .
Updating change history

For each server object that you create, BMC Remedy AR System server automatically records the
owner (the user who created the object), the user who last modified the object, and the date and
time of the last modification. You can view and, in some cases, modify this history information in the
Change History category in Properties tab or (for forms) the Definitions tab.
To update the change history of a form

1. Open the form for modification.
2. Click the Definitions tab, and expand the Other Definitions panel and then the Change
History panel.
3. To change the ownership of the object, in the Owner field, enter the user name of the new
owner.
Page 2289 of 4705
3.
Home
Note
Any user with Administrator or Subadministrator permissions can modify a form,
regardless of who the specified owner is for the object.
4. In the New Description field, type information about the object or about the change that you
made.
5. Save the form.
A time stamp, your user name, and the text that you typed appear at the beginning of the
Change History field.
To update the change history of a field or of an object other than a form

1. Open the object for modification or select the field in the form editor.
2. To change the ownership of the object, in the Owner property, enter the user name of the
new owner.
Note
Any user with Administrator or Subadministrator permissions can modify an object
or field, regardless of who the specified owner is for the object.
3. In the New Description property, click ellipsis (...).

4. In the New Description dialog box, type information about the object or about the change
that you made, and click OK.
A time stamp, your user name, and the text that you typed appear at the beginning of the
Change History property.
Providing help text

You can provide help text for forms and fields.
Help for browser users

To create help for users viewing forms in a browser, add a Form Help button to a form. When
users click the Form Help button, information about the form and each of its fields appears. For
more information, see Adding form action fields to a form .
To create context-sensitive help text

1. Open an object in BMC Remedy Developer Studio.
2. Access the help text:
Page 2290 of 4705
2.
Home
For the form help text, select the Definitions tab. Expand the Other Definitions
panel and then the Help Text panel.
For a field, select the field, and select the Help Text property.
For other objects, open the object, and select the Help Text property.
3. In the Help Text field, type the text for the users.
4. Save the object.
Help for administrators

For all other server objects (except forms), the help text you create is available only to
administrators and subadministrators in BMC Remedy Developer Studio. You can, however,
compose extra help text for guides that users can see in the mid tier as they are guided through a
form or a series of forms. For more information, see Defining guides and guide actions.
To learn about creating help for applications, see Specifying Help properties for an Application
mode.
Accessing help outside of BMC Remedy Developer Studio

The online help for BMC Remedy Developer Studio is packaged in an Eclipse plug-in named
com.bmc.arsys.studio.help_VerNum. (For BMC Remedy Data Import, the plug-in is named
com.bmc.arsys.dataimport.help_VerNum.)
To access help outside of BMC Remedy Developer Studio

1. In com.bmc.arsys.studio.help_VerNum, locate the doc.zip file, and unzip the file to a
location where you want to store the help files.
These files do not include a table of contents or an index; they are simply the topic files of
the help.
2. Browse to the folder and launch any of the files to view a topic.
For BMC Remedy Data Import, follow these steps, but go to the
com.bmc.arsys.dataimport.help_VerNum plug-in.
Modifying the attributes of two or more objects

Follow the steps given below to modify attributes of two or more objects:
1. (Optional) Reserve the objects you want to modify.
For more information, see Version control in BMC Remedy AR System .
2. Select objects in an object list.
3. Right-click and select Edit.
4. In the Edit dialog box, select the appropriate page.
The following table lists which pages are included for each object type. If you select objects
of different types, only the common pages are included.
Edit dialog box attribute pages for each object type
Object type
Edit dialog box attribute page
Page 2291 of 4705
Home
Associated Forms
Execution Options
Permissions
Change History
Help Text
Rename
Active link
Active link guide
Application
Escalation
Filter
Filter guide
Image
Menu
Form
Packing list
Web Service
5. To associate forms with workflow:

a. Select the Associated Forms page.
The Associated Forms list includes all forms associated with any selected object.
b. Click Add.
c. In the Form Selector, select the forms to associate and click OK.
To filter the list of forms, type a pattern in the Name field. To move to a form in the list
, type the first characters of the name in the Locate field.
d. In the Edit dialog box, click Apply to associate the form or OK to associate the forms
and close the dialog box.
6. To change workflow execution options:
a. Select the Execution Options page.
Only execution options that apply to all workflow types selected are shown. A square
in the check box indicates that some but not all of the selected objects have that
execution option enabled.
b. Select or clear the check boxes to set the appropriate execution options.
c. To change the execution order, select an operation from the list and type an integer in
the field.
d. Click Apply to update the execution options, or click OK to update the execution
options and close the dialog box.
7. To change object permissions:
a. Select the Permissions page.
In the Permissions list, the Applicable To column displays one of the following
conditions:
All Objects The group or role has permissions for all of the selected objects
.
Some Objects The group or role has permissions to some of the selected
objects.
b.
Page 2292 of 4705
Home
b. To assign permission to a group or role for all of the objects selected, click in the
corresponding Applicable To and select All Objects.
c. To assign permissions to new groups or roles, use the arrow buttons to move the
appropriate groups and roles into the Permissions list.
d. To change access levels (for example, Visible or Hidden), for each group or role in
the Permissions list, click the drop-down menu in the Permission column and select
the correct access level.
Note
To assign permissions for one group to multiple objects, see Assigning
permissions.
8. To update the change histories:

a. Select the Change History page.
b. In the New Description field, type an update description.
9. To update or replace the help text:
a. Select the Help Text page.
b. In the Help Text field, type the new help text.
c. To append the new text to the existing help text for each object, select the Append
check box.
10. To rename the selected objects:
a. Select the Rename page.
b. Select the option for the type of renaming you want:
Replace
Prefix
Append
c. Complete the fields as needed.
For example, to add Sales- to the beginning of all of the selected objects, select
Prepend, and enter Sales-.
11. Click OK to apply the changes and close the dialog box.
Exporting objects
You can export object definitions from one server and import them to another server.
To export objects
Use one of the following methods:
To export specific object types

1. In an object list, select the objects that you want to export.
2. Right-click and select Export to File.
3.
Page 2293 of 4705
Home
3. Complete the wizard that appears.
To export several different object types

1. Select File > Export.
2. Complete the wizard that appears.
For information about exporting and importing, see Importing and exporting object definitions
and locking objects.
Deleting objects
When deleting server objects, remember the following important facts:
If you delete a primary or secondary form of a join, the join form is also deleted.
You cannot delete an object that is open for modification in BMC Remedy Developer Studio.
When you delete a form, all associated data and workflow that is not associated with any
other form is deleted. If workflow is shared by multiple forms, it is not deleted until the last
form that uses it is deleted. Menus, applications, and packing lists must be deleted
separately because they are independent of forms.
When you delete an archive or audit form, the archive or audit properties for the base form
are cleared. See Managing data for details about archive and audit.
To delete an object
1. If the object is open for modification, close the editor.
2. In an object list or the Search Results tab, select the objects to delete.
The objects are removed from the server database.
Finding objects
Use the following methods in BMC Remedy Developer Studio to find the server objects that you
need to view or modify:
Browse the AR System Navigator (see Browsing the AR System Navigator)
Use object lists (see Using object lists)
Use the Search menu option (see Using the Search menu option)
View and sort related objects (see Viewing and sorting related objects)
Use working lists (see Using working lists)
For information about creating and modifying objects, see Creating objects and Working with
existing objects.
Page 2294 of 4705
Home
Browsing the AR System Navigator

To find objects on a server in the AR System Navigator, open a branch on the tree and double-click
the object. The AR System Navigator view opens automatically when you start BMC Remedy
Developer Studio.
If you open a working list, application, or packing list, it appears in an object list tab with panels that
allow you to explore the working list, application, or packing list.
If you double-click an object type (such as Forms) in the AR System Navigator, an object list
appears. Then, you can double-click an item (such as a form) in the object list to open it.
Using object lists

When you open an object from AR System Navigator, objects are displayed in an object list. Each
object list that you open appears in a separate tab.
Object lists tab group
To open an object list

In the AR System Navigator, double-click a working list, application, packing list, or object type item
.
To open a large object list without timing out

If time-out problems occur when you try to open an object list, use one of the following procedures
to selectively display the columns in the list for that object type:
Display only the Basic Columns in the list.
Do not display columns that are not required.
Display only the Basic Columns in the list

1. Select Window > Preferences to open the Preferences dialog box.
2. In the BMC Remedy Developer Studio branch, click Object List View.
3. In the Object List View panel, select the appropriate object type.
4. Select the Basic Columns option.
5. Click OK.
Page 2295 of 4705
Home
The object list for the selected object type should now open quickly because it contains only the
basic columns of each object.
Do not display columns that are not required

2. In the BMC Remedy Developer Studio branch, click Object List View.
3. In the Object List View panel, select the appropriate object type.
4. Choose a column that is not required and click on the Display settings for the column.
5. Select No from the Display drop-down list. (See the following image.)
Columns with Display set to No are not fetched from the database. This reduces the time
taken to load the object list in BMC Remedy Developer Studio.
Hiding certain CLOB columns also improves the time taken to load the object list. You can
hide the following CLOB columns:
CLOB column
Object type
Lock State
Present on all object types
Access Point
Applicable to Form and Guides
Pool Number
Escalation
The columns Primary Form and Shared are not CLOB, but hiding these columns increases
performance .
To sort the contents of an object list

Click a column heading to sort the list by that column. Use this method to bring together items with
common values.
Page 2296 of 4705
Home
To expand or collapse a panel in an object list

Click the triangle or the text on the panel header. The first item in the list that begins with those
characters is selected.
To locate an object in an object list

1. Select an object in the list.
2. Enter the first few characters of the name of the object that you want to find.
To filter the contents in an object list

1. Click Filtering Options text at the top of the object list to open the filtering options panel.
2. From the first drop-down list, select the column to use to filter the object list.
For a single object list, the columns shown are the columns in the list. For an application,
packing list, or working list views and for search results, the columns shown are the columns
configured for all object types in the list.
3. From the second drop-down list, select the compare operation.
The compare operations available depend on the data type of the column selected.
4. In the text field, type the value to match.
To refresh objects in a list

Select File > Refresh. The Refresh option is useful when you add objects to an application but the
objects are not immediately visible in the application object list. For example, when you attach a
menu to a field on a form in an application, the menu is associated with the application, but the
application list might not immediately recognize that association.
To change the columns shown in an object list

2. In the BMC Remedy Developer Studio branch, click Object List View to show the Object
List View preferences.
3. In the list, select the object type.
4. To display only the Name column, select the Basic Columns option, and go to step 9.
Selecting Basic Columns is useful if an objects list has tens of thousands of objects, which
could potentially cause a time-out when you try to open the object list.
5. If the All Columns option (the default) is selected, change the value in the Display column to
show or hide columns in the object list.
6. Use the Up and Down buttons to position the columns.
7. Use the Import button to read column preferences from an XML file, or use the Export
button to write preferences to an XML file.
8. Click Restore Defaults to restore the object list configuration for the selected object type to
the defaults.
9. Click OK to save your changes.
10. Close and reopen the object list to see your changes.
Page 2297 of 4705
Home
To change the layout of an object list

Click the appropriate layout button in the object list tab group toolbar (see the following figure
).
Single list (
View by type (
View by form (
Object list view by form

Note
Switching a list of many objects to single list layout can take some time as
information about all of the objects is retrieved.
To close an object list

Click Close on the list tab.
To close all object lists

Right-click any item in the AR System Navigator and select Close all open Object Lists from the
pop-up menu.
Using the Search menu option

With the Search menu option, you can search for objects based on criteria that you define and
show the relationships for objects. The Search Results tab lists the forms whose fields or the
objects whose attributes, properties, and field references match a text string or field ID that you
specify. For example, use Search to find:
All forms with fields whose name is, begins with, or contains the search string
All objects of a given type whose name is, begins with, or contains the search string
All workflow objects of a given type that have an associated form whose name begins with or
contains the search string
All workflow objects of a given type that reference a field with a specified name
Page 2298 of 4705
Home
Note
To search for objects, BMC Remedy Developer Studio uses object relationships that the
BMC Remedy AR System server records. For the Show Relationships option to be
available, you must enable the relationships feature. See To enable the relationships
feature. Sample data objects in Set Fields and Push Fields actions have meaning only at
design time, so the server does not record relationships for sample data objects, and a
search cannot find sample data objects.
To find objects that are related to a specific field or object, see Viewing and sorting related objects.
To search for objects that contain specified text

1. Select Search > Search to open the Search dialog box (see the following figure).
Search dialog box
2. Click the String Search tab.

3. In the Server field, select the server to search in.
4. In the Search Text field, enter the text to find.
5. To search for a field ID, select Treat as Field ID and ensure that Search Text specifies a
positive integer.
6. From the Search In list, select the option that describes the types of object lists in which you
want to search:
Views; Fields
Forms; Workflows; Guides (the default)
Applications; Packing Lists
Groups; Roles
Menus
Web Services
Flashboards; Flashboard Alarms; Flashboard Variables
All
More Options
If you want to select a different combination of object lists, select "More Options."
7.
Page 2299 of 4705
Home
7. (Optional) Open the Qualifications panel (see the following figure) and select options that
further narrow your search.
Qualifications panel
The options on this panel are:

Only Selected Objects Enables you to select a specific set of objects on which to
search.
Objects Modified Between Searches for objects that were modified in a specific
date range.
Only These Locations Searches for objects by type and location:
Object Type Defines the objects in which you want to search (for example, forms,
fields, active links, and so on).
Target Text Location Defines where you want to search (for example, you might
want to search only fields IDs or only form names).
To search two or more object types or locations, select additional object types and
locations in other rows.
To add a row, click a plus ( +) button. To remove a row, click its minus ( -) button.
Only the Following Enables you to narrow your search to specific options (such
as execution options for workflow objects).
8. (Optional) Open the Match panel, and select options that further narrow your search.
Match panel
a. Select an option in the Match area:

Match Target Text Exactly
Match the Beginning of the Target Text
Match Anywhere in the Target Text
String constants are stored in encoded format in BMC Remedy AR System
server. Although the goal of the search functionality is to use the option that
you specify when searching in string constants, the "Match Anywhere in the
Target Text" option might be used when string constants cannot be matched
with the option you selected.
Note
Page 2300 of 4705
Home
You cannot search on the Change History field with the Match
Target Text Exactly or Match the Beginning of the Target Text option
selected. Change History is stored on the server with a timestamp
and a user name, so you cannot obtain an exact match or beginning
match.
b. To search by using string constants, select Match String Constants.

To narrow the search further, select Match Only String Constants, Not Names. When
you select this option, the Match option automatically becomes "Match Anywhere in
the Target Text."
c. To search by using keywords, select Match Keywords.
To narrow the search further, select Match Only Keywords, Not Names.
9. (Optional) To save the search as a working list:
a. Open the Working Lists panel.
b. Select the Save Results as Working List check box.
c. In the Name field, enter a name for the working list.
10. Click Search.
The Progress tab displays the search progress. When the search is complete, the Search
Results tab displays a list of fields and objects.
Viewing and sorting related objects

Relationships of objects appear on the Relationships tab (the following figure), which lists all fields
and objects related to a selected field or object. The Relationships view appears automatically
when you select item from the Object List and run Show Relationships from the context menu.
You can use relationships to find:
All workflow objects that have a given form as an associated form.
All Open Window actions that open a given form.
All forms and fields that reference a given image or menu.
All images or menus that are referenced by any field in a form or by a particular field.
Only objects on the same server as the selected object are shown in the Relationships tab.
Relationships with objects in different servers, such as a Push Fields action to a form in a different
server, are not included.
Keywords are not objects, so the Relationships tab does not include keywords. For example, if a
keyword is related to a field in an active link Set Fields action, that relationship is not listed in the
tab.
Relationships tab
Page 2301 of 4705
Home
The Relationships tab contains the following columns.

Columns in the Relationships tab
Column
Description
Name
The name of the field or object.
Object Type
One of the object types listed at the beginning of this section.
Relationship
Type
One of the relationship types listed at the beginning of this section.
Field ID
For a field, its ID; otherwise, blank.
Form
For a field, the form it is in; otherwise, blank.
Action
For a workflow object and a relationship with a workflow action, the number of the action in the sequence of If or
Else actions; otherwise, blank.
Number
WS
Operation
For a relationship with a web service, the operation; otherwise, blank.
Important
For the Show Relationships option to be available, you must enable the relationships
feature. For more information, see the following section.
To enable the relationships feature

Server Information.
3. Select the Record Object Relationship check box.
4. Click Apply.
For more information, see Setting administrative options.
Page 2302 of 4705
Home
To list fields and objects related to an object

In an object list, the Relationships tab, or the Search Results tab, right-click an object and
select Show Relationships.
The Relationships tab lists the fields and objects related to the selected object.
To list fields and objects related to a field

In the form editor, right-click a field and select Show Relationships.
The Relationships tab lists the fields and objects related to the selected field.
Note
If two or more objects are selected in a list or two or more fields are selected in the
form editor, the Show Relationships command is not available.
To list fields and objects related to a field or object by selecting it in an editor

1. Select the Relationships tab.
2. Click the Link with Editor button (
).
3. Select a field or a workflow object.

Select a field in the form editor or Outline tab.
The Relationships tab lists the fields and objects related to the selected field.
Make a workflow editor active.
The Relationships tab lists the fields and objects related to the workflow object being
edited.
When you select Link with Editor, each time you select a field or workflow object, the
Relationships tab is immediately updated.
Miscellaneous commands in the Relationships tab

You can select only one item in the list. The Relationships tab does not allow multiple
selection.
To sort the list by the values in that column, click a column heading.
To open the object in its editor, double-click an item.
If the item is a field, it is selected in the form editor. If the item is a workflow action with an
action reference, the action is selected in the workflow editor.
To update the Relationships tab with the relationships of the selected item, right-click an
item and select Show Relationships.
To move back and forth through a history of relationship lists, click Previous (
To refresh the list, click Refresh (
).
).
Page 2303 of 4705
Home
Using associations
You can use associations to create relationships between two different forms and add qualifications
. The following topics are provided:
Direct associations
Related topics
Direct associations
Direct associations are primary key and foreign key associations between two forms. The multiple
fields from primary form can be used as a primary key and similarly, multiple fields from secondary
form can be used as a foreign key. In other words, each field in the primary key maps to a field in
the foreign key and is called direct association. The fields used for the primary key may or may not
be uniquely indexed. In BMC Remedy Developer Studio, you can create two types of direct
associations: one-to-one association and one-to-many association.
You can use two different forms for creating direct associations in BMC Remedy Developer Studio:
primary form and secondary form. You can also enforce associations between these two forms.
For information about how association enforcement works, see Associations enforcements.
Direct associations are helpful when you can establish a primary key foreign key associations
between fields of two forms that you want to associate.
Highlights
A direct association is a direct relationship between two forms.
This association is used wherever there is parent-child kind of relationship, such as purchase
order to purchase order line item.
This association supports one-to-one and one-to-many relationships.
Multiple fields from the primary form can be the primary keys and similarly multiple fields (the
number of fields in the secondary form should be same as primary form) from the secondary
form can be foreign key. Each field of the primary key maps to a field in the foreign key. This
association is also referred to as PKFK mapping.
The fields used for the primary key must be uniquely indexed for best results.
Indirect associations are the associations created using an association form apart from primary and
secondary forms. This form stores the foreign key for both the primary and secondary forms.
Multiple fields from the primary form can be mapped to the same number of fields on the
association form and similarly multiple fields from the secondary form can be mapped to same
number of fields on association form. In BMC Remedy Developer Studio, you can create three
types of indirect associations: one-to-one association, one-to-many association, and
many-to-many association.
Page 2304 of 4705
Home
You can create indirect associations in BMC Remedy Developer Studio with the help of an
association form, along with the primary form and secondary form. You can also enforce
associations between these forms. For information about how association enforcement works, see
Associations enforcements.
Highlights
This type of association supports one-to-one, one-to-many, and many-to-many relationships
This association is used for describing peer relationship or loose relationship such as a
relationship between incident management and change management.
Records in the two forms are related to each other by creating a record into a third form
called association form.
Association form holds the foreign key for both primary and secondary form.
Multiple fields from the primary form can be mapped to the same number of fields on an
association form and multiple fields from the secondary form can be mapped to the same
number of fields on the association form.
Related topics
Modifying associations
Deleting associations
Associations are relationship object types that you can explicitly define in BMC Remedy Action
Request (AR) System. These objects help you create and manage relationships between forms for
various BMC Remedy AR System functions.You can use associations to get related entries using
REST API. For more information on using REST API to get associations, see get Associated
Entries using REST API.
You must create associations when you want to establish a relationship between two or more forms
in BMC Remedy Developer Studio. This relationship ensures that all the related form data is
archived along with the main form when you run the archive process when you have configured
associations to follow for the form which is getting archived. You can create two different types of
associations in BMC Remedy Developer Studio.
Note
You cannot create associations for join forms and archive forms.
For information about which associations to choose, see Using associations.
Page 2305 of 4705
Home
To create direct associations

To create indirect associations
Related topics
To create direct associations
1. In AR System Navigator, expand serverName > All Objects.

2. Right-click Associations, select New Direct Association, and enter the following
parameters:
a. Select the state of the association. The options are Enabled and Disabled.
b. Select the cardinality of the relationship between the primary and secondary form.
The options are: One to One and One to Many. For information about type of
associations, see Type of associations.
c. Select the Primary form for association.
d. Select the Secondary form to be associated with the primary form.
Note: Optionally, you can add qualifications using Advanced Options. For more
information about qualifications, see Associations qualifications.
e. Enter the description for the association.
f. To enforce associations, select the Enforced check box.
For more information about enforced associations, see Relationships.
g. Map the fields from the primary form to the secondary form using PKFK Field
Mapping.
If one or more fields used in key mapping or in qualification are deleted, the server
considers that association as invalid and it will not be functional until those fields are
created again.
Note
Only Character, Integer, Enum, Decimal, Real, Date, time, and timeofDay
fields are allowed for PKFK mapping.
h.
Page 2306 of 4705
Home
h. Select File > Save.

3. In the Save Association As dialog box, enter the name of the new association and click OK.
To create indirect associations
1. In AR System Navigator, expand serverName >All Objects.

2. Right-click Associations, select New Indirect Association, and enter the following
parameters:
a. Select the state of the association. The options are Enabled and Disabled.
b. Select the cardinality of the relationship between primary and secondary form. The
options are: One to One,One to Many, and Many to Many.
For information about type of associations, see Type of associations.
c. Select the Primary form for association.
d. Select the Secondary form to be associated with the primary form.
e. Select the Association form.
Note: Optionally, you can add qualifications using Advanced Options.
For more information about qualifications, see Associations qualifications.
f. Enter the description for the association.
g. To enforce associations, select the Enforced check box.
For more information about enforced associations, see Enforced associations.
h. Specify the Primary and Association form Field Mapping for comparing values
from the two forms.
considers that association as invalid and it is not functional until those fields are
created again.
i. Specify the Secondary and Association form Field Mapping for comparing values
from the two forms.
considers that association as invalid and it is not functional until those fields are
created again.
j. Select File > Save.
3.
Page 2307 of 4705
Home
3. In the Save Association As dialog box, enter the name of the new association and click OK.
Note
To use a newly added custom field in an association, you must:
1. Create the overlay of the base association and disable it.
2. Create a new custom association that involves fields used in base association and
the new custom field added in the overlay form.
Related topics
In the Associations list, right-click the name of the association and select Delete.
Note
When the primary form, secondary form, or association form is deleted, the related
associations are also deleted.
For modifying your associations, you must open your associations from the list in BMC Remedy
Developer Studio.
Page 2308 of 4705
Home
In Best Practice Customization mode, you can create an overlay of associations that are
defined in Base Development mode. You can create Overwrite type overlay for
associations and can enable or disable associations in overlay mode. For more
information about creating overlays, see Creating overlays for AR System objects.
To modify associations
1. In AR System Navigator, expand serverName> Associations, right-click the association
name, and select Edit.
2. In the Edit Association dialog box, modify the association as necessary.

For details about how to modify associations, see the following procedures:
a. To create direct associations
b. To create indirect associations
Note
To view all the associations related to a form, right-click the form and select associations.
Using working lists

You can create working lists to keep references to objects that you need to view, change, or export
to complete an application development or maintenance task. You can add and remove objects
from working lists as you work with them.
Descriptions of working lists are stored locally in your BMC Remedy Developer Studio workspace.
Working lists refer to objects on the BMC Remedy AR System server, but the server does not
record any information about working lists or an object's membership in them.
BMC Remedy Developer Studio has the following types of working lists:
View-by-form list Contains one or more BMC Remedy AR System forms and all objects
related to them.
Application view-by-form list Contains one or more BMC Remedy AR System forms
from one application and all objects related to them.
Page 2309 of 4705
Home
Related list Contains one or more BMC Remedy AR System server objects and
optionally either directly related objects or all related objects.
Reserved Objects Contains all objects reserved on a BMC Remedy AR System server
with object reservation enforced. (Subadministrators see only those objects they have
reserved.) This list cannot be modified or deleted. See Version control in BMC Remedy AR
System.
Search list Contains the list of objects that is defined through a Search.
Every time you open a working list, the list is updated with the current related objects. For example,
if a filter is created that is associated with a form in a view-by-form list, the new filter is included the
next time that you open the list.
Note
Although there is no limit on the number of objects in a working list, lists with many objects
, included related objects, are slower to open than lists with fewer objects.

Creating working lists
Modifying working lists
Exporting and saving working lists
Deleting working lists
Creating working lists

Follow the steps given in this section to create working lists.
To create a view-by-form list

1. In the AR System Navigator, expand serverName, right-click Working Lists, and select New
View by Form List.
2. In the New View by Form List dialog box, enter the List Name.
3. Click Add.
4. In the Form Selector dialog box, select one or more forms to include in the list, and click OK.
To filter the list of forms, type a pattern in the Name field. To move to a form in the list, type
the first characters of the name in the Locate field.
Use the usual Windows methods to select multiple objects. For example, hold down the
CTRL key and click an item to select or clear it.
5. Click OK to save the list.
Page 2310 of 4705
Home
To create a view-by-form list including only forms from an application

1. In the Applications branch in the AR System Navigator, right-click the application name and
select New Application View by Form List.
2. In the New Application View by Form List dialog box, enter the List Name.
3. Click Add.
4. In the Form Selector dialog box, select the forms to include in the list, and click OK.
The Form Selector dialog box lists only the forms in the application. To further filter the list of
forms, type a pattern in the Name field. To move to a form in the list, type the first characters
of the name in the Locate field.
To create a related list

1. In the server branch in the AR System Navigator, right-click Working Lists and select New
Related List.
2. In the New Related List dialog box, enter the List Name.
3. Click Add.
4. In the Add Items dialog box, select the objects to include in the list.
To filter the list of objects, type a pattern in the Name field, select an application from the
Application drop-down list, or clear the appropriate Object Category check boxes. To move
to a form in the list, type the first characters of the name in the Locate field.
5. In the Add Items with Related Property drop-down list, select to add any of the following:
Only the objects selected
The object and directly related objects
The objects and all related objects
For applications and packing lists, the object and its contents
For descriptions of the related options, see Exporting object definitions, views, and
applications.
6. Click OK.
7. To see which objects will be included in the list, in the Related List dialog box, select an
object and click Show Related.
8. To change which related objects are included in the list with the selected object, select the
objects in the list and click and change the value in the Related column or click the buttons.
applications.
Note
When you export objects, you can select an option to create a related list
containing the exported objects.
Page 2311 of 4705
Home
To create a search list

1. In the server branch in the AR System Navigator, right-click Working Lists and select New
Search List.
2. In the List Name field, enter a name for the search list.
3. Complete the rest of the fields as described in To search for objects that contain specified
text.
Alternatively, you can create a search list by completing the Working List panel when you
perform a search as described in To search for objects that contain specified text .
4. Click OK.
Modifying working lists

1. In AR System Navigator, expand serverName > Working Lists, right-click the list name,
and select Edit.
2. In the Edit View by Form List or Edit Related List dialog box, modify the list as necessary.
For details about how to modify working lists, see the following procedures:
To create a view-by-form list
To create a view-by-form list including only forms from an application
To create a related list
To create a search list
Exporting and saving working lists

Follow the steps given below to export and save working lists.
To export the objects in a working list

1. In the Working Lists branch of the server branch in the AR System Navigator, right-click the
name of the list and select Export Working List Content.
2. In the Export To File dialog box, select or enter a file to write the object definitions to.
3. Click Save to start the export operation.
applications.
To save a working list as import/export commands

1. In the Working Lists branch of the server branch in the AR System Navigator, right-click the
name of the list and select 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 the use of this XML file, see Using buttons and menu bar items to execute active links .
Page 2312 of 4705
Home
Deleting working lists

In the Working Lists branch of the server branch in the AR System Navigator, right-click the name
of the list and select Delete.

The Outline tab displays a visual overview of the object in an editor. Use it to navigate within the
editor. When you select an item in the outline, it is also selected in the editor and vice versa.
When you are editing a form, the Outline tab contains the following icons:
Show Tree Overview ( ) Displays all of the fields (ordered by field ID) on the current
form view in a tree format. See the Outline tab with Show Tree Overview displayed figure
below.
Show Table Overview (
) Displays all of the fields on the current form view in a table
format. You can click on the columns to sort by field ID or by name.
Show Fields Not in View (
) Displays fields that are not in the current or selected view
including the fields that are not in any view. The fields created from this view are not present
in any view. In Best Practice Customization mode, you can create or delete Field Overlay of
these fields. You can also see such fields by choosing Form > Add/Remove Fields In View
(they are listed in the left pane of the dialog box). See Including and excluding fields from
form views.
Show Zoom Overview (
) Displays a small picture of the form view with a gray box
that you can move to focus the editor on a specific area of the form. See the Outline tab with
Show Zoom Overview displayed figure below.
Outline tab with Show Tree Overview displayed
Page 2313 of 4705
Home
Outline tab with Show Zoom Overview displayed
You can view the list of all fields contained in all views of form. If you have created multiple views
for a form, you can view a list of all fields contained in all forms. The Outline view also lists the
fields that are not in view.
To view all fields in the Outline view

1. Open BMC Developer Studio in the Best Practice Customization mode.
2. From the object list and open the form to view.
The Outline view lists the fields in all views of the selected form.

When an editor is active, the Messages tab lists any warnings about the object that you are editing.
They often note fields that must be completed before you can save the object.
The tab also shows a count of all messages. If you minimize the Messages tab, the minimized icon
shows the highest severity, and the counts are shown on a tool tip.
To fix a problem described in a warning

1. Double-click the message in the Messages tab.
If the message is linked, the insertion point moves to the item in the object editor that you
must change.
2. Fix the problem reported in the message.
Page 2314 of 4705
2.
Home
Note
When you try to save an object and the BMC Remedy AR System server returns
an error, that error is listed in the Messages tab, but it is not linked to the object in
the editor.
Printing from BMC Remedy Developer Studio

In BMC Remedy Developer Studio, you can print an image of the following tabs and editors:
Form editor
Workflow editor
Analyzer tab
Relationships tab
Search tab
Outline tab
Properties tab
Event Navigator tab
For the workflow editor, open all of the panels; otherwise, any panels that are closed are also
closed in the image.
For the tabs, enlarge the tab before you print so that more of the area appears in the image.
To print an image of the content in an editor or tab

1. In BMC Remedy Developer Studio, place focus in the editor or tab that you want to print.
3. Select the options you want for your document.
4. Click Print.
Clearing BMC Remedy Developer Studio cache

All the BMC Remedy Developer Studio objects are added to Developer Studio cache when you
open them for the first time. However, in some instances where the cache is either corrupted or not
updated, you might have issues accessing the latest objects. In such cases, you must use the
Clear Cache option in Developer Studio to clear the objects from the cache and get the latest
objects from the server.
To clear the developer studio object cache

2. Right-click the AR System server in the AR System Navigator and click Clear Cache.
A confirmation dialog box is displayed which provides the location of the cache.
3. Click OK.
Page 2315 of 4705
Home
After clearing the cache, if you have access to the cache location mentioned in the confirmation
dialog box, you can check whether the cache is cleared.
Creating reports for selected objects

In BMC Remedy Developer Studio, you can create reports that detail the properties of the following
BMC Remedy AR System server objects:
Working lists
Applications
Packing lists
Objects in object lists
Objects in packing list
For more information, see To create a report about selected objects .
You can also create reports from the following tabs:
Analyzer Results tab
Relationships tab
Search Results tab
For more information, see To create a report from a tab .
Reports are available in PDF, RTF, or HTML format.
To create a report about selected objects

1. Select the objects for the report:
In the AR System Navigator, select a working list, application, or packing list.
In a packing list, select an object.
In an object list, select one or more objects.
2. Right-click and select Document.
The Document Objects dialog box appears, displaying the Select Objects page, as shown in
Document Objects dialog box
3.
Page 2316 of 4705
Home
3. To add more objects to include in the document:

a. Click Add.
b. In the Add Items dialog box, use the Filtering Options section to filter the options that
are listed.
c. From the list, select the objects you want to add. (Use the CTRL or SHIFT key to
select more than one object.)
d. From the Add Items with Related Property list, select one of the following options:
Object Only
Directly Related Objects
All Related Objects
For object descriptions, see the Exporting object definitions, views, and
applications section.
e. Click OK.
4. (Optional) To change which related objects appear in the document, in the Document
Objects dialog box, select an object, and click the appropriate button:
Object Only
Directly Related Objects
All Related Objects
5. Click Next.
The Output Details Page appears as shown in the following figure.
Output Details Page
6. On the Output Details Page, select the options for your document.
a. (For objects that contain forms) To create separate reports that outline information
about the fields on the selected forms, select the Document Fields option, and then
select one of the following options:
Summary Lists a summary of details about each field. Details include field
name, ID, type, length, and permissions. One summary document is created.
Detail Lists details about the properties of each field on the selected forms.
A separate document is created for the each form. The names for these
separate documents include a prefix (if any), the form name, and a suffix called
_Fields.
For example, if you document the AlertList and Adhoc:Dialog forms (with a
prefix of doc), a doc_forms document is created to describe the two forms.
Additionally, the following documents are created to describe the details about
Page 2317 of 4705
Home
the fields: doc_AlertList_Fields and doc_Adhoc_Dialog_Fields. (Special

characters, such as colons [:], are replaced with a underscores [_].)
The Document Fields option is disabled if you did not select any forms for the
report.
b. To specify what appears in the report for all objects, select one of the following
options:
Regular Lists all of the properties of the object
Help Text and Change History Lists details about help text and change
history only
c. In the Output Details section, select one of the following options:
To File If you select this option, select the file format (RTF, PDF, or HMTL).
Optionally, include a prefix to add to each document's file name. Enter the path
to the output folder.
To open the folder that contains the files after you click Finish, select the
Show Output Folder When Complete check box.
Note
The PDF option cannot generate Japanese characters. For objects in
Japanese locales, select RTF or HTML.
To Printer Click Print Setup to select a printer.

7. Click Finish.
The Progress tab displays the progress of the report creation.
A document is created for each object type that you selected. For example, if you selected
forms and their related objects, and active links were related to the forms, two documents
would be created one for the forms and one for the active links.
To create a report from a tab

1. In BMC Remedy Developer Studio, place focus on the tab for which you want to document:
Analyzer Results, Relationships, or Search Results.
2. Select File > Document.
3. Select a location for the file.
4. In the File Name field, enter a name for the report.
5. From the Save as Type drop-down list, select a file format:
PDF
RTF
HTML
6. Click Save.
Page 2318 of 4705
Home

This section includes questions that you might have about BMC Remedy Developer Studio and
their answers.
Q: How do I log on as a different user or change the server list?

A: Select File > Login to display the Login window.
Q: Why does a single click in AR System Navigator not show the list of objects?
A: Selecting an item in AR System Navigator does not open the object list. You must double-click to
open it. This way, you can have multiple object lists open at the same time.
Q: How do I open a missing tab?

A: To open an object list, double-click an item in an AR System Navigator sub-tree. To open
another tab, select Window > Show View > viewName.
Q: Can I run multiple instances of BMC Remedy Developer Studio?

A: Yes, but you must use different workspaces. When you start BMC Remedy Developer Studio,
you are prompted for a new workspace if the references workspace is already in use. You can also
switch workspaces from within BMC Remedy Developer Studio using the File > Switch
Workspace command.
Q: How do I display two editors side by side?

A: Drag the Editor tab to the edge of the editor window. Drag it back on or next to the other tabs to
stack the editor again.
Q: What is the function of the Design tab at the bottom of the Application, Guide,
Menu, and Workflow editors?
A: The Design tab has no function in this release. This feature is reserved for future enhancements
.
Q: Why do I need to click the property value twice in the Properties tab to edit it?
A: This is how the Eclipse Properties tab works. It is a current limitation in the tool.
Q: When editing a cell in a mapping table in an Open Window, Push Fields, or Set
Fields action, why must I click elsewhere in the table before the data is accepted
and the cell is closed?
A: You can usually press Enter to close the cell and accept the data. This is how the Eclipse/SWT
JFace table works. It is a current limitation in the tool.
Q: How does multi-select in the form editor display and update field properties?
A: When you selected two or more fields in the form editor, the Properties tab displays the
properties that apply to all selected fields. If the fields have different values for a property, the value
for the primary selection, the first field selected, appears in the Properties tab. If you change a
Page 2319 of 4705
Home
value in the Properties tab, BMC Remedy Developer Studio applies the change to all the selected
fields. Because of an Eclipse limitation, BMC Remedy Developer Studio cannot clear or use a
colored background to distinguish fields with mixed values.
Q: Where can I use Undo and Redo?

A: The form editor provides Undo and Redo commands. The Undo and Redo commands are only
available in the Edit menu when the form editor has the input focus. If you make a change in the
Properties tab, you must click the form editor tab before you can undo it.
Q: How can I use special characters in the Filtering Options Name field and the
Locate field in Selector dialog boxes?
A: These two fields use regular expressions for matching. Certain characters, among them * and [,
have special meaning. To match a single * in a name, enter [*] in the field.
Q: Since it is actually Eclipse, can I use BMC Remedy Developer Studio to do Sun
Java or other development?
A: BMC Remedy Developer Studio is a packaged plug-in to the basic Eclipse IDE, but other
development plug-ins are not packaged in. BMC has not tested other Eclipse plug-ins installed
alongside BMC Remedy Developer Studio, so it is recommend that you not try this for the release.
Q: Where are the Eclipse menus?

A: The Eclipse menus that are not applicable to BMC Remedy Developer Studio are not included.
Differences between BMC Remedy Administrator and BMC

Remedy Developer Studio
The following sections summarize the differences between BMC Remedy Administrator and BMC
Remedy Developer Studio:
Server and object navigation differences
Login differences
Permissions differences
Forms differences
Workflow differences
Menu differences
Web services differences
Import and export differences

The following table explains the server and object navigation differences.
Function
Page 2320 of 4705
Home
Group or visually
compare
There is a single AR System Navigator view that shows all servers.

Each distinct object list can be opened once. You can open a separate
Create a new Server Window.
different lists of
objects
BMC Remedy Developer Studio using a different workspace and open

the same object list with different filtering or other settings.
Display a list of
Double-click the object type in the All Objects subtree in AR System
Click the object type in the server
all objects of a
type (for
Navigator.
object tree in Server Window.
example, list of
all filters)
Find an object in
a list
1. In the object list, open the Filtering Options or select an object in

the list and type the one or more characters to move the selection
to the first object that starts with those characters.
1. Select File > Find.

2. Press F3.
2. Select Search > Search to list all objects that contain the search
text.
Switch to
another window
Hold down CTRL and press TAB.

To switch to an editor, hold down CTRL and press F6 until the
one that you want is selected.
To a select a view, hold down CTRL and press F7 until the one
that you want is selected.
View objects
In AR System Navigator, create a custom View by Form working list.
Create a new Server Window and
associated with
a form (View by
This definition is persistent.
configure list of forms. This is not

persistent.
Double-click the application node under Applications in AR System

Navigator.
Open the Application Window.
Form
functionality)
View the objects
in an application
View the list of
applications and
edit their
properties
1. In the AR System Navigator, expand the Applications node under
1. Click the Applications node
serverName, right-click an application node, and select Edit

Application.
2. Double-click the Application node under All Objects in AR
System Navigator to open the Applications object list.
Double-click the application in the list to open the Application
editor.
to open the list.

2. Right-click the selected
View more
columns in an
object list
application and select

Properties.
Select View > Details.

1. Select Window > Preferences.
2. In the Preferences dialog box, open BMC Developer Studio and
click Object List View.
3. Select the object list type from the list and configure the columns
to display and their order.
Create an object
(not in an
application
context)
1. Right-click the type node in AR System Navigator All Objects

subtree.
1. From Server Window, select

File > New Server Object or
2. Select File > New > objectType.
the New Server Object

toolbar button. Then, select
the object type.
2.
Page 2321 of 4705
Home
2. Right-click an object type

node in a server tree, and
select the command from the
pop-up menu.
Create an object
(in an application
)
1. Select the application node in the Applications subtree in AR

System Navigator (not under All Objects).
1. From the Application

Window, select File > New
2. Right-click the application and select the object type from the
New Object submenu of the context menu.
View roles
Server Object.
2. Click the New Server
Object toolbar button, and
select the object type.
In the AR System Navigator All Objects subtree, double-click Roles.
In the Application Window, click
This is a distinct node from Groups. You can only view roles in an object
list; you cannot create or edit them.
Roles/Groups.
Login differences
The following table explains the login differences.
Login differences
Function
BMC Remedy
Administrator
Change user or
servers
Maintain different lists

of servers
1. Select File > Login to open the Login window.
Select Tools >
2. Click the Edit Server List button on the Login window to open the
Edit Server List dialog box.
Login.
Switch Eclipse workspaces when you log on.
Select Tools >

Servers.
Maintain multiple home

directories.
Permissions differences
The following table explains the permissions differences.
Function
Assign
Right-click the group in the Groups object list and select Assign
Double-click the group in the Groups
group
permissions
Permissions from the pop-up menu to open the Assign Group

Permissions dialog box.
list to open the Group Permissions

dialog box.
Forms differences
The following table explains the forms differences.
Forms differences
Function
Select a different view tab at the bottom of the form layout area.
Select Form > Select a View.
Page 2322 of 4705
Home
Switch form
views
Create a field
Right-click in the form layout area and select the field type from
Right-click in form layout
the Create a New Field sub-menu.

Use the form editor Palette.
area.
Select Form > Create a New
Select Form > Create a New Field.
Field.
Hold down CTRL and click a field in the form editor or in the
Hold down SHIFT and click a
Outline tab to add it to or remove it from the selection.
field to add to or remove from

the selection.
Select multiple
fields
Hold down SHIFT and drag a rectangle around the fields to add
to the selection.
Hold down CTRL and drag a rectangle around the fields to add
to or remove from the selection.
Drag a rectangle around the

fields to select.
Note
Select the Marquee tool in the Palette to drag a rectangle
instead of dragging a field
Move a field
using the arrow
keys
1. Select one or more fields.

2. Press the period key to enter the arrow key mode.
3. Press the arrow keys to move the field.
Select one or more fields and press

the arrow keys to move it
4. Press ENTER to complete the move or Escape to cancel the

move.
Press the period key repeatedly to enter other arrow key modes that
resize the fields.
Field properties
Select a field, and the properties appear in the Properties tab.
Double-click the field or select the

field and click the Field Properties
button.
View properties
Click the layout background, and the properties appear in the

Properties tab.
Resize a view
1. Select Layout > Show Actual View Size.
2. Select the view.
Select Form > Current View >

Properties.
Resize the form window and save
the form.
3. Drag the resize handles.
Find a field
Use the Find Field or the ID list at

Select the field in the Outline View Tree Overview.
the top of the layout area.
Select Edit > Find/Replace to open the Find Field dialog box (
which also supports find by label, partial search, and find next).
Tree / Table
Properties
Open the field properties as with

1. Select the table field.
any other field.
2. On the Tree/Table property in the Properties tab, click the

ellipsis (...) button to open the Tree/Table Properties dialog box
.
Page 2323 of 4705
Home
Default Value
and other
Each time you press ENTER, in the text entry dialog box, two
non-printing characters are added to the value. They appear as two
Each time you press ENTER, in the

text entry dialog box, one
multiple-line text
properties
rectangles in the field in BMC Remedy Administrator. BMC Remedy

AR System components treat new lines represented by either one or
non-printing character is added to

the value. That character appears
two non-printing characters correctly.
as a rectangle in the field.
Right-click the Navigation field and select Edit Navigation Items. To
Open the Navigation Items editor
display or edit the items in a different Navigation field, select that field
from the Navigation Items tab of

the Field Properties dialog box.
Navigation field
item editor
in the form. To close the Edit Navigation Items dialog box, click Close.
Edit Menu Bar
and Navigation
field item
properties
To display the item properties in the Properties tab, select the item in
the Edit Navigation Items dialog box or in the Outline view Tree
Results List field

on a Display-Only
Not available. Use a table field instead.
Permitted.
Display the same

field in all pages
in a page holder
Select the panel holder and click the ellipsis (...) button in the Shared
Fields property to open the Shared Fields dialog box. You can only
view shared fields created by BMC Remedy Administrator. You cannot
share fields by using BMC Remedy Developer Studio.
Select the field in the Shared Fields

tab of the page holder field
Attempt to delete
a core field
Not allowed. If only core fields are selected, the Delete command is
unavailable. If both a core field and a non-core field are selected, all
core fields are ignored and the other fields are deleted.
Not allowed. Displays a message.
Save a form that

contains a table
Reports errors.
Saves the invalid form, but it cannot

be used.
Overview.
The Navigation Items editor also

has tabs to edit the field properties
of the navigation items or menu bar
items.
form
properties dialog box.
field that
references a
server that does
not exist
The following table explains the workflow differences.
Function
Create workflow
action
Use the panel pop-up menu or the menu bar Workflow

menu.
1. Select the If Action or Else Action tab of

the workflow window.
2. Select the new action.
3. Add data.
4. Click Add Action.
View or change
Put the input focus in the workflow or guide editor and
Select the appropriate tab in the workflow or
Help Text, Change

History, and
use the Properties tab.
guide window.
Permissions
Add a workflow
reference or a label
to a guide
Select the Active Links or Filters tab in the

guide dialog box and use lists and command
buttons to move workflow object and add labels.
Page 2324 of 4705
Home
Use the Add Active Link or Add Filter context

menu commands to add a workflow item or label
in a particular location in the guide.
Use the Workflow menu commands or toolbar
buttons to add a workflow item or label before the
selected item.
Use the Workflow menu Move Up and Move
Down commands or the toolbar Move Up and
Move Down buttons to change the order or items
and labels.
Set the Mechanism

of the Notify action
Select the mechanism from the list. The values 1, 2, 3,

and 99 are not allowed in the Code field.
to a standard choice
Select the mechanism from the

Mechanism list.
Select Other from the list and type 1, 2, 3,
or 99 in the Code field.
Menu differences
The following table explains the menu differences.
Function
BMC Remedy
Administrator
Create a
Select the New menuType Menu option from the File > New menu or from the AR
System Navigator Applications subtree New object or the All Object subtree Menus node
context menu.
Create a new menu object
menu
, and select the type of

menu.
Web services differences

The following table explains the web services differences.
Function
Input and
Output
Mappings
The XML and form items are represented as a table with XML items
always in the first column. The XML column is editable in the web
services editor and not in the action.
The XML and form items are swapped

around when comparing web services editor
with the web services action.
Default
operations
No default operations. Add the operations that the application requires

by using the Add Operation menu options on the Web Service menu.
By default, when you create a web service, it

automatically has certain operations.
Ports
A web service can have more than one port.
A web service has exactly one port.

The following table explains the import and export differences.
Function
Import and export
commands
1. Use the Import or Export command on the File menu to

start a wizard.

Use one of the commands on
the Tools menu.
2.
Page 2325 of 4705
Home
2. On the first page of the wizard, open the BMC Developer

Studio branch of the tree.
3. Select what to export or import.
4. Follow the wizard to complete the operation.
Save a packing list in

XML format for use with
the export CLI
In the Packing Lists branch of the server branch in the AR System
In the Packing List window,
Navigator, right-click the name of the list and select Save as Import
select Packing List >
/Export commands.
Generate XML.
Note
You can also save a working list as import/export
commands.
Export server objects as

server-independent
definitions
All server objects are exported as server-independent, except DSO

Mappings.
Select Export as
Server-Independent on the
Export Definitions dialog box.
Setting up the development environment

The following sections explain details about setting up the development environment:
Packing lists
Saving packing lists as XML import or export command files
Working with applications and packing lists
Development modes
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.
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
Page 2326 of 4705
Home
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 mapping's name and then open a packing
list that contained that mapping, the DSO mapping is missing from the packing list.

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 select New Packing List.
A new packing list opens.
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.
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.
Adding items to a packing list
Page 2327 of 4705
Home
c. From the Add Items with Related Property list, select the appropriate option for your
packing list:
Object Only Add only the selected objects (and not their related objects).
Directly Related Objects Limits the scope of server objects when shared
workflow is added to the packing list. See the table in the following table.
All Related Objects Adds all selected objects and their related objects.
d. Click OK.
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
7. In the Save Packing List As dialog box, enter a name.
Packing list names must be unique on each BMC Remedy 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.
Related objects in a packing list

For
Packing list includes
Forms
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.
Join forms
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).
Page 2328 of 4705
Home
For
Packing list includes
Active links
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.
Filters
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.
Active link
All active links referenced in the guide as well as all associated objects for those active links.
guides
Filter guides
All filters referenced in the guide as well as all associated objects for those filters.
Applications
All associated forms and the list of related objects associated with those forms.
Web
Included as an independent object.
Services
Menus
No related items included.
Groups
Flashboards
Images
Saving packing lists as XML import or export command files

In addition to exporting a packing list like any BMC Remedy AR System server object, you can
save a packing list to an XML import or 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 or 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 select Save as Import or Export Commands.
2. In the Save as Import or Export Commands dialog box, select or enter a file to write the
import or export commands.
For information about the import or export CLIs, see Exporting and importing data and
definitions.
Working with applications and packing lists

An application is a server object that contains references to a collection of forms. Based on the
forms included in the application, other objects related to those forms are also included in the
application. Use applications to group sets of objects to accomplish particular tasks so that you and
your users can interact with the application as a functional unit. For more information, see Defining
and managing an application.
Page 2329 of 4705
Home
Like an application, a packing list is a server object that contains references to a collection of
objects. For more information, see Creating packing lists.
If you open an application or a packing list from the AR System Navigator, an object list displays
the contents of the application or packing list and allows you to access the objects. If you create or
edit an application or packing list, an editor opens, and you can add or remove objects and change
other properties.
To create an application
1. In the server branch, right-click the Applications and select New Application.
2. In the New Application dialog box, select Local Application or Deployable Application,
and click Finish.
3. Complete the fields in the panels.
The application editor opens in the editor area.
To create a packing list

1. In the server branch, right-click Packing Lists and select New Packing List.
2. Complete the fields.
The packing list editor opens in the editor area.
To open an application or a packing list

In the Applications or Packing Lists branch, double-click the name of the application or
packing list.
A list of all the objects opens in an object list. See Using object lists.
To modify an application or a packing list

In the Applications or Packing Lists branch, right-click the name of the application or packing
list and select Edit.
The application editor or the packing list editor opens in the editor area.
To create an object in an application

In the Applications branch of the AR System Navigator, right-click the application and select
a New objectType command from the New Object menu.
For details about creating objects, see Creating objects.
Page 2330 of 4705
Home
To delete an application or a packing list

1. In the Applications or Packing Lists branch of the AR System Navigator, right-click the name
of the application or packing list and select Delete.
A Confirm Deletion dialog box appears.
2. Click OK.
To save a packing list as import/export commands

1. In the Packing Lists branch in the AR System Navigator, right-click the name of the list and
select 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.
To understand the use of this file, see Exporting and importing data and definitions .
To export an application
1. In the Applications branch, right-click the name of the deployable application and select
Export Application.
2. In the Export Application dialog box, select a file to write the object definitions to.
For more information, see Importing and exporting object definitions and locking objects .
Note
You cannot export a local application by using Export Application. You can export
an application object without its contents using Export to File.
To export a packing list

1. In the Packing Lists branch, right-click the name of the packing list and select Export
Packing List.
2. In the Export Packing List dialog box, select a file to write the object definitions to.
For more information, see Importing and exporting object definitions and locking objects .

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.
Page 2331 of 4705
Home
Version control provides two independent functions:

Object reservation Users can reserve server objects. BMC Remedy AR System server
prevents other users from modifying reserved objects.
Object modification log When users change an object, BMC Remedy AR System server
automatically logs the change. It can also export the object's 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 BMC Remedy AR System server 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)
Object reservation
Object modification log
Object reservation and object modification for overlays and origin objects
Object reservation
BMC Remedy AR System server 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.
Page 2332 of 4705
Home
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.
Tip
Use individual BMC Remedy 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 BMC
Remedy AR System installed forms.
For information about enabling and using object reservation, see Using object reservation.
Object modification log

When the object modification log is enabled, the BMC Remedy AR System server automatically
logs every change to the object types listed in Version control in BMC Remedy AR System .
Optionally, it also exports an object's definition file when the object is created or modified.
You can use the object modification log to find an earlier 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 BMC
Remedy AR System installed forms.
For information about enabling and using the object modification log, see Using the object
modification log.
Page 2333 of 4705
Home
Object reservation and object modification for overlays and origin objects
BMC Remedy AR System server 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.
BMC Remedy AR System server 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 BMC Remedy AR System server populates these fields, while BMC Remedy AR System
clients use real names for object reservation and object modification.
For information about overlay objects, see Customizing applications using overlays and custom
objects.

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 Setting version control options.
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 select 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.
3.
Page 2334 of 4705
Home
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, select
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 Creating working lists.
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 select 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.
Page 2335 of 4705
1.
Home
Note
Administrators and subadministrators can release only objects that they have
reserved.
2. Select the objects.

3. Right-click the objects, and select Release.
The object reservations are removed. The Reserved By column in the object list is cleared.
Other users can change or reserve the objects.

The topics in this section provide information about using the object modification log. For additional
information about objects, see:
Labeling a collection of objects
Adding version control labels to objects
Finding objects with a specified version control label
Exporting .def files for labeled objects
Modifying version control labels
Removing version control labels
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 an earlier version of an object.
To enable the object modification log

the following options:
Set Object Modification Log to Enabled.
(Optional) Set Save Definition Files to Yes. See Setting version control options.
Important
To restore earlier versions of an object, you must configure the object
modification log to save object definition files. For information about
restoring earlier versions, see To restore an earlier version of an object .
2. Click OK.
Page 2336 of 4705
Home
When the object modification log is enabled, the BMC Remedy 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:
Fields in object modification log entries
Field
Description
Object
Name
Name of the new, changed, or deleted object.
Obj Old
Name
Previous name of the object if the change is renaming the object.
Object
Type of changed object: form, active link, escalation, filter, menu, image, or container (application, guide, or packing
Type
list).
Operation
Create, Delete, or Modify.
User
User who made the change.
Modified
Date
Time stamp of the change.
Comments
Text from the New Description property of the object.
Def
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:
1 Form, field, or view
3 Filter
4 Active link
6 Character menu
7 Escalation
10 Container
12 Image
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
An integer, starting at one, that specifies the version of the object.
API ID
An identifier that is the same for all log entries resulting from the same API call to the BMC Remedy AR System
server.
Page 2337 of 4705
Home
API Target
A flag indicating whether the object was referenced by the API call (Yes) or is related to a referenced object (No).
Label
Reserved for future development.
Note
This field is not associated with version control labels (see Labeling a collection of objects).
Task ID
A single change in BMC Remedy Developer Studio can produce many changes on the BMC
Remedy 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
To restore an earlier 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 .
1.
2.
3.
4.
In a browser, log on to the BMC Remedy AR System server as an administrator.

Open the AR System Version Control: Object Modification Log form in Search mode.
Specify the appropriate search criteria.
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
Page 2338 of 4705
Home
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
earlier 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.
To enable version control labeling

the following options:
Set Object Modification Log to Enabled.
Set Save Definition Files to Yes.
See Setting version control options.
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.
Page 2339 of 4705
Home
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 select 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 select 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.
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:
Page 2340 of 4705
Home
To use an existing label, select it from the Version Control Label list.
For more information about importing definition files, see Importing and exporting object definitions
and locking objects.
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
exclamation point
plus sign
asterisk
grave accent
semicolon
at sign
>
greater than sign
'
single quotation mark
{}
braces
hyphen
question mark
[]
brackets
<
less than sign
"
quotation mark
caret
number sign
slash mark
colon
()
parentheses
tilde
dollar sign
percent
underscore
equal sign
period
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, select 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:
(Click the image below to expand it.)
Page 2341 of 4705
Home
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 Setting version control options.
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 .
2. In the Label Search Results, right-click the appropriate label, and select 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 .
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 select 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 is exported to the specified location.
For information about downloading individual object .def files from the object modification log
, see To restore an earlier version of an object .
Modifying version control labels

To modify a version control label, follow this procedure.
Page 2342 of 4705
Home
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 .
2. In the Label Search Results tab, right-click the label to modify, and select 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

2. In the Label Search Results tab, right-click the label to modify, and select Delete.
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

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 select Remove Object.
The label is removed from the selected objects, and the objects are removed from the label's list of
objects in the Label Search Results tab.
Development modes
The following modes were introduced in BMC Remedy Developer Studio:
Best Practice Customization (Default)
BMC recommends that you use this mode for developing and managing your applications.
Base Development
This mode should be used only by BMC application developers. In your environment, if one
of the groups associated with your login user is an overlay group, BMC Remedy Developer
Studio opens only in the Best Practice Customization mode. Such a user is not allowed to
switch to the Base Development mode.
Page 2343 of 4705
Home
Note
You can use the Dev-Studio-Development-Mode configuration setting to enable these
modes in BMC Remedy Developer Studio. To enable the other mode (or both the modes
together), you must modify the Dev-Studio-Development-Mode configuration setting. For
configuring the value, see Configuration settings C-D

Best Practice Customization mode
Base Development mode
Changing the development mode
Operations on objects restricted by development mode
Related topics

The Best Practice Customization mode (the default mode) enables you to indirectly modify objects
created in Base Development mode. This includes all out-of-the-box BMC Remedy AR System
application and server objects. Modification is achieved by creating overlays for the object, and
modifying the overlay. This practice ensures that your modifications follow BMC development best
practices and that they are not lost when your application or server is upgraded. In this mode, you
can also create, modify, and delete custom objects. You cannot create, directly modify, or delete
origin objects (objects created in Base Development mode). To modify origin objects, you must
switch to the Base Development mode. Changes made to origin objects in this mode might be lost
during upgrades.
When in Best Practice Customization mode, only the following objects are displayed in the object
list:
Overlay objects
Custom objects
Unmodified objects
Best Practice Customization mode Object List view
Page 2344 of 4705
Home
Note
The Customization Type column is available only when you connect to a 7.6.04 or later
For information about overlays and custom objects, see Customizing applications using overlays
and custom objects.

The Base Development mode provides unrestricted access to create, modify, and delete origin
objects, such as out-of-the-box application objects. This mode is intended to be used only by
application developers. You cannot create, modify, or delete overlay or custom objects in this mode
.
In this mode, only origin objects, unmodified and overlaid, are displayed in object lists, as shown in
Base Development mode Object List view
Warning
Page 2345 of 4705
Home
BMC recommends that you do not create or modify objects in Base Development mode. If
you do, your changes can be lost when BMC Remedy AR System applications and
servers are upgraded. However, you must use Base Development mode to modify origin
objects.
Changing the development mode

The current mode of BMC Remedy Developer Studio is displayed in the status bar:
By default, BMC Remedy Developer Studio opens in Best Practice Customization mode. If you
change modes, the mode selected opens by default with the application is started.
When you are working in Base Development mode, the following banner appears below the toolbar
. This banner can only be hidden by changing the mode.
Base Development mode banner
To change the development mode

If your group permissions allow access to both modes, use the following steps to switch modes:
Page 2346 of 4705
Home
Note
Save any changes and close any open editors and object lists, before proceeding with
these steps.
1. From BMC Remedy Developer Studio, select File > Switch Mode, and select one of the
following modes:
Best Practice Customization
Base Development
a. When switching modes you must confirm by clicking OK, that you are aware all
opened object list views, and all editors, close when you switch modes.
b. Additionally, if you are switching to Base Development mode, you must activate the
check box and click OK, to confirm you are aware customizations made in this mode
might be lost if you upgrade.
2. In the Save resource dialog box, click Yes to save your current changes and switch the
mode.
If you click No, your unsaved changes are lost and the mode changes.
Operations on objects restricted by development mode

The following table provides an overview of operations that you can perform on origin, overlay, and
custom objects in each BMC Remedy Developer Studio mode.
Permitted operations by development mode and customization type
Page 2347 of 4705
Home
Operation
Can be performed on these customization types

Create
Overlay
Custom
Origin
Overlay
Custom
Origin (unmodified and overlaid)
Overlay
Custom
Custom
Modify
Delete
Rename
Note
Renaming an overlaid object automatically
renames its corresponding overlay object.
Save As
When performed on any type of object, creates a

custom object
When performed on any type of object, creates an

origin object
Export object
definitions
Origin (unmodified only)

Overlay
Custom
Note
Exporting an overlay object automatically
exports its corresponding overlaid object.
Import object
definitions
Origin (unmodified only)

Overlay
Custom

Overlay
Custom

In application development and production environments, you might want to provide different levels
of access to your administrators. The following BMC Remedy AR System server features enable
you to define access restrictions for administrators:
Overlay Group field
Configure this setting in the User Form. For details, see Creating groups.
Page 2348 of 4705
Home
Struct Admin group

In the User Form, assign the user to this group to grant Struct Admin access. For details,
see Special groups in BMC Remedy AR System .
Struct Subadmin group
In the User Form, assign the user to this group to grant Struct Admin access. For details,
see Special groups in BMC Remedy AR System .
Mode assignment based on access restrictions

To allow external customers the ability to configure extensions and customizations to their
applications, and to ensure that upgrades can implemented without affecting these changes,
Developer Studio now includes Best Practice Customization mode.
Members of the Administrator, Sub Administrator, Struct Admin, and Struct Subadmin groups by
default can create, modify, and delete all base, overlay, and custom objects to which their group
memberships give them access. By adding an overlay group to these user's group lists, you can
restrict them to only overlay and custom objects (or only to base objects). For more information
about Struct Admin and Struct Subadmin groups, see Access level options for administrators.
You can add a read-only functionality to the members of the Struct Admin group. By adding this
functionality you can allow the members to view and export objects, but restrict them to create,
modify, delete and import all base, overlay and custom objects.
Important
Any user assigned to the Administrator, Sub Administrator, Struct Admin, or Struct
Subadmin group must have a fixed license or the group assignment is ignored.
To restrict a user to creating, modifying, and deleting overlay and custom objects, but not base
objects, and without access to data or administrative functions:
1. Create a group with Overlay Group field value 0. Add the user to this group.
2. Add the user to the Struct Admin group.
3. Create a permission group named Struct Admin. Add the user to this group. You'll use this
group to grant access to system forms that are otherwise visible only to Administrators. For
more information about Struct Admin permissions, see Struct Admin group permissions.
4. Make sure the user has a Fixed license.
To restrict a user to creating and modifying only certain overlay and custom objects, without
access to data or administrative functions:
2. Add the user to the Struct Subadmin group.
3.
Page 2349 of 4705
Home
3. Create a group and add it to the Administrator lists of the objects you want the user to
access.
4. Add the user to this group.
5. Make sure the user has a Fixed license.
Struct Subadmin users are very similar to Sub Administrator users; they both get permission
to an object via the object's Administrator group list. Neither Struct Subadmin or Sub
Administrator users have special access to the forms mentioned in Struct Admin group
permissions.
To restrict a user to creating, modifying, deleting, and importing all base, overlay, and custom
objects, with access only to viewing and exporting definitions:
2. Add the user to the Struct Admin group.
Overlay Group field

The Group Information form contains an Overlay Group field, with the values defined in the
following table.
Overlay Group field values
Mode
Description
User is restricted to editing base mode objects.
User is restricted to editing overlay/custom objects (Best Practice Customization mode).
999999999
User is restricted to editing base, overlay, and custom objects.
(clear)
This group imposes no restrictions on access to base or overlay-mode objects.
Note: Do not assign an overlay to a computed group. If you assign an overlay to a computed group
, the ARERR 8821 warning occurs and the computed group is saved with Overlay Group as NULL
in the AR System server.
To create an administrator that has access to only one development mode at a time, create a user
with the following Group List settings:
One of the groups has Overlay Group set to 1.
For more information about Overlay Groups, see Selecting requests in list view and tree
view tables.
One of the groups is Administrator, Sub Administrator, Struct Admin, or Struct Subadmin.
For more information about Struct Admin and Struct SubAdmin groups, see Struct Admin
group permissions.
Page 2350 of 4705
Home
One of the groups is a Struct Admin Permissions group.

For more information about the Struct Admin permission group, see Access level options for
administrators and Struct Admin group permissions.
In this scenario, the user can only log on and work as an administrator or subadministrator in
one development mode, and cannot switch to another mode.
Defining and managing an application

The following sections describe the two types of applications you can create:
Local applications
Deployable applications
Alternatives for presenting applications to users
Deleting an application
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.
Deployable applications
A BMC Remedy 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 BMC Remedy AR System application type and is most appropriate
when the application is intended for use on the same BMC Remedy AR System server where it is
developed. For information about working with local applications, see Local applications.
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.
For more information about deployable applications, see the following sections:
Features of a deployable application
Shared workflow in a deployable application
Contents of a deployable application
Building a deployable application
Page 2351 of 4705
Home
Exporting and importing a deployable application
Features of a deployable application

A deployable application includes these features:
A 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.
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 and Making applications licensable for
integration system vendors.
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.
Shared workflow in a deployable application

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
Page 2352 of 4705
Home
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.
You can configure the BMC Remedy 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 .
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.
Contents of a deployable application

A deployable application contains all the information needed to deploy the application on another
BMC Remedy 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 a deployable application

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 BMC Remedy
AR System server 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 Creating 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, the following figure 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.
Page 2353 of 4705
Home
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 the following figure.
The Sample: Cities form which is owned by the Sample application
Other contents of a deployable application

In addition to the server objects it contains, a deployable application also includes the following
related information:
Roles All 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.
Data An 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 files An application can use external files, for example, files referenced by file
menus or other data files.
Image files You can specify image files that the BMC Remedy AR System server uses as
the application icon and About box.
Help files You can create an external help file and link it to the application.
Building a deployable application

Along with this section, the following sections provide more information about working with
deployable applications:
Creating a deployable application
Page 2354 of 4705
Home
Including objects in an application

Creating objects in an application
Adding existing objects to an application
Dividing an application
Working with deployable application states
Working with deployable application access points
Application attributes and properties
In BMC Remedy Developer Studio, each application appears as an entry in the AR System
Navigator Applications branch, as shown in the following figure. 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.
Applications branch with Home Page application opened
Because an application is itself a BMC Remedy AR System server object, an Applications node
appears in the All Objects branch of the AR System Navigator, as shown in the following figure.
You can also open an application for editing from this location.
Applications node in server object list with Home page application opened
Page 2355 of 4705
Home
The following steps describe one good approach to creating, defining, and deploying an application:
1. Determine the forms required for the application user interface.
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.
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.
4. Configure default permissions for the application.
5. Create the deployable application object and set its permissions.
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.
7. Define entry points to appear in application lists.
8.
Page 2356 of 4705
Home
8. Optionally, define access points to indicate to developers where external workflow should
access the application.
9. Define help text for the application or create external help files and add them to the
application.
10. Optionally, configure the application or some of its forms to record statistics.
11. Export the application, import it to a different BMC Remedy AR System server development
or test server, define the required groups, users, and role mappings, and test the application.
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.
To create a deployable application

1. In the AR System Navigator, expand the server branch where you want to create the
application.
2. Right-click Applications and select 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.
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 a BMC Remedy 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.
Page 2357 of 4705
Home
Creating objects in an application

To create an object in an application, right-click the application's node in the AR System Navigator
and select the object type from the New Object pop-up menu as shown in the following figure.
Adding a form to the New Hire application
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:
Form The application controls the form.
Workflow object The list of forms to associate with the workflow object is filtered to
include only forms in the application.
Web service The list of forms to serve as the base form for the web service is filtered to
include only forms in the application.
Flashboard variable The list of forms to serve as the data source for the flashboard
variable is filtered to include only forms in the application.
Packing list The packing list is added to the application.
Permissions If default permissions are defined for the application and object type, they
are applied when you create each new object.
Adding existing objects to an application

You can use these methods to add existing objects to an application:
Forms and packing lists 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 .
All other objects Associate 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.
Page 2358 of 4705
Home
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 Deleting objects.
Note
When you add an existing form to a deployable application, BMC Remedy AR System
server 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.
To add existing forms to an application

1. In BMC Remedy Developer Studio, right-click on the application's name in the AR System
Navigator, and select 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. Choose File > Save to save the changes to the application.
To add existing packing lists to an 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.
Page 2359 of 4705
Home
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. Choose 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.
4. Drag the forms to move to the new application from the application object list to the new
application's 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 application's state in the application tab in the editor area or through workflow,
as described in the following sections. You can also create custom states for use by all deployable
applications on the server.
Page 2360 of 4705
Home
To specify deployable application states

1. Define role-group mappings for each state in the Roles form:
a. In the mid tier, open the BMC Remedy AR System Administration Console.
b. Select the Roles form and search for all roles defined for the application.
If the search returns no roles, define roles for the application.
c. For each role, make sure that the role is mapped to an explicit group for each state.
d. Save the roles.
For more information about roles, see Creating and mapping roles.
2. Specify the state for the application, as follows:
a. Open the application for modification as described in Working with applications and
packing lists.
b. In the Application tab, expand the General panel.
c. Select a state from the State list.
d. Select File > Save.
The role-group mappings for the specified application state become effective after the
server re-caches.
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 application's 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.
BMC Remedy AR System server 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
re-caches.
5.
Page 2361 of 4705
Home
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 Importing and exporting
object definitions and locking objects.
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 a BMC Remedy 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

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.
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 the following figure.
Locating an external form marked as an access point
Page 2362 of 4705
Home
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

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.
Page 2363 of 4705
Home
General panel
The primary properties in the General panel determine the application label and development state.
The following sections describe these properties in detail.
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 Creating and managing fields.
The Label also has a specific meaning when an application is accessed directly in Windows clients.
For more information, see Alternatives for presenting applications to users.
State
This property defines the application state (Maintenance, Production, Test, or custom) and appears
for deployable applications only. Depending on the state you select, different access permissions
are applied to the application.
For more information, see Working with deployable application states.
Forms panel
The Forms panel determines the forms included in the application, as explained in Creating objects
in an application and Adding existing objects to an application .
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.
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
Managing resource files.
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.
Page 2364 of 4705
Home
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.
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 BMC Remedy AR System server, see Providing help text.
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 a deployable
application.
Use the Subadministrator Permissions property to define subadministrator permissions for access
control groups. For more information, see Rights for subadministrators.
BMC Remedy AR System server 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 Updating change history.
Exporting and importing a deployable application

To deploy or copy a deployable application to another BMC Remedy AR System server for testing,
additional development, or production, export it from the current server and import it to the
destination server using BMC Remedy Developer Studio.
Creating a deployable application definition file
Exporting and importing shared workflow and integrated applications
Defining and exporting integration workflow objects
Exporting and importing a deployable application with localized views
Exporting and importing data with a deployable application
Page 2365 of 4705
Home
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 BMC
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 .
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.
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 BMC Remedy AR System forms that are defined as data forms for the
application. See Exporting and importing data with a deployable application .
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 BMC Remedy 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.
Page 2366 of 4705
Home
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 .
To export an application with multiple localized views for import on deployment
servers with different locales, see Exporting and importing a deployable application
with localized views.
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 BMC Remedy AR System server 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.
You can use the following features to help manage cross-server development of integrated
deployable applications:
Include Shared Workflow option Use 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 .
Create-Workflow-Placeholders configuration option Set 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 .
Workflow Integration property for workflow objects Set 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
AppB
FormA
FormB
Page 2367 of 4705
Home
AppA
AppB
ActiveLinkA is associated with FormA its primary form
ActiveLinkA is also associated with FormB (a secondary form)
In this example, AppA owns FormA and ActiveLinkA. Both objects are 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.
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, BMC Remedy AR System server 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.
Page 2368 of 4705
Home
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 the following figure.
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 the following figure.
6. Click Finish.
Exporting integration workflow only

Page 2369 of 4705
Home
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 a deployable application with localized views

For a deployable application that includes 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 a 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.
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 the following figure.
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.
Page 2370 of 4705
5.
Home
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 on 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.
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 a deployable application

With a deployable application, 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
Page 2371 of 4705
Home
import time.
Use the Data tab in the Application window to select 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.
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.
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 Records Entries are imported using their existing IDs. If an ID is
already in use, an error is generated. (Default)
Generate New ID for Duplicate Records Entries 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 Record Entries 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 Record Entries 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.
Page 2372 of 4705
Home
9. Use the procedure described in To export a deployable application to export the application
to a definition file.
The form data is exported along with the object definition files.
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 Creating and managing
fields.
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 URLs for forms and
applications.
Specifying General and Forms attributes for an Application mode
Specifying Help properties for an Application mode
Specifying General and Forms attributes for an 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.
To specify General properties for an application

2. In the Application tab, expand the General panel.
3. In the Label field, specify the label that you want to appear in the Object List form in the mid
tier, 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 form in the mid tier.
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.
Page 2373 of 4705
Home
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.
To specify the behavior of forms in Application mode

2. In the Application tab, expand the Forms panel.
3. From the Primary Form list, select the form to appear in the mid tier when the application
first opens.
If you do not specify a primary form, no form appears when users open the application in mid
tier.
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.
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.
Specifying Help properties for an Application mode

You can create field-level help for users of your application, as explained in Providing help text. 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.
Page 2374 of 4705
Home
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.
To specify help text in a dialog box

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.
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.
To specify external help files

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.
Deleting an application
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.
Page 2375 of 4705
Home
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.
To delete the forms, data, menus, and workflow in an application

1. Open the application for modification as described in Working with applications and packing
lists.
2. Change the list layout to a single list as described in To change the layout of an object list .
3. Select all the objects in the list.
Note
To delete the roles used in an application, see Creating and mapping roles.
To delete an application
1. In the AR System Navigator, expand serverName > Applications.
2. Right-click the application node and select 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.

BMC Remedy AR System forms
BMC Remedy AR System installed forms
Using templates to dynamically present HTML content from a form
Working with panels
Working with tables
Working with menus
Working with images
Creating and managing fields
Recommendations while developing applications
Page 2376 of 4705
Home
BMC Remedy 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 BMC Remedy AR
System. While the entries comprise the rows of a database table, the fields comprise the columns.
This section discusses the following sections about types of forms available, and the tasks used to
create them:
Types of forms
Setting form properties
Creating and managing forms
Types of forms
An administrator can create forms that serve as part of a unique workflow solution. Form types
include the following:
Regular forms
Join forms
Display-only forms
View and Vendor forms
Inline forms
These forms can be customized using form views, as explained in Creating and managing form
views.
Regular forms
Regular forms are generally the main forms of your applications. Within the BMC Remedy AR
System server database, BMC Remedy 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 the following figure). All regular
forms contain these fields. For information about core fields, see Core fields.
Create Form window and core fields
Page 2377 of 4705
Home
Join forms
You can create a join form to combine information from multiple BMC Remedy 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).
For example, you can combine the information from the Help Request and the Employee ID forms (
as shown in the following figure) 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.
How joins work in BMC Remedy AR System
For information about creating and using join forms, see the following sections.
Understanding 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.
Page 2378 of 4705
Home
This section helps you understand more about join forms.

A join form in BMC Remedy 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 below). 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 user's 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.
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) and the execution order in workflow (see
Filters and join forms).
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 the following figure. In database terms, this is an equal join.
Join criteria in BMC Remedy AR System
Page 2379 of 4705
Home
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.
Including fields in the join form

You select the fields from the primary and secondary forms that will be part of the join form. If you
select 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
Creating and managing fields.
Inner and outer joins

You can create two types of join forms:
Page 2380 of 4705
Home
Inner join Selects 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 join Includes 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 BMC Remedy 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.
The following figure 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.
Example of an inner join
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 the following figure shows an example of an outer join.
Example of an outer join
Page 2381 of 4705
Home
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 following figure, you can join two regular forms, a regular form to a
join form, or two join forms.
Joining several forms
Add only as many join layers as you need, and make sure that your join criteria is efficient. The
Page 2382 of 4705
Home
practical upper limit for combining forms is about six layers. This is because each join form is
created by querying the database--which 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.
Self-join example 1
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.
Self-join example 2
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.
Page 2383 of 4705
Home
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).
Requirements for creating a join form using a vendor form

This section explains the requirements for creating a join form using a vendor form.
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 of creating a join form using a vendor form

This section explains the limitations of creating a join form using a vendor form.
The data from the join form is available only when the form is accessed through the BMC
Remedy AR System server's 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.
Creating join forms

The following procedure guides you through the process of creating a join form.
To create a join between forms

2. Right-click Forms, and select New Join Form.
The New Join Form wizard appears.
Choosing forms and join types
Page 2384 of 4705
Home
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
Inner Selects entries (or rows) only when corresponding values exist in both
forms.
Outer Includes 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
Horizontal Arranges 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.
Inheritance
Inherit Help Text for All Fields Takes the help text from the fields in both
forms and uses it in the join form.
Inherit Help Text for Selected Forms Takes 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.
Page 2385 of 4705
Home
Note
For optimal performance, use indexed fields in the join criteria. For information
about indexing fields, see Defining indexes.
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 . For
information about arranging fields on a form, see Arranging fields in a form view.
13. Save the form.
Creating entries in join forms

When creating entries through a join, BMC Remedy 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.
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.
Page 2386 of 4705
Home
You can "swap" which form is primary and which is secondary. You can also change the type of
join inner 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.
The Join Information panel in the Definitions tab of BMC Remedy Developer Studio allows you to
modify options specific to join forms.
Definitions tab Join Information panel
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 following figure illustrates the execution order of the join forms and their primary and secondary
forms.
Execution order of filters with join forms
Page 2387 of 4705
Home
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 Filter processing in BMC Remedy AR System server .
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
Joining several forms, if a filter returns an error on form I, none of the updates for the other forms is
written to the database.
The Request ID field

The BMC Remedy 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
Joining several forms), the join form's 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 BMC Remedy AR System. For information, see
Controlling access by using implicit groups Row-level security .
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:
Page 2388 of 4705
Home
Control panels (Using a display-only form as a control panel ) These provide an efficient
way to organize and present users with specific tasks or objectives.
Dialog boxes (Using a display-only form as a dialog box ) These 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 data You 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.
Creating 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.
Note
You can create display-only forms that work in New mode and Search mode in a browser
(Using a display-only form as a control panel ). For general information, see Creating and
managing forms.
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.
For more information about dialog boxes and using the display-only forms, see the following
sections:
Creating dialog boxes
Using a display-only form as a dialog box
Using a display-only form as a control panel
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
Page 2389 of 4705
Home
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 Active links.
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.
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 select 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 select Add Action > Open Window.
f. On the Open Window sub-panel, complete the following fields as follows:
In this field:
Enter:
Window Type
Dialog
Data Source
SERVER
Server Name
(The name of server that contains the display-only form)
Form Name
(The name of the display-only form)
View Name
(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 field's 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 form's 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.
4.
Page 2390 of 4705
Home
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 select Add Action > Commit Changes.
The Commit Changes subpanel appears under the If Actions panel.
e. Right-click the If Actions panel heading, and select 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 select 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 Access control.
For additional examples of using buttons that open dialog boxes, open the Sample:
ClassCentral form that is installed with BMC Remedy AR System, and click the Enroll tab.
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 select.
Provide a way for users to edit or view a rarely used set of fields, and thus avoid cluttering
the main form.
Page 2391 of 4705
Home
Provide a way for users to view or edit a set of fields that handle complex calculations of
multiple components.
To define a dialog box, use the following active link actions with the Window Type set to Dialog:
Workflow actions for defining a dialog box
Action
Description
Open
Window
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 occurs--usually 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 Close Window action.
Using a display-only form as a control panel

A display-only form can be used as a centralized entry point from which users select 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.
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.
Page 2392 of 4705
Home
View and Vendor forms

View and vendor forms allow users to access external data sources outside of BMC Remedy 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 BMC Remedy AR System to point to and access data in an existing database
table created outside BMC Remedy AR System. The table can be located on the same server or in
any other database server accessible from the current BMC Remedy AR System database server.
Vendor forms allow BMC Remedy AR System to access arbitrary external data sources through the
use of a BMC Remedy AR System Database Connectivity (ARDBC) plug-in. ARDBC plug-ins
enable BMC Remedy 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 Creating vendor forms and View forms.
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 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.
Page 2393 of 4705
Home
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.
Note
If you want to load an inline form on a view field that was loaded earlier in a different view,
you must clear the cache and log on to BMC Remedy Mid Tier again.
You can set the Inline Property to a BMC Remedy AR System form while defining a workflow using
Open Window action. For more information, see the following sections:
Creating Open Window actions for Search or Submit windows
Creating Open Window actions for Modify or Display windows
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.
Setting form properties in Base Development mode

The following panels are displayed when you are in Base Development mode.
Definitions tab in Base Development mode
Panel name
Description
More information
Basic
Defines settings for the next ID block size, cache, status history, and tags.
Defining next ID
block size, cache,
status history, and
tags
Entry Points
Defines the order in which entry points appear in the Application List field and the mode (
New or Search) in which the form will open.
Creating form
entry points
Page 2394 of 4705
Home
Panel name
Description
More information
Result List
Fields
Defines the form's fields that appear when a user performs a Search operation in a web
browser.
Defining search
results
Sort
Defines the order in which requests appear in the matching table list when the Search button
Setting up sort
is clicked on a form in a web browser.
order
Archive
Defines the settings for periodically backing up or deleting form data.
Archiving data
Audit
Defines form indexes to reduce the database search time for frequently searched fields.
Auditing changes
to data
Join
Information
Defines the primary and secondary forms of a join form, the join type, and a qualification.
Modifying join
form properties
Indexes
Defines form indexes to reduce the database search time for frequently searched fields.
Defining indexes
Full Text
Search
Defines the weighted relevancy fields for searches on multiple forms. Defines the scan times
for join, vendor, and view forms.
Configuring forms
for multiple-form
FTS
Vendor
For vendor forms only, defines the vendor and table names used to create the form. If you
Creating vendor
Information
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
forms
access data from the vendor form.

View
Information
For view forms only, displays the names of the table and one or more key fields used to
create the form. You cannot edit these fields.
View forms
Permissions
Group Permissions Defines the access control groups that can access the form.
Subadministrator Permissions Defines the access control groups that have
subadministrator permissions for the form.
Form,
active link
guide, and
application
permissions
Form,
active link
guide, and
application
permissions
Change
History
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.
Updating change
history
Help Text
Defines the help text for the form. This help text should describe the form, what it does, and
Providing help text
how to use it. Web browser users can view help by clicking the Help button, if a Help form
action field is added to the form.
Associations
to Follow for
Archive
Allows you to configure the associations that need to be followed during archiving of a form
and to archive related data. You can choose from the specific filtering options so that only
necessary associations are archived along with the form. The following options are available:
Defining
associations to
follow
Unspecified, Selected, All Enforced, All

Note: In the Best Practice Customization mode, you can overlay Associations to Follow for
Archive. However, you will only be able to select the filtering option that includes higher
associations than Base Development mode.
Page 2395 of 4705
Home
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 form's
view properties under Properties. For more information about setting view-specific properties, see
Setting form view properties.
Setting form properties in Best Practice Customization mode

In Best Practice Customization mode, the granular properties are available for customization.
These granular properties are listed under separate panels in the Definitions tab. The properties
for which the granularity is not available are listed under the Other Definitions panel. For
information about customizing the granular properties in the Best Practice Customization mode,
see Customizing a BMC Remedy application using overlays and custom objects .
Definitions tab in Best Practice Customization mode
To define form properties

1. Open the form.
2. Select the Definitions tab in the form editor.
3. Click the property panels to view and change the base properties. The form type you are
modifying determines which panels appear.
For more information about setting form properties, see the following sections:
Defining next ID block size, cache, status history, and tags
Allocating blocks of Next-IDs for faster create operations
Allowing users to delete entries
Defining search results
Setting up the sort order
Defining indexes
Page 2396 of 4705
Home
Defining next ID block size, cache, status history, and tags

You can perform the following tasks from the Basic panel on the Definitions tab of a form:
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 Setting administrative
options and Allocating blocks of Next-IDs for faster create operations.
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
Setting administrative options. For more details about this option and the memory use
impact, see Reducing memory using Display Property Caching .
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. The
mid tier shows 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, the mid tier shows the status history for the form starting
from when it was enabled.
Define tags to apply the same skin to multiple forms. You can use this property to set a
single skin across multiple forms. While defining skins, administrators can use this tag name
and ensure that the same skin gets applied across all forms that use that tag name. For
more information about defining skins, see Defining skins.
To define the next ID block size, cache, status history, and tags
3. Expand the Other Definitions panel and then the Basic panel.
4. Select Overwrite from the Overlay Type drop-down list.
5. To define the next ID block size:
a. Select Enable Next Request ID Block Size .
b. In the Next Request ID Block Size field, enter a value between 1 and 1000 inclusive.
Warning
Page 2397 of 4705
b.
Home
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 BMC Remedy AR
System server does not malfunction due to this gap, so it should not be
considered a defect.
6. 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.
7. To disable the server maintenance of status history, select Disable Status History.
8. To use tags to apply a single skin across multiple forms, enter the name of the tag.
Allocating blocks of Next-IDs for faster create operations

To increase performance during a create operation, you can configure the BMC Remedy AR
System server to allocate Next-IDs in blocks rather than one at a time.
Note
This setting is always disabled on the Distributed Pending form so that BMC Remedy
Distributed Server Option (DSO) can operate correctly.
To allocate Next-ID blocks

1. Locate the ar.cfg or ar.conf file.
By default, the ar.cfg (and ar.conf ) file is located in ARSystemInstallDir\CONF, as shown
in the following examples:
C:\Program Files\AR System\CONF in Windows systems
/usr/ar/conf in UNIX systems
2. Edit the Next-ID-Block-Size value to a positive number up to 1000, for example:
Next-ID-Block-Size: 100
The default value is 1. If 0 or a negative number (for example, -1) is used, the server will use the
default value. The option is started immediately. You do not need to restart the server for the
change to take effect.
Note
Page 2398 of 4705
Home
To disable this option, set the value of Next-ID-Block-Size to 1, or remove the parameter
from the configuration file.
Warning
The use of this configuration setting could result in unpredictably large Next-ID sequence
gaps. The likelihood of this occurring increases with the use of multiple servers that share
a database. The AR System server will not malfunction due to this gap and should not be
considered a defect.
Allowing users to delete entries

The Allow Delete option on the Basic tab of the Form Properties dialog box enables you to allow
licensed users who are not administrators to delete entries of a form if the following requirements
are met:
The user has access to the form.
The user has Change permission to the form's Request ID field.
If the Allow Delete option is not selected, only an administrator can delete the record.
To allow users to delete entries

3. Expand the Other Definitions panel and then the Basic panel.
4. Select the Allow Delete check box.
5. Save the form.
Defining search results

Use the Results List Fields panel on a form's Definitions tab to customize which fields appear in
the results pane when a user performs a search operation in a web browser. 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.
Note
You cannot include character fields that are greater than 255 characters in the Results
List Field.
Page 2399 of 4705
Home
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 width is used in a web browser.
The settings in the Results List Fields panel specify the default set of fields returned for API
programs that do not override the fields returned.
To define fields returned in a search

3. Expand the Other Definitions panel and then the Results List Fields panel.
Result List Fields
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, radio-button, 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. For
information about full text search, see Enabling full text search.
In the Width column for each field, enter a number (1-128) 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.
To remove fields or to change the order of the fields, select a field, and click the Remove,
Up, and Down buttons.
Save the form.
To set the color of requests that appear in the results list, see Setting form view properties.
Page 2400 of 4705
Home
Setting up the 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.
To set up the sort order for the results list pane

2. Click the Definitions tab, and expand the Other Definitions panel and then the Sort panel.
3. To add fields to the Sorted Fields list, click Add and complete the Field Selector dialog box
for each field you want to add.
4. To remove a field, select it, and click Remove.
To remove all of the fields, click Remove All.
5. To change the order of the fields in the Sorted Fields list, select a field, and use the Up and
Down buttons.
6. As needed, change the Sort Order value for the fields in Sorted Fields list.
Click in the table cell, and select Ascending or Descending from the list.
Note
Only those character fields that are less than or equal to 255 characters in length are
displayed in the sort list.
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 BMC Remedy AR System, so any indexing
they support must be managed outside of BMC Remedy 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 more information,
see the description of the "QBE Match" property under the Field Properties table.
If you are creating or modifying indexes in a form for which a large amount of data exists, this
Page 2401 of 4705
Home
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 also take longer on forms with many
indexes.
For more information about maximizing index performance, see Creating effective indexes.
To define indexes for a form

2. Click the Definitions tab, and expand the Indexes panel.
3. Add a new index to the list:
a. Select Additive as the Overlay Type, then click New.
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 characters, 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
BMC Remedy AR System does not verify if the size violates the databases
rules, but a database error is returned if the size is too large.
4. To remove an index from the database, select the index, and click Delete.
5. Save the form.
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.
1. Create a form (see Creating forms).
2.
3.
4.
5.
Set form properties (see Setting form properties).

Plan the layout of a form (see Arranging fields in a form view).
Create fields on a form (see Creating and managing fields).
Set field properties (see Field properties).
6.
Page 2402 of 4705
Home
6. Create form views (see Creating form views).

Creating forms
Opening forms
Copying forms
Renaming forms
Deleting forms
Previewing form updates
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 and Opening an object for editing.
Form names must be unique on each BMC Remedy 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.
Note
When you create forms, users who are logged in to BMC Remedy AR System using a
browser will not be able see the new form until you save the form and they log on to their
client again.
To create forms
2. Right-click Forms, and select 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 the Create Form window and core fields figure.
For join forms, the New Join Form Wizard opens. To continue, see Creating join
forms.
For display-only forms, a blank form opens. To continue, see Display-only forms.
For view and vendor forms, other dialog boxes open. For more information, see
Creating vendor forms and View forms.
4. In the Save Form As dialog box, enter the name of the new form.
Page 2403 of 4705
Home
4.
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.
Opening forms
The following procedure describes how to open all form types when you want to make changes.
To modify 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.
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.
6. To change the form properties, select the Definitions tab and expand the panels to make
the changes.
For more information, see Setting form properties.
7. Save the form.
Note
The form is available to users at their next login.
Copying forms
Important
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.
Page 2404 of 4705
Home
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
3. In the Forms list, double-click the form name.
5. In the Save Form As dialog box, enter the new name of the form.
6. Click OK.
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

3. In the Forms list, right-click the form name, and select 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
Page 2405 of 4705
Home
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 and about the
User form, see Adding and modifying user information.
To delete forms
3. In the Forms list, right-click the form name, and select Delete.
Previewing form updates

In Development mode, you can preview changes made to a form within Developer Studio, as
shown in the following figure.
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 the following figure and described in the following procedure.
Setting mid tier information for previewing forms in Developer Studio
Page 2406 of 4705
Home
To enable form previewing in Developer Studio

1. Open the Preferences dialog box, and select Mid Tier Information.
2. In the Mid tier URL informationsection, select one of the following options:
Default Mid Tier to use The mid tier to use for all servers to which you are
connected
Custom Mid Tier to use The path for specific servers on which forms are installed
. You can edit the name in the Mid Tier Path column.
3. For the selected server, specify a path, or edit an existing path as needed.
4. In the Profiles used for preview section, select the Use logged in users profile check box
to preview the form with the same credentials with which you logged on to Developer Studio.
5. To preview the form with different profiles, click Add to enter the user name and password
for the profiles.
6. Change the default for one profile to true.
At one time, only one profile can be actively used to preview a form. When you
preview a form, the profile which has the default value set to true will be used.
7. Click OK.
To preview a form in a browser

1. Open the Preferences dialog box, and select Web Browser.
2. Select the browser you want to use to preview a form.
3. Click OK.
4. Right-click a form from the form list.
5. From the context menu, select Open in Browser.
6. The selected form is displayed in the editor area.
BMC Remedy AR System installed forms

This section describes the system-defined forms that are loaded during BMC Remedy AR System
installation. 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 BMC Remedy AR System functionality are maintained by the BMC Remedy 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.
BMC Remedy AR System server installed forms A to C
Page 2407 of 4705
Home
Form name
System
Description
Application forms:
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 AR System server threads.
Used to monitor and analyze the performance of your deployable applications and forms
.
Application Pending
Application Statistics
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 BMC Remedy AR System debugging tools.
+
Application Statistics
Configuration
Verifies or changes application and form statistics logging settings. For more information
, see BMC Remedy AR System debugging tools.
+
AR System
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 application's state. Changing the state changes the access
Application State
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 for more information about application states.
+
SHARE:
Application_Interface
Required by the following applications (and their earlier 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_
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.
Properties
Enables you to view and modify the BMC Remedy AR System server information. For
more information, see Configuring AR System servers.
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 Localizing BMC Remedy
AR System applications for how to use this form.
AR System Object
Relationships
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 Setting
administrative options.
AR System Orchestrator
Configuration
Used by administrators to configure the integration between BMC Remedy AR System

and BMC Atrium Orchestrator. For more information, see Defining BMC Atrium
Orchestrator web services.
Page 2408 of 4705
Home
AR System Resource
Definitions
Used to define templates. For more information, see Resources for templates.
AR System Searches
Preference
Stores searches that users can create and save for a form. Each search is an entry in
this form. For more information, see Types of browser searches for end users.
AR System Server Group

Operation Ranking
Assignment Engine forms:
Stores the ranking of servers for operation ownership within a server group. This form is
loaded only when the BMC Remedy AR System server is configured to be a member of
a server group.
Used to run the Assignment Engine. For more information, see the Assigning requests
with the Assignment Engine.
ASE:Assignment
Association
ASE:
ProcessRuleForm
Assignment Engine
Administration
Assignment Forms
Assignment
Processes
Assignment Rules
Search Rules
BMC Atrium Web Services
++
Registry integration forms:
Used by the integration between BMC Remedy AR System and the BMC Atrium Web
Services Registry. For more information, see the Registering a web service.
AR System Web
Services Registry
AR System Web
Services Registry
Pending Delete
BMC Remedy Alert forms:

Alert Events
Contains alerts that are sent to users. If a notify action of a filter or escalation sends an
alert, the alert text and reference is stored in this form. For more information, see the
Alert Events form.
Alert List
Provides a web view with an alert list field already created. You can add this form to
your web-based applications for viewing lists of alerts in a browser.
Business Time forms:
++++
+++
Used to define periods of availability and unavailability, workdays, and holidays to

calculate business schedules. For more information, see Business Time introduction.
Business
Segment-Entity
Association
Business
Segment-Entity
Association_Join
Business Time
Holidays
Business Time
Segment
Business Time
Shared Entity
Business Time
Shared Entity-Entity
Association_Join_Join
Page 2409 of 4705
Home
Business Time
Workdays
Currency forms:
Holds the currency codes that are available on a server. Each code can be activated or
inactivated by checking the Active field on the form. Activating a currency code makes it
available to the clients.
Contains localized labels that override the currency codes in the menus associated with
currency fields in browsers.
Queried by clients to retrieve overridden currency labels. There is no interaction with this
join form.
Holds the ratios for converting one currency to another. This form can include ratios for
both conversion directions (for example, from USD to Euro and from Euro to USD)
AR System Currency
Codes
AR System Currency
Label Catalog
AR System Currency
Localized Labels
AR System Currency
Ratios
because these conversion rates are sometimes different. This form can store current
and historical conversion rates.
BMC Remedy AR System server installed forms D to L

Form name
System
Data visualization forms:
Description
Used to set up a data visualization module to display graphical data in a field
on a form. For more information, see Data visualization fields.
Data Visualization Definition

Data Visualization Module
Data Visualization System Files
DSO forms:
Defines and maintains parameter and data control values for a specific
distributed mapping.
Maintains a queue of pending distributed transfers, updates, returns, and

deletes.
Maintains a queue of failed pending distributed operations. Includes

information about the error that caused the failure.
Defines and maintains definitions of specific distributed pools.
Distributed Mapping
Distributed Pending
Distributed Pending Errors
Distributed Pool
Flashboards forms:
Used to create and add flashboards to a form and to handle them at run time.
For more information, see Adding graphics to an application with flashboards.
FB:Alarm Events
FB:Alarm Monitor
FB:CumulativeServerStatistics
FB:Datasource
FB:DataSourceVariables
FB:Flashboards
FB:History
FB:History Summary
Page 2410 of 4705
Home
FB:
NonCumulativeServer-Statistics
FB:Variable
FB:Variable Attributes
FB:User Privilege
Flashboard Server Statistics
Sample
Group
Used to create access control groups to which you grant or deny access to
BMC Remedy AR System objects. There must be exactly one Group form
defined on a server. See Creating groups for how to use this form.
Home Page
Used as a convenient starting point for administrators and site managers to

display entry points. This default form is automatically installed with BMC
Remedy AR System.
inetorgperson
Provided as an example form based on an industry standard directory service

user schema. Each field on the form references an attribute defined by the
inetorgperson object class.
LDAP forms:
Enables administrator to view and modify configuration parameters for the

ARDBC and BMC Remedy AR System External Authentication (AREA) LDAP
Configuration ARDBC
plug-ins that are stored in the ar.cfg (or ar.conf ) file. Requires the
Configuration ARDBC plug-in. For more information, see ARDBC plug-ins
introduction.
AREA LDAP Configuration
Enables administrators to view and modify the parameters for the AREA LDAP
plug-in. The parameters are used to query the LDAP-enabled directory service
for authentication purposes and user information.
ARDBC LDAP Configuration
Enables administrators to view and modify the parameters for the ARDBC
LDAP plug-in. The parameters are used to establish connections with
LDAP-enabled directory services.
Licensing forms:
AR System Administration: Add

and Remove Licenses
Used to add, activate, modify, deactivate, and remove licenses for the BMC
Remedy AR System server, server components, and applications based on
BMC Remedy AR System. For more information, see Adding or removing
licenses.
AR System Current License

Usage
Tracks all licenses currently in use on the server when the Enable License
Tracking option is selected in the AR System Administration: Server
Information form.
Tracks information about licenses that are released while the Enable License
AR System Historical License

Usage
Tracking option is selected in the AR System Administration: Server

Information form.
++
Internal supporting forms for licensing.
++++
++++
Receives log information when a log mode is configured to log to a form. For
more information, see Working with logs.
AR System Licenses
AR System Tags
Log forms:
AR System Log: Alert
AR System Log: ALL
AR System Log: API
AR System Log: Escalation
AR System Log: Filter
++
Page 2411 of 4705
Home
AR System Log: FullText Index

AR System Log: SQL
AR System Log: Server Group
AR System Log: Thread
AR System Log: User
BMC Remedy AR System server installed forms M to Z

Form name
System
Description
Metadata forms
View forms used by BMC Remedy AR System client programs to access server objects.
These forms are not designed for access using the browser.
Preference forms
Store user preferences centrally, providing "roaming profiles" for any BMC Remedy AR
System user. These forms are loaded when they are selected in the Select BMC Remedy
Action Request System Components dialog box during installation of the BMC Remedy AR
System server. Users can access these forms in a browser to view and set their preferences.
In BMC Remedy Developer Studio, select Window > Preferences to set preferences. For more
information, see Setting user preferences.
AR System
User
Preference
AR System
User Central
File
AR System
Administrator
Preference
Query builder widget
forms
Enables developers to configure the fields displayed in the Query builder widget list. Defines
unique query information to be displayed in a query widget
AR System
Query Widget
Enables developers to configure the fields displayed in the Query builder widget list. Backend
form that contains the list of fields to be allowed in creating the query
Enables developers to configure the fields displayed in the Query builder widget list. Join form
that can be used by the Query builder widget to get the list of field IDs and information to be
used in the Query builder widget
AR System
Query Fields
AR System
Query Info
Reporting forms:
Report
Links reports to forms on the same BMC Remedy AR System server that hosts the Report
Form, and provides the structures needed for granting permissions to run a report for specified
groups. Administrators and individual users can submit entries to this form. For more
information, see Managing reports with the Report form.
ReportCreator
Provides the interface to create and maintain BMC Remedy AR System native report definition
files. This form is a vendor form using an ARDBC plug-in. The data is actually stored in the
Report form as attachments. This is a legacy report form. For more information about this form
, see Reporting in BMC Remedy AR System. For more information about ARDBC, see
ARDBC plug-in API functions.
Records report file names.
ReportToFile
ReportType
Specifies how each type of report (for example, Crystal or user-defined) is created, edited, and
run. Generally, only administrators can submit or modify entries in this form, but users must be
able to view the entries. For more information, see Defining report types.
Page 2412 of 4705
Home
Used in workflow to prompt users to select a report to run. This form has no entries. This is a
legacy report form. For more information, see Reporting in BMC Remedy AR System.
ReportSelection
Roles
Defines roles for each deployable application, and maps the roles to explicit groups on the
server. You must map roles to groups for each application development state, such as Test or
Production. See Creating and mapping roles for how to use this form. There must be exactly
one Roles form defined in a server.
Server Events
Contains a record of internal events for a particular server. Event types that can be recorded
include server structure changes, user and group changes, and server setting changes. Set
options for recording server events using the AR System Administration: Server Information
form of the AR System Administration Console. For more information, see Capturing server
events for workflow or API calls.
Server Statistics
Enables the server to automatically store server statistics. These statistics can then be
graphically displayed by client programs such as Flashboards and used to analyze server
performance. For more information, see Server statistics for baseline data and
ARGetServerStatistics.
User
Used to define users, their characteristics, and their access rights within BMC Remedy AR
System. There must be exactly one User form defined on a server. For more information, see
Adding and modifying user information.
User Password
Change
Used by users to change their passwords. For more information, see Enabling users to change
their passwords at will.
Version control forms:
For information about the features that use these forms, see Version control in BMC Remedy
AR System.
+
Stores information about labels used to identify a collection of objects for versioning purposes.
See Labeling a collection of objects.
Stores information that links a version control label to various objects. See Labeling a
collection of objects.
Records changes to server objects.
Records object reservations.
AR System
Version Control
: Label
AR System
Version Control
: Labeled
Object
AR System
Version Control
: Object
Modification
Log
AR System
Version Control
: Object
Reservation
AR System
Version Control
: Task
Page 2413 of 4705
Home
View selection forms:
Stores actor definitions for actor-based view selection. Each actor is an entry in this form. See
Configuring actor-based view selection.
AR System
Actor View
Stores information that links actors to views for actor-based view selection. See Configuring
AR System
actor-based view selection.
User
Application
Actor
Visualizer forms:
Store Visualizer configuration.
Visualizer
Module Images
Visualizer
Module
Registration
Visualizer Type
Information
Visualizer Type
Object Props
Visualizer Type
Style Info
Using templates to dynamically present HTML content from a

form
This section contains information about the template parameters, the resources for templates, and
how to use templates with fields.
Introducing templates
Resources for templates
Using templates with fields
Introducing templates
Templates are a method of formatting text dynamically for presentation in BMC Remedy AR
System server. 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.
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.
Page 2414 of 4705
Home
Note
Ensure that your HTML template is standards mode compliant.
BMC Remedy AR System server template supports two ways of rendering HTML pages:
HTML document templates
Inline template
For more information about templates, see the following sections:
HTML document template
Inline template
Parameters in templates
HTML document template

A template built as an HTML document. It is rendered inside an IFRAME element. It contains own
scripts and styles and work in own namespace.
Inline template
A template built as a simple HTML snippet. It is rendered inside a DIV element.
HTML snippet template (inline template) supports styles and scripts. You can use the standard
script tags to embed the scripts. The runtime client engine parses and evaluates these embedded
scripts and makes them available when the snippet is rendered to the browser.
Notes
For HTML compliance across multiple browser, only JavaScript is supported.

You must provide a namespace to the template to avoid conflicts with the internal
core snippets.
To send events to the parent form for the inline template, use the ARMT_SendSignalToParent
function. Below is the code snippet to use the function:
ARMT_SendSignalToParent("Event_Type","Event_Data", "DOM_element_reference")
Document Object Model (DOM) parameter helps you to identify the immediate parent form.
Parameters in templates
There are two kinds of parameters in templates:
Page 2415 of 4705
Home
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
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>
Page 2416 of 4705
Home
</tr>
</table>
Resources for templates

Templates, and the resources they use, are stored as attachments to requests of the AR System
Resource Definitions form. Three types of resources are available:
Template A text file containing text with parameters.
Image An image file in any format, including GIF or PNG formats.
Custom A 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.
The following figure shows the form used to store templates and other resources.
AR System Resource Definition form
This form includes the following information:

Name The name used to references the resource.
Status Either Active or Inactive. Inactive resources cannot be processed by the client.
Type The type of resource: Template, Image, or Custom.
Description A brief description of the template.
Mime type The 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 CSS files (.cs), text/css.
For Type set to JavaScript (.js), text/javascript.
For Type set to Custom, any type entered, for example, audio/mpeg.
Page 2417 of 4705
Home
Subtype An optional character value that can identify a more specific type to distinguish
resources.
Locale The locale of the resource. If specified, BMC Remedy AR System server uses this
field to select the resource with a given name that matches the user's locale.
Application The name of the application that uses this resource, if any.
Resources An attachment field where the actual HTML text, image, or other resource file
is stored.
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.
Binding a template to a view field
Evaluating a template using the TEMPLATE function
Using auto-complete functionality with the TEMPLATE function
Binding a template to a view field

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 using 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:
Page 2418 of 4705
Home
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 (the mid tier) executes the active link where the template is specified,
the template is retrieved from the BMC Remedy 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 select the TEMPLATE function, select 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 the following figure.
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.
Using auto-complete for template information
Page 2419 of 4705
Home
Working with panels

This section describes following topics about how to create and modify panel fields:
Panels
Panel holders
Floating panels
Panel fields
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.
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).
For information about panel holders, see Panel holders. For information about modifying panels,
see Modifying panels and panel holders.
For additional information about panels, see the following sections:
Creating panels
Adding an image to a panel
Applying border colors and thickness to a panel
Applying rounded corners to a panel
Avoiding scroll bars in panels
Workflow considerations for panels
Page 2420 of 4705
Home
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.
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
field's 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.
5. Set other panel properties as needed:

Field properties See Field properties This section provides brief descriptions of
field properties for all BMC Remedy AR System forms. The properties are listed in
alphabetical order.
Background mode See Background Mode setting in panel holders.
Color options See Setting color options for panels and panel headers .
Images in panels See Adding an image to a panel .
Rounded corners See Applying rounded corners to a panel.
Anchoring fields to the right side of a panel See Anchoring fields to the right
side of a form or panel.
6. Save the form.
Page 2421 of 4705
Home
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.
Note
Opacity settings for the panel do not affect the opacity of the image. An image's opacity is
determined by the settings applied in the tool used to create the image.
Applying border colors and thickness to a panel

This section provides the steps for 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 border's 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.
Page 2422 of 4705
Home
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.
For information about setting color options for panels, see Setting color options for panels and
panel headers. For information about using drop shadows in panels, see Drop shadows in panels
and panel holders.
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 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.
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
Panel with two rounded corners (browser)
Page 2423 of 4705
Home
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 the following figure).
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.
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
Using Fit to Content to dynamically resize panels
Avoiding scroll bars in view fields
Page 2424 of 4705
Home
Including space for panel elements to avoid scroll bars

Using flow layout to avoid multiple scroll bars
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 holder's 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.
Note
Slack is available only on forms displayed in a browser.
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.
Slack distribution order
Page 2425 of 4705
Home
The panel with the highest priority gets the slack, up to the maximum size set in the panel's
properties (see the above figure). 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.
Properties that affect slack allocation

Slack allocation is affected by these properties:
Maximum Size Specifies the maximum allowable size for a panel
Minimum Size Specifies 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:
True The 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.
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 holder's size, the panel has positive
Page 2426 of 4705
Home
slack.
If the total size of all panels is greater than the panel holder's size, the panel has
negative slack, and a scroll bar is required on the panel holder to display all the
panels.
The following use cases illustrate how positive and negative slack allocation are applied to panels.
Use case 1 Positive slack of 150 pixels

Property
Panel 1
Panel 2
Panel 3
Initial size
100
100
100
Maximum size
500
275
200
Minimum size
25
25
25
In this use case:

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).
Use case 2 Positive slack of 250 pixels

Property
Panel 1
Panel 2
Panel 3
Initial size
100
100
100
Maximum size
200
150
200
Minimum size
25
25
25
In this use case:

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.
Use case 3 Negative slack of -50 pixels

Property
Panel 1
Panel 2
Panel 3
Initial size
100
100
100
Page 2427 of 4705
Home
Property
Panel 1
Panel 2
Panel 3
Maximum size
200
200
200
Minimum size
25
25
25
In this use case:

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).
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 panel's 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 panel's 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. The following figures show a panel
whose scroll bars were eliminated by allocating a high slack distribution order to the
panel.
Table in a panel with scroll bars
Assigning a higher slack order to the panel to remove scroll bars
Page 2428 of 4705
Home
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 BMC Remedy AR System forms.
The following figures show a panel in a view field. The following figure shows the appearance of a
scroll bar when rows are added.
Panel with scroll bar
Page 2429 of 4705
Home
The following figure shows the panel after it was resized, which removed the scroll bar.
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.
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 field's 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 BMC
Remedy AR System server content in the same domain. The panel is not resized if the view
field contains content from a source outside BMC Remedy AR System server, such as a link
to an external web page, an image from an external source, or HTML code text.
For content other than BMC Remedy 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.
Page 2430 of 4705
Home
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.
Space requirements for panel and panel holder elements
Field
type
Element
Size
Panel
Border
thickness
0-9 pixels (adjustable). See To change a panel border's thickness.
Header
height
20 pixels (fixed).
Panel
Border
1 pixel (fixed). See the Borderless property description in Field properties.
holder
thickness
Margins
0-9 pixels (adjustable). See the Margin Bottom, Margin Left, Margin Right, and Margin Top property
descriptions in 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.
Using flow layout to avoid multiple scroll bars

When set to Flow, the Layout Style option in panels enables table fields to grow or shrink based on
their content. If a container includes multiple tables and a table field grows, the table fields
dynamically resize. This prevents empty space from resulting in a new single scrollbar within the
container. For more information about this option, see Flow layout.
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.
Remember these considerations when building workflow for panels:
When active links are executed, a specific panel gains focus when any of these conditions
occur:
Page 2431 of 4705
Home
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 Fields Use 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 Field Use 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.
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 Defining workflow to automate processes.
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
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 in the panel for which they
lack permission. See Panel field permissions properties.
Page 2432 of 4705
Home
BMC Remedy AR System server 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. The splitter can be configured to be visible, invisible (not visible but can be
dragged to resize the panels), or disabled (not visible and cannot be dragged).
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 panel's 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.
By default for supported browsers, system popups and floating panels and panel holders have a
drop shadow, whether the panel has rounded corners or not. A popup window opened by using an
active link Open Window will have a drop shadow. For more information, see Drop shadows in
panels and panel holders.
For additional information about panel holders, see the following sections:
Creating panel holders
Panel holder display types
Panel layout styles
Drop shadows in panels and panel holders
Shared fields in panel holders
Adding a panel to a panel holder
Background Mode setting in panel holders
Setting color options for panels and panel headers
Modifying panels and panel holders
Creating panel holders

This section explains the steps for creating a panel holder and setting properties for a panel holder.
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.
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 .
Page 2433 of 4705
Home
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 holder's 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.
3. Set other panel holder properties as needed.
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.
Tabbed panel holder
If a tabbed panel holder has more tabs than fit in one row, BMC Remedy Developer Studio display
the tabs in two or more rows.
Page 2434 of 4705
Home
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.
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 ) and by using the Fit to
Content property (see Using Fit to Content to dynamically resize panels ).
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.
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.)
By default, the splitter state of the splitter panel holder is Visible, which enables you to see the
Page 2435 of 4705
Home
splitter and drag it to resize the panels.

Splitter panel holder with splitter state set to Visible
To create a splitter that can be dragged to resize the panels but is not visible, set the splitter state
to Invisible. To create a splitter that cannot be dragged and is not visible, set the state to Disabled.
Splitter panel holder with splitter state set to Invisible
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.
Page 2436 of 4705
Home
Accordion panel holder

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 XY layout, fill layout, or 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.
Fill layout
Note
The Fill layout option is not supported for cell-based table fields.
Fill layout is applicable only to forms viewed in a browser and not displayed at design time in BMC
Remedy Developer Studio. At runtime, this style enables
The screen's layout to be automatically readjusted when the browser window changes its
size
The contents of panels in a splitter panel holder to readjust their layout when a user moves
the splitter
Page 2437 of 4705
Home
When fill layout is used, the container ignores the field's XY width and height properties at runtime.
Instead, each field takes up the container's entire width. The container's height is equally divided by
the number of visible contained fields (for example, if you have three fields, each one gets 33% of
the container's 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 field (list view table, tree view table, form view, or data visualization)
that 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.
Flow layout
When flow layout is used instead of the default XY layout, it enables you to stack fields vertically in
a panel. In this layout, developers have the option of configuring the margin for the panel and the
vertical spacing between fields within the same container. Fields cannot exist side-by-side; they can
only be above or below other fields in one column. This is helpful when you include fields that can
be dynamically resized in a panel, such as rich-text-formatting (RTF) fields or table fields. As the
user enters text, the field expands or contracts and all of the fields move up or down vertically. See
Adding rich-text-formatting capabilities to a character field .
When tables and view fields are contained in a parent panel which uses flow layout, the table and
view fields grow vertically and fill horizontally based on their content. Panel and panel holder fields
only fill horizontally. Data fields, such as integer and character fields, do not resize.
Flow layout at view level enables table fields to grow or shrink vertically based on the number of
rows in the table. The width of the table is limited by the view width. As the table fields dynamically
resize, the fields below them either move down or shift up to avoid empty space. As the table grows
and pushes the underlying fields down, a scrollbar appears at the container level. This helps
prevent multiple scrollbars within a panel.
Page 2438 of 4705
Home
Table fields in flow layout growing or shrinking in a container

Table fields in flow layout shrinking in a container

If a panel in a collapsible panel holder is set to flow layout, and Fit to Content is True, then the
panel will grow or shrink based on its content (that is, there will never be white space inside the
panel). For more information, see Using Fit to Content to dynamically resize panels .
Note
Some field types do not display in a flow layout, such as a toolbar, splitter, results list, or
query bar.
You can select flow layout for a panel either by setting the Layout Style property to Flow or by
right-clicking the panel and choosing Apply Flow Layout from the menu. The Apply Flow Layout
menu selection is available only for standalone panels or panels in a panel holder.
You can also select flow layout for a form view by setting the Layout Style property to Flow.
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
Panel holder display types.
Drop shadows in panels and panel holders
Page 2439 of 4705
Home
Note
Drop shadows in panels and panel holders are supported by Internet Explorer 9, Firefox,
and Safari.
Drop shadows are set by default for system popups. Drop shadows are also set by default for a
floating panels and panel holders. If you want to remove the drop shadow, set the Drop Shadow
property for a floating panel and panel holder to False. A drop shadow occurs whether the panel
has rounded corners or not. A popup window opened by using an active link Open Window will also
have a drop shadow.
System popup with drop shadow in Firefox
For non-floating panels or panel holders (that is, the Float Style property is set to None), you can
enable drop shadow by setting the Drop Shadow property to True. The default value for the Drop
Shadow property for non-floating panels and panel holders is False.
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 select 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.
Page 2440 of 4705
3.
Home
Note
If you remove a shared field from a panel, you cannot make it shared again using
Adding a panel to a panel holder

This section explains the steps for 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.
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 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.
Background Mode setting 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:
Opaque Fields on the form behind the panel in the stacking order are not visible.
Transparent In 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" effect; the fields behind the panel are visible, but
they cannot be accessed.
Panel holder Background Mode set to Transparent
Page 2441 of 4705
Home
A panel holder's 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
White space created by panel margins
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
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.
Page 2442 of 4705
Home
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.
Gradient options
By default, the target color is white.

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 Horizontal The gradient effect starts with the primary color at the top and
goes to the target color at the bottom of the panel.
Linear Vertical The 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 Horizontal The 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 Vertical The 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.
Page 2443 of 4705
Home
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:
0 Color is fully transparent.
1.0 Color is fully opaque.
0.5 Color is semitransparent.
Modifying panels and panel holders

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.
Panels dialog box
3. Select a panel, and click Up or Down to change its order.

4. Click OK.
To move a panel to another panel or panel holder

1. Right-click the panel to be moved.
2. In the context menu, select Move Panel To.
Move Panel to Other Panel Holder dialog box
Page 2444 of 4705
Home
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.
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.
By default for supported browsers, system popups and floating panels and panel holders have a
drop shadow, whether the panel has rounded corners or not. For more information, see Drop
shadows in panels and panel holders .
You can create the following types of floating panels:
Page 2445 of 4705
Home
Modeless floating panel Can 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 panel Can 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 panel Can 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.
The following figures show examples of floating panels.
Example of a modeless floating panel
Example of a dialog floating panel

Page 2446 of 4705
Home
Example of a tooltip floating panel

For more information about floating panels, see the following sections:
Characteristics of floating panels
Creating floating panels
Moving a dialog floating panel

The following table lists the characteristics for each type of floating panel.
Behavioral
Modeless floating
aspect
panel
Dialog floating panel
Tooltip floating panel
How the
panel is
invoked
Through a Change
Field active link
action. The panel
can be made
initially visible.
Through a Change Field active link action.

The panel must be initially hidden (enforced
at design time).

The panel must be initially hidden (enforced
at design time).
How the
panel is
Through a Change
Field active link
Through a Change Field active link action or

a mouse event outside panel area. Keyboard
dismissed
action.
Positioning
Based on the
Centered relative to the view. If one dialog
Located relative to the event that triggered
of the panel
floating panel's XY
location at
floating panel triggers another dialog floating

panel, the subsequent panel will not be
the workflow. (For example, if a user clicked a

link on the form, and that click triggered
design-time.
exactly centered.
workflow, the panel would appear just below

the field.)
users can press Esc to dismiss the panel.
Users cannot resize the panel.
Page 2447 of 4705
Home
Allowing
users to
Users cannot
resize the panel.
resize the
panel
To allow users to resize 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.)
Moving the
panel
Users cannot
move the panel.
Users can move the panel.
Users cannot move the panel.
Appearance
of
Normal
Dimmed out
Normal
How events
are handled
Keyboard and
mouse events are
passed to
underlying objects.
Keyboard and mouse events are blocked

outside of the visible area of the panel.
A click mouse event outside of the panel area

dismisses the panel.
How
Workflow that is
Workflow does not pause, and users cannot
Workflow that is invoked does not pause
workflow
behaves
invoked does not

pause when the
panel is displayed.
start new workflow from the base layer.
when the panel is displayed.
underlying
objects
Note
If the base form has workflow that
runs on an interval, that workflow
still runs.
Creating floating panels

This section describes the procedures to create the three types of floating 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)
Page 2448 of 4705
Home
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 panel's 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 select Move Field To.
Then, select the panel's 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.
To create a dialog floating panel

1. Create a panel or panel holder that will act as a dialog box.
2. Set the panel's Float Style property to Dialog.
The panel is displayed in zoom mode (as shown in the following figure), 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.
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.
Page 2449 of 4705
Home
4. Create the content in the panel.

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.
To create a tooltip floating panel

1. Create a panel that will act as a tooltip.
2. Set the panel's Float Style property to Tooltip.
The panel is displayed in zoom mode (as shown in the following figure), 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.
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.)
Moving 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.
Page 2450 of 4705
Home
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.
Panel holder with panels
Working with tables

The following sections provide information about the types of tables and how to create and modify
tables:
Table fields
List view tables
Tree view tables
Cell-based tables
Alert lists
Results lists
Creating table fields
Workflow considerations for table fields
Displaying images in tables
Adding buttons and URLs to tables
Adding a Select All or Cancel All check-box column to tables
Creating dynamic tables
Updating tables on-screen only
Enabling users to customize columns
Refreshing table fields
Table fields
BMC Remedy AR System server supports the following types of table fields:
List view (see List view tables)
Tree view (see Tree view tables)
Cell-based (see Cell-based tables)
Alert list (see Alert lists)
Results list (see Results lists)
Page 2451 of 4705
Home
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 about 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 table's 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.
Data in server-side table fields is read-only.
The most important reason for using server-side table fields is networkperformance. 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 this
situation:
To communicate from a form in a browser through the mid tier to the server and back
through the mid tier to the browser.
Chunk control in table fields

Cell-based tables and list view tables support chunking to return all records while limiting the
number of records displayed at one time. The chunk control contains a drop-down menu,
navigation buttons, and a results string.
Note
Application developers can remove chunk control from the table header by setting the
Next Label and Previous Label properties to an empty string or by setting the chunk size
to 0.
Following are the appearance and behavior of the chunk control:
Page 2452 of 4705
Home
The chunk control appears on the left of the table header.

The chunk control drop-down menu displays the record number (starting and ending record
number of the chunk being displayed), and not the page numbers. For example, when you
set the chunk size to 10, and navigate to the second chunk, the chunk control displays 11-20
.
The Number of Entries Returned property in BMC Remedy Developer Studio is set to {2}
of {3}results, by default.
When chunking is not enabled, BMC Remedy Mid Tier interprets the parameters and
displays both the total number of rows returned and also the maximum number of
rows that can be returned.
When chunking is enabled, BMC Remedy Mid Tier interprets only the {3} parameter
and displays only the maximum number of rows that can be returned.
You can add an additional parameter {4} to the Number of Entries Returned
property. For example: Number of Entries Returned = {2} of {3}results {4} . BMC
Remedy Mid Tier interprets the {4} parameter and based on the number of records
returned, the value set for the Row label or Row label Plural property appears on
the table header.
If the table contains only one record, the value set in the Row label property
appears on the table header.
If the table contains more than one record, the value set in the Row label
Plural property appears on the table header.
Note
If the number of records in the table is less than the chunk size, the
chunking control will not be visible.
The number of entries displayed on chunk control is right aligned.

The results string that displays the total number of records in all chunks appears on the right
of the chunk control.
The Page label is removed from the table header.
The navigation control to move to the previous chunk and the next chunk always appears
with the chunk control.
When you have selected the first chunk, the pagination control to navigate to the
previous chunk is displayed in the disabled state.
When you have selected the last chunk, the pagination control to navigate to the next
chunk is displayed in the disabled state.
Page 2453 of 4705
Home
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.
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 Change Field
action.
BMC Remedy AR System provides flexibility to the applications to manage the alignment of the
column headers and data in the BMC Remedy AR System table fields, irrespective of the data type.
You can set both column headers and data with the following alignment options:
Right (default for numeric field types)
Center (default for control field types)
Left (default for all other data types)
Note
The table alignment flexibility is applicable to list view tables only.
The following properties have been added in BMC Remedy Developer Studio to update the
alignment of column headers and data:
Header Alignment
Data Alignment
For more information about list view tables, see:
Structure of list view table fields
Editing row data in list view tables
Using drop-down menus in list view tables
Page 2454 of 4705
Home
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.
Editing row data in list view tables

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.
To make a column editable, change the column's 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.
Using drop-down menus in list view tables

When the Display Type property of a column in a list view table is set to Drop-Down 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 the following figures.
Drop-down menu in column based on character field
Page 2455 of 4705
Home
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 table's
right edge or use the Max Rows or Size of Chunk table properties to prevent the number
of rows from exceeding the table's length.
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 field's Display Type property does not have to be Drop-Down List.
To attach a menu to a character field, see Working with menus.
Selection field (drop-down, radio button, and check box)
To add columns to tables, see Adding a table field to a form .
2. Select the new column.
3. In the Properties tab, set the column's Display Type property to Drop-Down Menu.
Tree view tables

Use a tree view table field to display data from forms in a hierarchical manner.
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
Page 2456 of 4705
Home
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).
For more information about tree view tables, see:
Structure of tree view table fields
Editing data in tree view tables
Arranging nodes in tree view tables
Avoiding data inconsistencies in tree view tables
Selecting requests in list view and tree view tables
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 the following figure has these levels:
Example tree view table levels
Level
Source field
Nodes
Requests per node
Type
Problem, Defect
Multiple
Severity
Critical, Severe, Moderate
Multiple
Priority
Urgent, High, Medium, Low
Multiple
Description
Customer Downtime, Incorrect Setup, and so on
One
Example of tree levels, nodes, and leafs

Page 2457 of 4705
Home
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 ). 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.
Editing data in tree view tables

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.
Arranging nodes in tree view tables

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:
Page 2458 of 4705
Home
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:
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:
Page 2459 of 4705
Home
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
BMC recommends hiding 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 view and tree view tables .
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:
Page 2460 of 4705
Home
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 in tree view tables

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
Type
Problem
Defect
Suppose that a request is submitted with Type Sort = 1 and Type = Defect:
This error creates two branches in the tree for the Defect type:
Page 2461 of 4705
Home
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. In BMC Remedy AR
System server 7.5.00 and later, tree levels marked as hidden will be hidden in all clients.
Important
Check applications based on earlier versions of BMC Remedy AR System server to verify
that all levels in tree view tables that should be visible are visible.
Selecting requests in list view and tree view tables

The following figure 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.
List view versus tree view
Page 2462 of 4705
Home
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).
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
Change Field action.
For information about refreshing tree view table data in Modify mode, see Refresh on Entry Change
.
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 field's Display NULL Value As property.
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
the following figure, a list view table field displays text in a traditional grid format with column
headings.
Traditional list view table field
Page 2463 of 4705
Home
In a cell-based table field, all the information from a list view table row is displayed in one cell, as
Cell-based table field
Note
In a browser and BMC Remedy Developer Studio, cell-based tables have the format
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.
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.
Page 2464 of 4705
Home
Cell-based tables support chunking. Cell-based tables also support tabbing as follows:
Tabbing in tables
Use this key
In a browser
To move focus from . . .
Tab
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
Up and down arrow

Cell to cell
For more information about cell-based tables, see:

Templates for cell-based tables
Editing data in cell fields
Setting content clipping for cell-based tables
Table resizing due to browser resizing or panel collapse
Screen updates due to adding or deleting rows
Creating custom chunking buttons
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 to a
view field 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.
To make a cell field editable, change the column's 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).
Page 2465 of 4705
Home
Setting content clipping for cell-based tables

If the Content Clipping property of a cell-based table is set to True, cell-based tables display as
many cells as can fit in the table without displaying a scroll bar. Content clipping can only be set
when table chunking is enabled. For more information about setting this property, see Content
Clipped.
Content clipping can be used for a cell-based table when:
The cell-based table is in a panel with an XY or Fill layout style
The cell-based table is in a View field
The cell-based table is visible
Content clipping is disabled for a cell-based table when:
The cell-based table is within a panel that has Fit To Content or Flow Layout set to True.
Content clipping will be disabled. This allows the contents of the table to control the size of
its container.
The cell-based table is hidden or inside a collapsed panel.
Note
Even when content clipping is enabled for a cell-based table, a vertical and/or horizontal
scrollbar display if the browser window is too small to display a single cell in the table area
.
Content clipping does not change the meaning of chunk size. However, some of the information
strings displayed in the table header in a browser are different when content clipping is enabled.
See Number of Entries Returned.
To set content clipping for a cell-based table

1. In the BMC Remedy Developer Studio, open a panel with XY or Fill layout style or open a
View field that contains the cell-based table.
2. Select the cell-based table.
3. In the Properties tab, set the Content Clipping property to True.
4. Right-click the form, and select Save.
Table resizing due to browser resizing or panel collapse

Table resizing results under the following conditions:
User resizes the browser window
User collapses a panel
Page 2466 of 4705
Home
For example (the following figure), if a user resizes the browser window to a bigger size or
collapses another panel when the number of records displayed is less than the Size of Chunk
property for a table, more records are displayed because the table is bigger. The maximum amount
of records displayed is limited by the Size of Chunk property.
Note
In the following figures, the records in gray are those that are requested by chunking but
are not visible in the browser.
Example: Table resizing due to browser window resize to a bigger size or collapsing a panel
(chunk size of 10)
If a user requests the next chunk of data (the following figure), the next chunk of records displays
and is limited by the chunk size of the table.
Example: Next chunk displays due to user request (chunk size of 10)
If a user resizes the browser window bigger (the following figure), then requests the next chunk of
data, the next chunk of records displays starting with the next record that was not visible.
Example: Next chunk displays due to browser window resize to a bigger size then
Page 2467 of 4705
Home
requesting the next chunk (chunk size of 10)

If a user resizes the browser window smaller (the following figure), then requests the next chunk of
data, the next chunk of records displays starting with the next record that was not visible.
Example: Next chunk displays due to browser window resize to a smaller size then
requesting the next chunk (chunk size of 10)
If a user requests the next chunk of data (the following figure), then resizes the browser window to
a smaller size, then requests the previous chunk, the previous chunk of records displays ending
with the next record that was not visible.
Example: Previous chunk displays due to browser window resize to a smaller size then
requesting previous chunk (chunk size of 10)
If a user resizes the browser window to a bigger size (the following figure), then requests the
previous chunk, the previous chunk of records displays and can include some records that were
previously displayed.
Example: Previous chunk displays due to browser window resize to a bigger size then
requesting previous chunk (chunk size of 10)
Page 2468 of 4705
Home
Screen updates due to adding or deleting rows

The following examples show how chunks are displayed when records are added or deleted.
Note
Although you can add or delete rows for cell-based tables, the recommendation is not to
add or delete rows with content clipped cell-based tables.
If a user adds a row (the following figure), then requests the next chunk, the next chunk of records
displays starting with the next record that was not visible.
Example: Next chunk displays after adding row then requesting next chunk (chunk size of 8)
If a user deletes a row (the following figure), then requests the next chunk, the next chunk of
records displays starting with the next record that was not visible.
Example: Next chunk displays after deleting a row then requesting the next chunk (chunk
size of 8)
Page 2469 of 4705
Home
Creating custom chunking buttons

You can customize a table to have its own next and previous chunk buttons, whether content
clipping is enabled or not, by using either the PERFORM-ACTION-TABLE-PREV-CHUNK or
PERFORM-ACTION-TABLE-NEXT-CHUNK Run Process action in the active link.
By using the following keyword and workflow commands, a developer can calculate whether the
next and previous chunking buttons should be enabled or disabled based on the current contents of
the table:
$LASTCOUNT$
PERFORM-ACTION-TABLE-GET-CHUNKSIZE
PERFORM-ACTION-TABLE-GET-CURRENT-CHUNK
Workflow should enable the custom control for retrieving the next chunk when the following
arithmetic operation evaluates to true:
$LASTCOUNT$ > value of PERFORM-ACTION-TABLE-GET-CURRENT-CHUNK * value of

PERFORM-ACTION-TABLE-GET-CHUNKSIZE
Similarly, workflow should enable the custom control for retrieving the previous chunk when the
following arithmetic operation evaluates to true:
value of PERFORM-ACTION-TABLE-GET-CURRENT-CHUNK > 1
Note
For information about keywords, the Run Process action, and workflow commands, see
Defining workflow to automate processes.
When content clipping is enabled for a cell-based table,

PERFORM-ACTION-TABLE-GET-CHUNKSIZE returns the current visible chunk size of the table.
The current visible chunk size is the number of cells that can be displayed in the available space,
and can be less than or equal to the value defined in Developer Studio. For non-content clipped
tables, PERFORM-ACTION-TABLE-GET-CHUNKSIZE returns the chunk size defined in Developer
Studio.
Page 2470 of 4705
Home
Note
When content clipping is enabled for a cell-based table, the custom chunking buttons do
not update when a table resizes. The custom chunking buttons do not update because
there is no event, and the event table refresh occurs just before the actual refresh of the
table.
Alert lists
Use an alert list table field to display an alert list in the web view:
Alert list table field
Each BMC Remedy 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.
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 Using the alert list in a
browser.
For more information about alert lists, see the following sections:
Structure of alert list table fields
Editing row data in alert lists
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.
Page 2471 of 4705
Home
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.
Results lists
Forms can display results lists in these formats:
Results list pane By default, forms viewed 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.
Results list table field This 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 request's 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).
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).
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:
Types of table fields
Table field
View in a browser?
Page 2472 of 4705
Home
List view
Yes
Tree view
Yes
Cell-based
Yes
Alert list
Yes
Results list 1
Yes
Results list table fields are primarily for legacy support. For information about results list panes,
see Defining search results.
To create a table field, perform these procedures:
1.
2.
3.
4.
5.
Adding a table field to a form

Customizing table labels
Setting column properties
Setting sort order and visible levels
(Optional) Setting table colors
6. (Optional) Defining a context menu

7. Setting the remaining table properties
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 select 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.
c. (List view, tree view, cell-based, alert list only) In the Data Source field, select the
source of the table's data:
Page 2473 of 4705
c.
Home
SERVER The table displays data from the server specified in the Server
Name field and the form specified in the Form Name field.
SAMPLE DATA The 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.
d. (List view, tree view, cell-based only) In the Server Name list, select the server that
contains the form that supplies the table's data.
e. (List view, tree view, cell-based only) To select the form that supplies the table's 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 Using buttons and menu bar items to execute active links .
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.
Page 2474 of 4705
Home
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 .
For cell-based tables, fields in the working cell are called cell fields. You can
add these types of cell fields:
From the current form Button, character fields whose entry mode is
Display, menu item, navigation item, trim, and view.
From the source form Data fields.
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.
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.
Properties used for table fields
Property
Description
Auto Fit
Columns
(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.
Background
Color
(Cell-based only) Background color of all cells in the cell-based table.
Background
Image
(Cell-based only) Background image in all cells in the cell-based table. See Adding background images to
fields and form views.
Background
Image
Horizontal
(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.
Page 2475 of 4705
Home
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.
Content
Clipped
(Cell-based only) Specify if cell-based tables will display as many cells as can fit in the table without
displaying a scrollbar. Values are:
False
True
Note
This property can only be set when table chunking is enabled. See Size of Chunk.
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
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 BMC Remedy 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.
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
information about how NULL values are treated in tree view fields, see Tree view tables.
when this property is set to True.

Horizontal
Space
(Cell-based only) Width of the space between columns of cells. Specify in points.
Initial Row
Selection
Specify what happens the first time the table field is displayed:
Select First, Fire Workflow The first row or child node is selected, and enabled workflow is
executed.
Select First, No Workflow The first row or child node is selected, and no workflow is executed.
No Selection No item is selected.
Layout
Style
(Cell-based only) Specifies how fields are laid out in each cell. See Panel layout styles.
Note
Margin
Bottom
(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.
Page 2476 of 4705
Home
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. 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
(Cell-based only) Color of lines surrounding the cells.
Border
Color
Panel
(Cell-based only) Dimension of lines surrounding the cells. Specify in points.
Border
Thickness
Panel
Height
(Cell-based only) Size of cells from top to bottom. Specify in points.
Panel
(Cell-based only) Size of cells from left side to right side. Specify in points.
Width
Previous
Label
(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.
Refresh on
Entry
Change
(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:
(Browsers) Clicking the Refresh button if the developer supplies it (see Customizing table labels)
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.
Refresh
Row
Selection
Specify what happens when a table is refreshed:

Retain Selection, Fire Workflow The current selection is retained, and enabled workflow is
executed.
Retain Selection, No Workflow The current selection is retained, and no workflow is executed.
Select First, Fire Workflow The first row or child node is selected and enabled workflow is
executed.
Select First, No Workflow The first row or child node is selected and no workflow is executed.
No Selection No item is selected.
Row
Selection
Specify how users can select rows in a table:

Multiple Users with selection capability can select multiple rows at the same time. This is the
default.
Single Users with selection capability can select only one row at a time.
None Row 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
Size of
Chunk
(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:
Page 2477 of 4705
Home
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 field's Next
Label and Previous Label properties.
Notes
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.
For tree views, you cannot set chunking in BMC Remedy Developer Studio. If you set
chunking through the BMC Remedy AR System server configuration file ( ar.conf or ar.cfg
), users see only the first chunk in the tree, and they cannot display the next chunk. See
Server-Side-Table-Chunk-Size.
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 a browser to open the row's source request in Modify mode. For tree views, users must
double-click a node. See also Row Header.
Vertical
Space
(Cell-based only) Width of the space between rows of cells. Specify in points.
Visible
Columns
(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.
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.
Label properties
Property
Location
Description
Header
Page 2478 of 4705
Home
Auto
Refresh
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
BMC Remedy AR System installed forms.
String
Delete
Button
Footer
The label for the alert delete button.
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 all or cancel all check-box column to tables .
Number of
Header
Entries
Returned
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. 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}".
If content clipping is enabled, these parameters are passed to this string:
{0} Starting row number
{1} Row number of last visible row
{2} Total visible rows
{3} Maximum number of rows that can be returned
Preferences
Header
When a value is entered in this field, 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.
Read
Button
Footer
The label for the button used to mark an alert as read.
Note
Available only in a browser.
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 earlier versions.
Report
Button
Footer
The label for the report button.
Row
Body
BMC Remedy AR System server 7.5.00 This property enables developers to specify a
Header
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.
Note
For the best results, specify the first column in the table.
BMC Remedy AR System server 6.3.00 - 7.1.00 This property is not supported. In those
releases, if users double-click a row, the selected record appears in the new window.
Page 2479 of 4705
Home
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 all or
cancel all check-box column to tables.
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
Header
The message that appears when a table is initially displayed.
Footer
The label for the button used to mark an alert as unread.
Loaded
String
Unread
Note
Available only in a browser.
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 field's position in the working cell.
The cell field's Help text also matches the form field's 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.
Page 2480 of 4705
Home
2. In the Properties tab, set the following column properties.

Column properties
Property
Description
Column
Width
Specify the width of the column in pixels. See also the Auto Fit Columns property.
Note
The column size in a browser is not exact. The mid tier tries to fit columns into the specified table
width. If a column's 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
Horizontal alignment: By default, all numeric fields are right-aligned. All other fields are left-aligned.
Alignment
Vertical alignment: By default, all cells default to center vertical alignment.
Display
Type
List view, tree view, alert list, results list

Select one of these options:
Read Only Users cannot change the field value.
Editable Users 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-HTML Users 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. 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 the
description of "Entry Mode" under Field properties.
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 display-only 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 field's display type:
Enter text into the Initial Value property's 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.
Page 2481 of 4705
Home
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.
3. For display-only fields, optionally specify a default value in the Default Value field. See 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 cell's 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 select Hide Header or Hide
Footer.
To redisplay the header or footer, right-click the table, and select 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 Using Run Process
and $PROCESS$ commands.
6. Set the remaining properties as necessary. See Field properties.

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 refreshed--that 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.
Page 2482 of 4705
Home
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, BMC Remedy AR System sorts the tree by the
column at the top of the Table Columns list in the Tree/Table Property dialog box.
Note
In a browser you cannot sort on columns that reference display-only fields.
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
characters 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 view tables .
8. Click OK.
Page 2483 of 4705
Home
Sorting tables in browsers

Requests to sort data in table columns are sent to the BMC Remedy AR System server, which
sorts the underlying data in the database. The 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.
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 the following figure.
Additionally, you can include a count, which displays how many rows are included in the section.
Example of groups in a table
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.
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 .
2.
Page 2484 of 4705
Home
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 table's 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 field's 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
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 heading's row.
8. Click OK.
Setting table colors

You can specify colors for the following table elements:
Table type
List view
Table row
Table cell
Text
Background
background
Page 2485 of 4705
Home
Tree view
Cell-based
+1
1. 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.
BMC recommends limiting 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.
To set cell colors, see Setting cell background colors in list view tables .
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 Selection fields) 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.
For example, you might make the background of all New requests red and the background of all
Assigned requests green, as shown in the following figure.
Example of row background color in a list view table
Or, as shown in the following figure, you might set the text of engine parts whose status is "
Backordered" in red to alert the assembly manager.
Example of row text color in a list view table
Page 2486 of 4705
Home
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 the following figure 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; so, the priority of the first request
under each leaf controls the color of the leaf.
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 field's 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. Select 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 value's Background cell, and select Custom from the drop-down list.
b.
Page 2487 of 4705
6.
Home

The selected color is displayed in the Background cell.
7. When you finish setting results colors for the selection field, click OK.
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 the following figure, cell colors help users see at a glance whether the score of a
vendor's 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).
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 form's 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 field's selection values appears in the Column Color dialog box.
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.
The selected color is displayed in the Color cell.
7.
Page 2488 of 4705
Home
7. When you finish setting column colors for the selection field, click OK.
Defining a context menu

A context menu contains menu and sub-level menu items, for individual BMC Remedy AR System
table objects including list view tables, tree view tables, and cell-based tables. For more information
about tables, see 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.
BMC Remedy AR System provides the capability to create static and dynamic context menus. A
static menu is one that has a static list of items and can have multiple levels. You need to plan your
menu structure; labels, hierarchy, and order of items, before creating a context menu with static
items.
On the other hand, a dynamic context menu provides you greater flexibility with the menu items.
The values for the menu items are attached at run-time. Menu from any of the supported BMC
Remedy AR System menu types can be attached. See Working with menus. You can use entries
from an existing BMC Remedy AR System form as menu items by attaching it to a context menu.
The following figure shows the dynamic context menu with a label. In this case, the menu items are
added as a sub-menu.
Dynamic context menu with label
The following figure shows the dynamic context menu without a label. In this case, the dynamic
context menu is attached to the main menu.
Page 2489 of 4705
Home
Dynamic context menu without label
For more information about workflows, see Workflow considerations for table fields. For more
information about creating sub-menus, see Creating character menus.
To create a static 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.
3. Right-click on the table and select Edit Menu/Navigation Items.
The Edit Context Menu dialog box is displayed.
Note
Alternatively, you can also select the table field and click Form > Edit Menu/
Navigation Items to display the Edit Context Menu dialog box.
4. In the Edit Context Menu 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.
Page 2490 of 4705
Home
To create a dynamic context menu in a table field

1. Setting fields in the form:
a. Follow steps 1-5 as specified in to create a static context menu to create a table with
context menu.
b. Add a Character field and a Button to the form.
c. For the Table, Character field, and Button fields added in step a and b, change the
Label names to more meaningful names. To do this, open the Display properties in
the Properties editor to update the Labels. See Field properties.
d. In the Properties editor for the table, open the Database properties for the context
menu and copy the Id.
Make a note of the field Id of the context menu item to which the BMC Remedy AR
System menu will be attached. At run-time, the workflow accepts the field Id and
dynamically attaches the context menu.
e. Right-click the form, and select Save.
2. Define an Active Link that attaches the context menu at run-time
a. Open a new Active Link and associate the form with it.
b. Set the Active Link to execute on the Button field that you have set on the form in
step 1b.
c. Right-click If Actions and select Add Action > Change Field.
d. In the Field list, select Field Value. Click the ellipsis button. From the Field /Keyword
Selector dialog box, select the Character field added in step 1b.
The runtime value of this field determines the context menu to be attached.
e. In the Menu list, select Changed. Enter the name of the menu to attach or click the
ellipsis button to select the menu from the Menu/Keyword Selector dialog box.
f. Save the Active Link.
If the context menu is disabled, the items attached to the context menu will also
appear disabled. Similarly, if the context menu is hidden, the items attached to the
context menu are not visible to the user.
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 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.
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.
Page 2491 of 4705
Home
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 Using a filter guide to loop through a table field .
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 non-NULL
values in a column. For more information about functions you can use with table fields, see
Controlling row selection in a table field .
For more information about using workflow in tables, see:
Workflow in tree view tables
Workflow in cell-based tables
Workflow in dynamic context menu
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 .
Workflow in cell-based tables

Workflow in cell-based tables for example, firing active links on row selection or setting the
current row by using an active link Set Field action works 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.
Page 2492 of 4705
Home
Workflow in dynamic context menu

BMC Remedy AR System menus can be attached to the table context menu item through indirect
change field action. At run-time the Character Field accepts the fieldId of the context menu to which
the BMC Remedy AR System menu later attaches. Menu selection triggers the workflow that is tied
to the table context menu item. Workflow can discover the value of the menu item that is selected
through $context menu item id$.
The dynamic menu follows the properties of the context menu. For example, if the context menu is
hidden, the dynamic menu cannot be seen. Similarly, you can enable or disable the dynamic menu.
When disabled, users can view the menu items but cannot select any of them. The menu items are
accessible when the context menu is enabled.
Displaying images in tables

You can display images in list view and tree view tables as shown in the following figure and the
following figure. The images are based on shared image objects stored in the BMC Remedy AR
System server (see Working with images). They are displayed by reference.
Images in a tree view table
Images in a list view table

Page 2493 of 4705
Home
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-to-one relationship.
Likewise, the same text can appear with different images (see "Emily" in the above figures).
In standard left-to-right format, images are displayed to the left of the text. In right-to-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 the above figures).
Images and their alternative text are stored with a form view, so they can be localized.
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
Page 2494 of 4705
Home
Image size
BMC recommends making 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. BMC Remedy AR System server uses them as is.
Images in tree view tables must be no larger than 16 X 16 pixels. If you use other sizes, in
browsers, BMC Remedy AR System server 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, BMC Remedy AR System server 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.
Image limitations
Images in tables can be associated only with the values in selection fields (drop-down 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).
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 BMC Remedy AR System server skins.
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 .
Column display types and images

The value of a column's Display Type property affects images as follows:
Page 2495 of 4705
Home
Value
Description
Read Only
The image appears to the left of the column. The image is not editable.
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.
Read
Only-HTML
In list view tables displayed in browsers, BMC Remedy AR System server 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.
Adding images to tables

This section explains how to perform these tasks:
Add images to list view and tree view tables (see To add an image to a list view or tree view
table).
Add an image to the root node of a tree view table (see To add an image to the root node of
a tree view table).
Page 2496 of 4705
Home
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 field's 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 the following figure)
Levels or columns in which images are the only differentiators (see the "Emily" nodes
in the following figure)
See Arranging nodes in tree view tables .
(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 the following
figure.
Effect of not using hidden sort levels to sort images in tree view tables
Page 2497 of 4705
Home
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 property's value cell.
This label appears in the tree view table's root node. For example, in the above figure, "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 property's
value cell.
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.
Page 2498 of 4705
Home
Adding buttons and URLs to tables

In pre-7.5.00 versions of BMC Remedy AR System server, 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:
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 table's scrollable area. To preserve standard row height in a browser, use CSS
to designate a small font for table button labels (see BMC Remedy AR System installed
forms).
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
table's scrollable area.
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.
Page 2499 of 4705
Home
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.
To add a button to a list view table

1. Add the button to the form that contains the table.
2. Select the table.
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 Only Button is disabled.
Editable Button is enabled.
Page 2500 of 4705
Home
Read Only-HTML Button 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.
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
Image
Label Font
Button Label
Image Position
Maintain Aspect Ratio
Display as Flat Image
Label/Text Color
Scale Image to Fit
Adding a Select All or 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 the following figure).
List view table with Select All and Deselect All buttons
Page 2501 of 4705
Home
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 the following figure).
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 row's check box:
Page 2502 of 4705
Home
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 row's 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 row's 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 all or cancel all check-box column to a table
Note
This feature applies only to list view and results list tables in browsers.
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.
Page 2503 of 4705
Home

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 Allbuttons
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 BMC Remedy AR System server. Instead, the Select All and Deselect
All buttons appear in the table footer.
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 the following figure 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.
Using dynamic table fields
In this example, two requests exist in the Source form on the server cordova. If users open the
Dynamic Table Field form in the mid tier, 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
Page 2504 of 4705
Home
You cannot use a dynamic data source in a results list.
To create a dynamic table

1. Select the appropriate table.
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.
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 the above figure, 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.
Page 2505 of 4705
Home
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 the above figure, the table includes two columns that are core fields required
on every form: Request ID and Short Description.
8. Click OK.
Dynamically defining table field search criteria

To enable users to define table field search criteria dynamically, use the EXTERNAL() operator.
For more information, see Operator types.
Updating tables on-screen only

BMC Remedy 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 on-screen 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 BMC
Remedy AR System server database.
Results list, alert list, and server-side tables do not support this feature.
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. 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.
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.
Page 2506 of 4705
Home
PERFORM-ACTION-TABLE-ADD-ROW This 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 ). 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.
List view table with an empty row inserted at index 3
Tree view table with an empty node inserted at index 3

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 row's state to
Deleted. It does not, however, remove the row from the database. So, 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-ROWSTATE This 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
Page 2507 of 4705
Home
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. Because of this, you can undo the table row additions without calling
the server and database to refresh the table.
PERFORM-ACTION-TABLE-CHANGE-ROW-COL-VISIBILITY On-screen, 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 Using Run Process and $
PROCESS$ commands. For an example of how these Run Process commands can
be used, see Use case scenario for temporarily displaying table rows on-screen .
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 Set Fields action. For special tree view table
considerations, see Using Set Fields with temporary tree nodes .
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 row's 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:
Row states returned by the $ROWCHANGED$ keyword
Row state
Value
Description
Loaded or
Unchanged
When a table is refreshed, the state of all its rows is set to Loaded (0).
Modified
When either of the following actions occurs, a row's 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)
When an empty row is added to a table, its state is set to New (2).
Deleted (removed)
When a row's 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 PERFORM-ACTION-TABLE-ADD-ROW set
the row state to New, you could run a Push Fields action to add the row to the database.
Warning
Page 2508 of 4705
Home
If one of the following actions occurs before the changes are saved, the changes
will be lost:
The table is refreshed (browsers).
The table is re-sorted (browsers).
The form is closed (BMC Remedy AR System server does not prompt users to
save their changes).

Using Set Fields with temporary tree nodes
Use case scenario for temporarily displaying table rows on-screen
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 the following figure, this function returns the number
of table rows in the underlying form represented by that branch, which is 2. 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.
On Italian branch, SELECTEDROWCOUNT returns 2
For information about using functions with the Set Fields action, see Additional ways to use the Set
Fields action. For information about PERFORM-ACTION-TABLE-ADD-ROW, see Using Run Process
and $PROCESS$ commands.
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.
Page 2509 of 4705
Home
For example, suppose an empty node is added to index 3 of the tree view table in the following
figure.
Empty node added to row index 3 of tree view table
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
Note
In each case, before performing the Set Fields action, you must select the empty node.
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 the following figure
was created by inserting an empty node at index 1 and setting the node values to ["Japanese",
"Ramen"].
Duplicate nodes produced by poorly designed workflow
Page 2510 of 4705
Home
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 the following figure. 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.
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. 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 the following figure. 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.
Page 2511 of 4705
Home
Set Fields action to parent node

Use case scenario for 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 BMC Remedy AR System server 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, BMC Remedy AR System server 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.
For example, to create a team that includes Bob Burke and Fred Fairchild, a user and BMC
Remedy AR System server might perform these steps:
1. User Select Fred Fairchild in the Available Employees table, and click the right arrow
button.
Page 2512 of 4705
1.
Home
2. BMC Remedy AR System server

On button click, execute an active link that performs these actions:## Executes this Run
Process command to delete row 6 from the Available Employees table on-screen:
PERFORM-ACTION-TABLE-DELETE-ROW AvailableEmployeesTableFieldID6
6 is the index of the row in memory. Although the row is no longer visible on-screen, 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 Using Run Process and $PROCESS
$ commands.
a. Executes this Run Process command to insert an empty row in the Team Members
table on-screen:
PERFORM-ACTION-TABLE-ADD-ROW TeamMembersTableFieldID1
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 Using Run Process and $
PROCESS$ commands.
b. 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 Specifying workflow actions.
On-line, the tables now look like this:
3.
Page 2513 of 4705
Home
3. User Select Bob Burke in the Available Employees table, and click the right arrow button.
4. BMC Remedy AR System server On 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 AvailableEmployeesTableFieldID2
2 is the index of the row in memory. Although the row is no longer visible on-screen, 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 TeamMembersTableFieldID1
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. User Click OK to save the changes.

6. BMC Remedy AR System server On 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.
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
Page 2514 of 4705
Home
settings to the preference server, making them available for future logins on the web.
Users can set preferences for any visible table column except columns (levels) in tree views.
To enable preferences, make sure the table field's Preferences property has a value. For more
information, see the "Preferences" property description under Customizing table labels.
The following sections describe table column preference options and how they work in a browser.
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.)
Preferences button and menu items in web table header
When clicked, the button displays a drop-down menu with these options:
Add Column Displays 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 table's 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 Column Displays 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 Interval Sets the interval at which a table, including the results list pane, is
automatically refreshed. See Setting refresh intervals.
Reset Restores column width, visibility, and sort order to administrator-defined values.
Sets the refresh interval to 0.
Save Saves the current column settings to the user's 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.
Page 2515 of 4705
Home
Refreshing table fields

When a table field is refreshed, information from the table's 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 Adding a table field to a form ) 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.
Setting refresh intervals

In a browser, users can set the interval at which a table, including the results list pane, is
automatically refreshed by choosing Preferences > Set Refresh Interval in the table's header.
Valid values are 0-99 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.
Locale-specific refresh
To refresh tables with locale-specific information, set the table field's Use Locale property to True.
Now, when the table is refreshed, the system returns only requests related to the user's locale.
In the Advanced tab of the AR System Administration: Server Information form, the Localize
Server option must be selected, and the Locale field must be on the form. For more information
about the Locale field, see Form view initial properties and Form view properties - Basic category.
Working with menus

This section describes how to work with menus including creating and modifying character field
menus.
Before performing the procedures described in this section, familiarize yourself with BMC Remedy
AR System forms and Creating and managing fields.
Character field menus
Creating character menus
Creating SQL menus
Creating search menus
Creating file menus
Creating help text for menus
Page 2516 of 4705
Home
Recording menu change history

Automatically completing menu entries
Adding and removing clear from drop-down lists
Refreshing menus
Creating data dictionary menus
Deleting menus
Copying menus
Modifying menus
Creating dynamic search menus
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 Menu Displays a static list of items configured in BMC Remedy Developer
Studio. See Creating character menus.
File Menu Displays a formatted character menu by referencing an external plain text file.
See Creating file menus.
Search Menu Draws menu labels and values from a specified form. Used to create
menus that are automatically updated to reflect your system's current data. See Creating
search menus.
SQL Menu Uses 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.
Field Data Dictionary Menu Pulls labels and values from field objects in the BMC
Remedy AR System data dictionary. See Creating data dictionary menus.
Form Data Dictionary Menu Pulls labels and values from form objects in the BMC
Remedy AR System data dictionary. See Creating data dictionary menus.
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 Setting the
General tab.
Note
Do not confuse character field menus with menus in the menu bar used to execute active
links (see Using buttons and menu bar items to execute active links ) or menus in
drop-down list selection fields (see Selection fields).
Page 2517 of 4705
Home
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 application's Menus list.

A character menu is a static list of items that can have multiple levels. Plan your menu structure
before creating a character menu. The following figure shows an example of a plan, including
parent and child menu items.
Design for parent and child menus
To create a character menu

1. In BMC Remedy Developer Studio, select 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 the following figure). It has two properties:
Label The text that appears on the menu. The default label is New Menu 0.
Value The text that is entered into the character field when users select this menu
item. The default value is New Menu 0.
New character menu
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.
Page 2518 of 4705
Home
7.
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.
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 the above figure:
a. Click Add Menu, and replace the default label and value with AR System.
b. Select the 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 Remedy Import.
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 menu's change history.
See Recording menu change history.
11. (Optional) Add Help text to the menu.
See Creating help text for menus.
13. In the Save Menu As dialog box, enter a name for the menu, and click OK.
Menu names must be unique on each BMC Remedy 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 and Menu Name.
Page 2519 of 4705
Home
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 BMC Remedy AR System server 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 database-specific 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.
To create an SQL menu

1. In BMC Remedy Developer Studio, select File > New > SQL Menu.
A new SQL menu appears as shown in the following figure.
New SQL menu
3. In the Refresh list, select the appropriate refresh mode.

See Refreshing menus.
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.
Page 2520 of 4705
Home
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 select a menu item.
Only the first 255 bytes of each field value are displayed.
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 Using the expression editor and content assist .
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 BMC Remedy 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
interpreter, for example,isql for Sybase, SQL*Plus for Oracle, Command Center for
DB2, or Query Analyzer or Microsoft ISQL/w for Microsoft SQL Server, and enter the
same SQL query directly into the database to see what results are returned.
If the SQL operation fails, a BMC Remedy 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.
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.

12.
Page 2521 of 4705
Home

See also:
Sample SQL menu
Database security issues
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 the following figure.
Results returned from the sample SQL query
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 the following figure).
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 selects John from the menu, the BUG_ID value associated with John is entered
into the field (see the following figure).
Page 2522 of 4705
Home
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 the
following figure).
Field value if Value Index is set to 3 in sample SQL menu
Entering 2,3 into the Label Index List field creates a hierarchical menu (see the following figure).
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:

Users of SQL queries
Database
User
DB2
The user who installs BMC Remedy AR System server
ARAdmin
Oracle
ARAdmin
Page 2523 of 4705
Home
Database
User
Sybase
ARAdmin
If you run BMC Remedy AR System as one of these users without permission to access the
database, you cannot issue the SQL query.
To access non-BMC Remedy AR System server 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

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"
).
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, select File > New > Search Menu.
A new file search appears as shown in the following figure.
Page 2524 of 4705
2.
Home
New search menu


4. In the Data Source list, select one of these options:
SERVER The menu displays data from the server specified in the Server field and
from the form specified in the Form Name field.
SAMPLE DATA The 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.
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.
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:
Page 2525 of 4705
Home
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 field's values are the first-level menu items, the second field's 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 select 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 single-byte
characters, this field displays 254 characters. In case of locales that use multi-byte
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.
11. Select or clear the Sort On Label check box:
Selected Menu 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.
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.
Page 2526 of 4705
12.
Home
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 Using buttons and menu bar items to
execute active links.
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, select File > New > File Menu.
A new file menu appears as shown in the following figure.
New file menu
Page 2527 of 4705
Home

4. In the Location list, select the location of the file that contains the menu definition:
Server File is on the computer where the BMC Remedy 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.
Creating dynamic file menus
Menu file format
Creating dynamic file menus

Instead of hard-coding a file menu's 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.
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, select File > New > File Menu.
3. In the Refresh list, select the On Open refresh mode.
4. In the Location list, select Client.
5.
Page 2528 of 4705
Home
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 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.
If you insert a pound sign ( #) at the beginning of a line of text, the text that follows the pound sign is
ignored.
Note
Page 2529 of 4705
Home
A menu file for a Unicode system must use the encoding used by that system. A menu file
stored on a Unicode BMC Remedy 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 help text for menus

You create help text for menus the same way that you create help text for other objects. See
Providing help text.
Recording menu change history

BMC Remedy 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 Field Properties.
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.
Page 2530 of 4705
Home
This feature applies only to forms viewed in a browser.

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 Defining workflow to automate processes.
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
Description
Auto
Complete
Determines what types of matches are displayed. The options are:

None (the default) Disables auto-complete.
Leading Match Lists menu options that begin with the text that the user entered in the field.
Anywhere Match Lists 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.
Auto
Complete
Hide Menu
Button
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.
Label Menu 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
Page 2531 of 4705
Home
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
re-enabled 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 (default) Menu values are displayed and used for matching while typing, as
well as for completion.
Label Menu 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.)
Considerations for search menus with large data sets
Workflow considerations
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
field's 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 field's 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.
Page 2532 of 4705
Home
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 Defining workflow to automate processes.
Adding and removing clear from 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 types, character, file, search, SQL,
and data dictionary, of character field menus.
When users select (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.
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.
Page 2533 of 4705
Home
Refreshing menus
For all menu types except character menus, you must set a refresh mode:
On Connect Retrieves the menu when the user opens the menu after selecting the form.
To update the menu, the user must reopen the form.
On Open Retrieves 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 Interval Retrieves 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 menu's 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.

A data dictionary menu pulls labels and values from field or form objects in the BMC Remedy AR
System server data dictionary.
To create a data dictionary menu

1. In BMC Remedy Developer Studio, select File > New > dataDictionaryMenuType, where
dataDictionaryMenuType is one of these values:
Field Data Dictionary Menu The menu pulls labels and values from field objects
in the data dictionary.
Form Data Dictionary Menu The menu pulls labels and values from form objects
in the data dictionary.
A new data dictionary menu appears as shown in the following figures.
New field data dictionary menu
New form data dictionary menu

Page 2534 of 4705
Home

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:
Name The name of the object in the database.
Label The label displayed for the object in the client.
ID The ID of the object.
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:
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:
c. 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.
d. To display hidden forms matching the form type, select the Show Hidden Forms
check box.
11.
Page 2535 of 4705
Home
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
2. In the All Objects list, double-click the Menus node.
3. In the Menus object list, right-click the menu, and select Delete.
The menu is deleted from the database and the Menus object list.
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
3. In the Menus object list, double-click the appropriate menu.
The menu is displayed in the editor area.
5. In the Save Menu As dialog box, enter a new name, and click OK.
Modifying menus
Use this procedure to modify a menu.
To modify a menu
3. To rename the menu:
a. In the Menus object list, right-click the menu, and select Rename.
b. In the Rename Menu dialog box, enter a new name, and click OK.
4. To change the menu type:
a.
Page 2536 of 4705
4.
Home
a. In the Menus object list, right-click the menu, and select 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 menu's fields as needed.
For information about those fields, see one of these sections:
Creating file menus
Creating SQL menus
Creating dynamic search menus

Instead of hard-coding a search menu's 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 the following figure, 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.
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 the mid tier, 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 (
Page 2537 of 4705
Home
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, select File > New > Search Menu.
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.
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:
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 Using dynamic table fields, the Runtime Server field is set to
server, and the Runtime Form Value is set to form.
7. Go to step 8 in To create a search menu and perform the remaining steps in that procedure.
Page 2538 of 4705
Home
Working with images

This section describes how to create and modify image objects. For more information, see:
Adding background images to fields and form views
Using transparent images
Using image objects
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 a BMC Remedy AR System server 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, BMC
Remedy AR System clients and supporting applications such as 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 select .bmp, .jpeg, .jpg, . gif, and .png files. The selected 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 Image The 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 Reference A 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 BMC Remedy AR
System server. 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.
4.
Page 2539 of 4705
Home
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:
Left Position the left edge of the image at the left edge of the panel or cell.
Center Position the horizontal center of the image at the horizontal center of the
panel or cell.
Fill Resize the image horizontally to fit the width of the panel or cell.
Right Position the right edge of the image at the right edge of the panel or cell.
Tile If 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:
Top Position the top edge of the image at the top edge of the panel or cell.
Center Position the vertical center of the image at the vertical center of the panel
or cell.
Fill Resize the image vertically to fit the height of the panel or cell.
Bottom Position the bottom edge of the image at the bottom edge of the panel or
cell.
Tile If 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.
Using transparent images

In earlier versions, BMC Remedy AR System server supported only .bmp, .dib, .jpeg, .jpg, .targa,
and .tiff images. Those image types cannot have transparent backgrounds.
In BMC Remedy AR System server 7.5.00 and later, the following BMC Remedy AR System
components support .gif and .png images, which can have transparent backgrounds:
BMC Remedy Mid Tier
Note
PNG images that use alpha transparency are supported by Firefox, and Safari. PNG and
GIF images that use binary transparency are supported by all BMC Remedy AR System
server compatible browsers.
Page 2540 of 4705
Home
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. The following figure shows a .gif coffee cup image with a
transparent background on a regular button and on a borderless button.
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 the following
figure.
Transparent images as toolbar buttons
Tip
To add decorative graphics to forms, use borderless buttons without workflow.
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
.
You can use .gif and .png images anywhere that images are supported in BMC Remedy AR
System server, including
Backgrounds on form views
Backgrounds on standalone panel fields
Using image objects

An image object is an image stored in the BMC Remedy AR System server database with
information defining the image as a BMC Remedy AR System server object. The image object type
appears in the AR System Navigator pane at the end of the All Objects list (see the following figure)
.
Page 2541 of 4705
Home
Image objects in BMC Remedy Developer Studio

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.
BMC Remedy AR System server 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)
Note
To convert existing references and image files to shared images, use the
ImageExtractor.bat utility. See ImageExtractor.jar (ImageExtractor.bat).
For more information about image objects, see:

Working with image objects
Using backslashes in image object names
Creating image objects
Working with image objects

This section explains more about working with image objects.
To open an image object

2.
Page 2542 of 4705
Home
2. Double-click Images.
3. From the Images list, double-click the image object to open.
To save an image to a file outside BMC Remedy AR System server

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

3. Right-click the image to be renamed, and then select 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.

3. Right-click the image to be renamed, and then select 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.
Using backslashes in image object names
Important
Page 2543 of 4705
Home
Although BMC Remedy AR System server permits backslashes in image object names,
the recommendation 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

2. Right-click Images, and select 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.

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.
To create table fields, see Creating table fields.
To create panel fields, see Creating panels.
For detailed descriptions of each field, see Creating and managing fields.
Page 2544 of 4705
Home
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 fields, see:
Core fields
Reserved fields
Data fields
View fields
Creating fields that are not in form view
Attachment pools
Button fields
Trim fields
Application list fields
Navigation fields
Creating global fields
Executing entry points in HTML
Managing fields
Working with fields in join forms
Field Properties
Properties tab for fields in Best Practice Customization Mode
Core fields
BMC Remedy 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
Page 2545 of 4705
Home
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. BMC Remedy 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 BMC Remedy 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.
BMC Remedy Developer Studio localizes the labels of the core fields based on the server language
and whether the server is UTF-8 or not. If the server is UTF-8, then the Developer Studio uses the
current locale to localize the labels and does not base it on the server language.
The following table lists the BMC Remedy AR System core fields.
BMC Remedy AR System core fields
ID
Field name
Description
Request ID
A unique identification value for each request in the system.

The Request ID field contains a character string that holds a unique index for each request. The form of this
string is an optional prefix, which can consist of any alphanumeric characters, followed by a 0-padded numeral
(for example, HD0000000000001 ). The length of the Request ID field must be either 1 or between 5 and 15
characters, inclusive. Specifying a length of 1 causes leading zeroes to be stripped from the value in the
Request ID field. The prefix can be as long as the total length of the field less five characters.
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: 5-15
For join forms, there is no limit to the number of layers of joins that BMC Remedy AR System supports, so the
Request ID field of a join form contains more than 15 characters. See Joining three or more forms for more
information.
Note
Do not change the QBE Match setting to Equal for the Request ID field. Because BMC Remedy 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.
Submitter
Page 2546 of 4705
Home
The name of the BMC Remedy 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 groups--Row-level security. 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 BMC Remedy AR System server sets
Assigned
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 groups--Row-level security.
Data Type: Character Length: 254
To
Last
Modified
By
Modified
Date
Status
this field, and it cannot be modified. Data Type: Timestamp
The name of the user who last altered the request. BMC Remedy AR System sets this field to the login name
of the user who last changed the request. It cannot be modified. Data Type: Character Length: 254
The date the field was last modified. The BMC Remedy AR System server sets this field to the time the last
change to this request was made. It cannot be modified. Data Type: Timestamp
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
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. BMC Remedy 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
Core field characteristics

The following core fields have special characteristics that you should consider when defining a new
form.
Request ID field
BMC Remedy 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 Changing the
Request ID field length or prefix.
The Request ID field is fundamental to access control in BMC Remedy 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 .
Page 2547 of 4705
Home
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. For information about preventing changes to this field, see Enabling submitters to modify
requests.
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
Working with menus.
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, BMC
Remedy 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.
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 BMC Remedy
AR System, see Special groups in BMC Remedy AR System .
Page 2548 of 4705
Home
Reserved fields
BMC Remedy 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.
BMC Remedy 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 BMC
Remedy 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.
For more information about reserved fields, see:
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

BMC Remedy AR System has special ranges of field IDs. Numbers 1-99 are reserved for core
fields. Numbers 100-536868911 are reserved for registered fields. The following table lists reserved
field ranges that forms and applications use in BMC Remedy AR System.
ID range
Type of fields, forms, or applications that use the field IDs
1-99
Core fields
101-149
Access control fields
150-159
AR System Message Catalog
Page 2549 of 4705
Home
ID range
Type of fields, forms, or applications that use the field IDs
200-399
Distributed Server Option forms
450-469
Audit fields
600-699
Business Time forms
700-750
Alert forms
800-810
Server Events form
820-880
Business Time forms
900-999
Server Statistics form
1000-1100
Form Action fields
1101-1399
Application Statistics forms
1500-1525
Currency forms
1700-1799
Roles form
2000-2299
Application States
2300-2699
Business Time forms
10000-14999
Approval Server Option
15000-15999
Enterprise Integration Engine
17000-17399
Reporting forms
18000-19999
Email Engine
20000-39999
Preference forms
40000-40499
Flashboards
53000-53199
Query builder widget (AR System Query Fields use 53150-53199.)
60000-60999
Dynamic group fields
536870999-536880999
BMC Remedy Identity Management
536881000-536890000
BMC Remedy Identity Management View ID
610000000-610001000
Entuity EYE-of-the-Storm
610001001-610001100
IDS ARIS Integration
900000000-909999999
BMC IT Business Management
1000000000-1999999999
BMC IT Service Management
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 might 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
Page 2550 of 4705
Home
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.
Reserved IDs for special operations
ID
Field
name
Description
97
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
98
Like ID
Used in Push Fields and Set Fields actions to indicate mapping of like IDs. Data type: Character
99
Weight
Number between 1 and 100 indicating the quality of a match. The closer to 100, the better the match. Data
type: Integer
1576
AppSubset
Used to display a subset of entry points. This field is hidden on the default Home Page form installed with the
BMC Remedy AR System. Create this field as necessary on your own home page form. Data type: Character
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. For more information about access control, see
Access control.
Reserved fields for access control
ID
Field name
Form
Description
101
Login Name
User
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
Page 2551 of 4705
Home
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: 0-100 (can be expanded)
107
Group Type
Group
The maximum permission type intended for the group named in the Group name field.
Data type: Selection (None, View, Change)
108
Default
User
The notification method used if the user specifies the default mechanism. Data type:
Notification
Mechanism
Selection (None, Alert, Email)
109
License Type
User
The type of license that the user has. Data type: Selection (Read, Fixed, Floating)
110
Full Text
License Type
User
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 row-level security. For more information about this
type of security, see Controlling access by using implicit groups--Row-level security. 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 Setting up an authentication alias. Data type: Character Maximum length: 254
118
Authentication
String
User
This field is used for external authentication under certain conditions. For more information,
see Setting up an authentication alias. 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:
120
Group
Category
Group
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 Regular, computed, and dynamic groups. 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 Making applications licensable for
integration system vendors. 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 BMC Remedy 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
Page 2552 of 4705
Home
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
2002
Production
Roles
The regular or computed group to which you want to map the role for the Production
application state. Data type: Character Maximum length: 255
6000060999
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 Row-level security for controlling access by using implicit groups . Data type:
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 BMC Remedy 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 BMC Remedy AR System.
See your product documentation for more information. Data type: Character Maximum
length: 38

The following reserved field is used for localization.
ID
Field
Description
name
160
Locale
Add this field to a form to localize search menus. The system uses this field to search for requests matching the
user's locale. For more information, see Creating and managing fields. Data type: Character Length: 255
DSO reserved fields

Distributed Server Option can add one or more of the reserved fields shown in the following table.
DSO reserved fields
ID
Field name
Description
300
To Mapping
The name of the mapping to use when transferring a request. Data type: Character Length: 254
301
Transfer
The status of a distributed transfer operation. Data type: Selection (Success, Retry, Failure, Timeout,
Status
Canceled)
Update
Status
The status of a distributed update or return operation. Data type: Selection (Success, Waiting, Retry,
Failure, Timeout, Canceled)
302
Page 2553 of 4705
Home
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
The ID of the request from which this copy was transferred. Data type: Character Length: 15
Request ID
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 information--the 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
311
From Server
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
The action that occurs if you transfer a request and a request with the same ID already exists in the form
Entry ID
Action
specified in the To Form field. Data type: Selection (Create New, Error, Overwrite)
317
Max Time to
Retry
The maximum time (in seconds) that the system should retry a distributed operation before canceling the
operation. Data type: Integer
318
From Pool
DSO pool on the source server that processed the distributed operation. Data type: Character Length: 254
319
Enforce
Pattern
Matching
Flag indicating whether to enforce patterns defined in fields on the target form during distributed operations.
Date Type: Selection (No, Yes)
320
Require
Required
Fields
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)
321
Matching
Qualification
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
Performing distributed operations on join forms. Data Type: Display-only character Length: Undefined
Page 2554 of 4705
Home

The following fields are used in web applications to help users perform actions. For more
information about form action fields, see Adding form action fields to a form .
ID
Field name
Description
706
Alert List
Displays the alert list. Data type: Table
1001
Submit
Performs a save operation in New mode to create a record. Data type: Button
1002
Search
Performs a search operation. Data type: Button
1003
Modify
Performs a save operation in Modify mode to save a record. Data type: Button
1004
Modify All
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
Clear
Clears all data in fields on the screen. Data type: Button
1007
Set to Default
Sets the form to the default settings. Data type: Button
1008
Help
Opens help for the form. Data type: Button
1009
New Search
Changes the form to Search mode. Data type: Button
1010
New Request
Changes the form to Create mode. Data type: Button
1011
Show Status History
Displays the progress made on a BMC Remedy AR System server request. Data type: Button
1012
Home
Displays the form you have configured as your home page. Data type: Button
1020
Results List
Displays results of a search. Data type: Button
Data fields
Data fields contain data and can be any one of the following data types:
Character
Currency
Diary
Integer
Date/Time
Real
Date
Decimal
Time
Selection
(drop-down, radio, check box)
The following sections describe these types of fields:
Page 2555 of 4705
Home
Character fields
Diary fields
Date and time fields
Integer fields
Real fields
Currency fields
Selection fields
Decimal fields
Creating data fields
To learn how to add them to forms, see 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 the Expand Box
property description under Field Properties.
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 the following table, a clob is used.
Maximum varchar size
Database
Maximum Input Length for varchar
IBM DB2
3999
7999
Oracle
3999
Sybase
255
Note
To include a tab in the text that you enter into a character field, press Ctrl+Tab.
Page 2556 of 4705
Home
Oracle CLOB storage

If a BMC Remedy 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 Setting database options.)
For BMC Remedy 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 the CLOB Storage
property description under Field Properties.
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
BMC Remedy AR System server with a time and a user name. After they are saved, diary entries
cannot be modified.
By default, BMC Remedy 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 field's dialog box, the user must
press Ctrl+Tab.
The default maximum size limit of data contained in diary fields varies per database:
For Sybase and Microsoft SQL Server 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 BMC Remedy AR System configuration files .
Page 2557 of 4705
Home
To search a diary field when using Oracle, you must configure ar.conf (ar.cfg ) to allow searching
on CLOB data types. See ar.cfg or ar.conf.
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.
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 to create a search index
for the field. For more information, see Enabling full text search.
Note
Web reports do not support diary fields.
Date and time fields

There are three types of date and time fields:
Date/Time Stores 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.
BMC Remedy 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.
Date Stores 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.
Time Stores 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 user's 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.
Page 2558 of 4705
Home
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 Defining workflow
to automate processes.
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.
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 value Decimal values are displayed according to the user's
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 field's 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 Localizing
currency codes).
A currency code can be entered into the field in any of the following ways:
Default value At runtime, a user can enter the code into the field or select the
code from the menu attached to the field.
User preferences Users can specify a preferred initial currency type 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 code's
currency type is not one of the field's allowable currencies (see Allowable and
Page 2559 of 4705
Home
functional currencies). 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 type Developers can specify an initial currency code in a currency
field's Initial Currency Type or Default Value properties. The default value overrides
the initial currency type.
Primary allowable currency If users do not specify a code, the system adds the
code of the primary allowable currency when the request is saved. See Adding a
currency field to a form.
One or more functional currency values Generated when users save the data that they
entered in the currency field. See Allowable and functional currencies.
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.
Date on which the functional currency values were generated After entering data into
a currency field and saving the request, users can view the field's functional currency values
by clicking the expand button next to the currency field, as shown in the following figure.
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.
Page 2560 of 4705
Home
To learn how to add currency fields to forms, see Creating currency fields.
Note
Web reports support currency fields, but do not support currency value and currency type
. BMC Remedy AR System reports support currency value and currency type.
For more information about currency fields, see the following sections:
Creating currency fields
Adding a currency field to a form
Field name considerations
Setting currency field information
Currency exchange ratios
Allowable and functional currencies
Workflow considerations for currency fields
Creating currency fields

Use this process to create currency fields:
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 Setting currency types)
. 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.
2. Add a currency field to a form (see Creating currency fields).
3. Create currency exchange ratios (see Currency exchange ratios).
Note
For an overview of currency fields, see Currency fields.
Adding a currency field to a form

Use this procedure to add a currency field to a form.
To add a currency field to a form

2. Right-click the form, and select Create a New Field > Currency.
3.
Page 2561 of 4705
Home

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 the following figure.
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
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.
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.
Page 2562 of 4705
Home
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 currency's decimal precision, click the precision field in the
Selected Types list, and select a precision value from the drop-down list.
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.
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 currency's 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 Value Specifies 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.
Page 2563 of 4705
Home
Initial Currency Type Specifies 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 the mid tier.
9. Set the other field properties as needed.
10. Select the field, drag it to a position in the form, and adjust its size.
Field name considerations

When the ODBC driver accesses a currency field for example, when you run a report it
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 issue, do not use field names that conflict with the column names generated by the
ODBC driver for currency fields.
Setting currency field information

Set currency field information in these locations:
Locations for currency information
Currency
Where to set
information
Default allowable
and functional
currencies
Currency Types tab of the AR System Administration: Server Information form. See Setting currency
types. The defaults appear in the Currency Types property dialog box of all new currency fields.
Individual field
currencies
BMC Remedy Developer Studio. See Creating currency fields.
Localized currency
AR System Currency Label Catalog form. See Localizing currency codes.
labels
Currency exchange ratios

To convert allowable currency values into functional currency values, BMC Remedy AR System
uses currency exchange ratios that you specify in the AR System Currency Ratios form.
Page 2564 of 4705
Home
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.
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, BMC
Remedy AR System uses the value in the Conversion Date field.
BMC Remedy AR System does not automatically update records in the AR System Currency
Ratios form. However, you can use BMC Remedy AR System server 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
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 the mid tier.
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:
Page 2565 of 4705
2.
Home
Field
Contents
Conversion Date
$TIMESTAMP$
From Currency
USD
To Currency
EUR
Conversion Ratio
0.640
Then create a second entry for converting from EUR to USD:

Field
Contents
Conversion Date
$TIMESTAMP$
From Currency
EUR
To Currency
USD
Conversion Ratio
1.562
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.
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 field's functional
currencies are EUR and JPY, 7.00 USD is converted into the corresponding EUR and JPY
values (see Currency exchange ratios). Applications can use these preconverted values,
which are stored with the field, to search, report, and run qualifications without spending
Page 2566 of 4705
Home
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.
Workflow considerations for currency fields

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 Specifying arguments that use a comma as a
decimal separator.
Because the currency field is a complex type, it has special rules for conversion to and from other
data types.
Conversion from currency
Target data type
Data conversion rule
Character or Diary
The decimal value, with the currency code to the right.
Decimal, Real, or Integer
The decimal value only, dropping the fraction as necessary.
Date/Time, Date, or Time
The decimal value converts to a long date value.
Selection
The decimal value converts to an integer value.
Conversion to currency
Source data
Data conversion rule
type
Character or
Parses the string to get a number and symbol. If the currency code is valid, the following rules are applied:
Diary
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.
Page 2567 of 4705
Home
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.
Selection fields
Selection fields provide users a small number of choices. Selection fields are displayed as one of
these types:
Drop-Down List Users can select from a list of items.
Radio Button Users can select only one item.
Check Box Users can define multiple items. But, check box for only first value is
displayed.
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. BMC Remedy 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:
Example IDs
Selection item
Custom ID
Open
10
In Development
20
In QA
35
Closed
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.
If BMC Remedy 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:
Page 2568 of 4705
Home
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.
Creating selection fields

Use these procedures to create selection fields.
Note
For an overview of selection fields, see Selection fields.
To create a selection field

2. Right-click the form, and select Create a New Field > selectionField.
Selection field types are Drop-Down List, Radio Button, or Check Box.
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.
Page 2569 of 4705
Home
5. Set the other field properties as needed.

See Field properties
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. BMC
Remedy 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.
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 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.
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.
To modify selection items

1.
Page 2570 of 4705
Home

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.
To delete selection items

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.
5. Click OK.
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.
Creating data fields

Use this procedure to create all data fields except currency and selection fields, which are
discussed in Creating currency fields and Creating selection fields.
Page 2571 of 4705
Home
Note
For an overview of data fields, see Data fields.
To create a data field

2. Right-click the form, and select Create a New Field > dataFieldType.
4. In the Properties tab, set the field properties as needed.
5. To add a file system browser to a character field, see Adding a file system browser to
character fields.
6. To add effects such as highlighting to fields, see Adding field effects.
Adding a file system browser to character fields
Adding rich-text-formatting capabilities to a character field
Enabling dynamic resizing of RTF fields
Allowing users to add an image to a character field
Adding field effects
Generating a URL in an RTF field using a workflow
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.
Page 2572 of 4705
Home
2. Right-click the form, and select Create a New Field > Character.
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 field's Expand Box property is disabled, and the expand box button is hidden.
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.
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.
Note
You can modify rich text formatting (RTF) properties for the character fields at run-time by
using a workflow. For more information, see Change Field action.
The following figure shows the RTF dialog box that appears when a user clicks the RTF icon (
) next to the field.
Editing a character field with rich text formatting
Note
Page 2573 of 4705
Home
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 Editing fields with rich text formatting .
For information about using the STRIPHTML function in workflow to remove RTF formatting, see
Functions.
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 Text Allows users to click the RTF icon (
separate dialog box
) and make RTF changes in a
Rich Text In Place Allows users to make RTF changes within the field, which
includes a toolbar with a smaller subset of the commands found on the dialog box.
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 with flow layout. To avoid the horizontal and vertical
scroll bars on the RTF field, set the display property Custom CSS to RTFPanel.
Page 2574 of 4705
Home
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 (horizontally, vertically, or both) of RTF fields

1. Create a panel that will contain the RTF fields.
For more information, see the Creating panels and Creating panel holders sections.
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 panel's
Layout Style property.
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
Page 2575 of 4705
Home
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 .
5. Set the following properties for each RTF field within a panel:
Set Auto Resize to Vertical, or Horizontal, or Both, depending on the content
expected in the RTF field. Selecting Both is recommended as this option displays the
vertical and horizontal scroll bars on the panel.
If you set the RTF field to grow Vertically, the field does not show vertical scroll bars.
Similarly, for the Horizontal scroll bars. If you select Horizontal or Both, set the
Custom CSS property to RTFPanel.
Set Maximum Height to 0 (no limit) or to a number that is equal to or greater than the
field's Height property.
Note
While editing contents of the RTF field, scroll bars appear on the RTF field if
the contents of the field exceed the maximum limits specified in the display
properties.
Scroll bars might appear while editing the contents of the RTF field. These scroll bars
disappear when you tab-out of the RTF field. When a large image or text inside the
RTF field is removed, the scroll bars on the panel disappear and the RTF field and its
contents resize to the dimensions specified in the display properties.
Important
For the RTF fields to grow horizontally and vertically, set the Custom CSS
display property to RTFPanel.
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.
Page 2576 of 4705
Home
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.
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, select 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 .
For information about setting up the RTF field to hold large images, see Enabling
dynamic resizing of RTF fields.
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 BMC Remedy AR System server can serve as visual cues to specific system
actions.
Page 2577 of 4705
Home
Generating a URL in an RTF field using a workflow

You can create a workflow that generates the URL, which is then applied to an RTF field. The
external link option on the Link Options dialog box triggers the active link associated with it to
generate the actual URL. For information about how to trigger the active link, see Inserting and
removing URL links in the RTF fields .
To define a workflow to generate an external URL

1. Create a form or use an existing form, and add an RTF field and a button field on the form.
For example, you can create a form with the following objects in BMC Remedy Developer
Studio.
A regular character field to enter an URL.
An RTF field to copy the URL from the regular character field using a workflow.
A button to trigger the workflow.
2. Select the button and in the Properties window, set the Visible property to False.
Note
You can also set to use the label of the button as the label for the external links.
3. Select the RTF field, in the Properties window, select the External URL Button
property and click the ellipses button.
4. In the Field Selector dialog box, select the button field to link it to the RTF field. For more
information, see Selecting a field with the Field Selector dialog box .
5. Save the form.
6. Create an active link associated to the form that uses the Button/Menu Field execution
option and specify the button field.
7. Define the required workflow actions needed to generate the URL string. Note that the last
action must be a Set Field action to set the generated URL from the character field to the
RTF field. Using the Set Field action, set the contents from the character field to the RTF
field
Verifying the workflow

You can verify the defined workflow using BMC Remedy Mid Tier.
To verify the workflow for inserting an external URL
1. Open the form in BMC Remedy Mid Tier.

2. Enter an external URL in the character field. You can specify the URL in the following
formats:
www.bmc.com
http://www.bmc.com
Page 2578 of 4705
2.
Home
<a href ="http://www.bmc.com">

https://www.bmc.com.
Note
To open the Hypertext Transfer Protocol (HTTP) links, you can specify the
URL without using the http:// string. However, to open a Hypertext Transfer
Protocol Secure (https) links, you must specify the complete address. For
example, https://www.bmc.com.
3. Open the RTF Editor.

4. Select the text to add a link to the external link.
5. Click the
option to open the Link Options dialog box.
6. Click the
option next to the Link URL field.
This triggers the workflow associated with the RTF field to generate a URL and inserts the
URL in the Link URL field. See also, Inserting and removing URL links in the RTF fields .
Note
If the workflow was constructed properly, then the URL generated by the workflow
will be set in the URL Link Options Dialog.

8. Click OK to close the RTF Editor.
9. If you click on the selected text in the RTF display mode, the specified URL opens.
Generating URLS that link to the form Data

The RTF fields can generate a URL dynamically in the display mode based on AR System defined
attributes provided in the HTML tag. The dynamic URL enables users to link to a specific entry or a
set of entries on the AR System server.
Perform the following steps to generate a dynamic URL:
1. Open the form that you created in BMC Remedy Mid Tier. See #To define a workflow to
generate an external URL.
2. Click the expand box next to the character field to open a dialog box.
3. Enter an HTML tag using the following format to generate a URL.
<a href ="" arschema="form_name"arqual="qualification" arserver="
servername"
For example, <a href ="" arschema="User" arqual="RequestID=1"
Page 2579 of 4705
Home
Note
You cannot use the special characters such as ', ", < and > in the value of an
HTML attribute and so qualifications need special considerations and must be
replaced with the HTML character codes (such as, "). To link to a form that
opens with a range of entries matching the qualification. For example, to open all
entries with RequestID is less than 100. So, you have to use special HTML
characters.
The following table lists the attributes that you can use in the HTML tag to generate a URL
for a specific entry.
Attribute
Description
href
Source URL. For dynamic URL, you must add this attribute with an empty string. For example href =""
arschema
(Optional) Form name. To link to an entry on the current form, you can ignore this attribute and the current
form is assumed.
arserver
(Optional) Server name. To link to an entry on the current server, you can ignore this attribute and the
current server is assumed.
arentryid
Entry ID or request ID of the entry on the server.

Note: If you use arentryid attribute in the tag, you cannot use the arqual attribute.
arqual
The qualification to open a specific entry or entries on the form. The form opens in the Search mode with
the matching entries in the list. Note: If you use arqual in the tag, you cannot use the arentryid
attribute.
arvui
(Optional) View name. If you do not specify this option, the form opens in the default view.
arattID
(Optional) Attachment ID. This opens an attachment embedded to a specific attachment field ID on the
specific form.
4. Click OK.
5. Open the RTF Editor.
6. Select the text to add a link to the external link.
7. Click the
option to open the Link Options dialog box.
8. Click the
option next to the Link URL field.
This triggers the workflow associated with the RTF field to generate a URL based on the
attribute specifications and updates the URL in the Link URL field.
10. Click OK to close the RTF Editor.
11. (Optional) Select the Open in a new window option to open an external URL on a new
window.
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:
Page 2580 of 4705
Home
Views of BMC Remedy 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 BMC
Remedy AR System forms as Inline forms. For more information, see Inline forms.
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.
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 and the following sections:
Workflow considerations for view fields
Using view fields
Creating view fields
Users print a document in a view field by performing right-click on the field and choosing Print.
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.
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 Scroll Bar) determines whether scroll bars appear at the bottom and
right side of the field.
View field with scroll bars
Page 2581 of 4705
Home
In a browser, you cannot print the contents of a view field.
Creating view fields

Use this procedure to create a view field.
Note
For an overview of view fields, see View fields.
To create a view field

2. Right-click the form, and select Create a New Field > View.
The new view field appears on the form.
4. In the Properties tab, select the Text property, and click its ellipsis button.
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
company's 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
Page 2582 of 4705
Home
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.
In 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.
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.
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 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 field's bottom and right side
in a browser.
7. Set the other field properties as needed. See Field Properties.
8. Select the view field, drag it to a position in the form, and adjust its size.
9. (Optional) Use a trim text field to add a label (view fields do not have labels).
Creating fields that are not in form view

You can use the form editor to create the fields that do not appear in any view.
To create a "not in form view" field using the form editor

1. Right-click on the form editor and select Create a New Field.
2. From the sub-menu, select the in No View option to open the list of field types.
3. Select a field type that you want to create.
Page 2583 of 4705
3.
Home
Note
When you use the form editor to create a not in form view field, the Outline tab
appears automatically with the Show Fields Not in View option selected. The new
field is selected in the field list of the Outline tab.
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.
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.
Note
Web reports do not support attachment pools or attachment fields.
For more information, see Creating attachment pools and the following sections:
Workflow considerations for attachment pools
Attachment field size considerations
Creating attachment pools
Viewing attachments in a browser
Workflow considerations for attachment pools

Attachment pool and attachment field database names can be used as field references in workflow
(see Name field). 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.
Workflow actions for attachments
Action
Description
Page 2584 of 4705
Home
Change Field active link
Shows or hides an attachment pool, and sets focus to it.
Message
Displays the name of an attached file in a message.
Set Fields and Push
Transfers attachment data from one attachment field to another attachment field. You can also use
Fields
Set Fields to display an attachment in a view field.
Set Fields and Run

Process active link
Adds, saves, opens, or deletes attachments. The following 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 Defining workflow to automate processes.
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 field's 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 Db-Max-Text-Size.
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 database-specific memory error, check the data or log (or
transaction) space.
Creating attachment pools

Use these procedures to create an attachment pool.
Note
Page 2585 of 4705
Home
For an overview of attachment pools, see Attachment pools.
To create an attachment pool

2. Right-click the form, and select Create a New Field > Attachment Pool .
The new attachment pool field appears on the form.
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.
d. In the Properties tab, enter these values:
Audit Log Key See Field Properties.
Audit Option See Field Properties.
Label Can have up to 80 characters. It is used as the display label and
database name for the attachment field. See Field Properties.
Max Size Specifies 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.
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 .
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
c. Repeat steps a through b for each attachment field.
6. (Optional) Specify column headings and button (mid tier) labels for the attachment pool:
a. Select the attachment pool.
b.
Page 2586 of 4705
6.
Home
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
Default
property
value
Description
Add
Label
Add
Label on button or context menu used for adding attachments.
Attach
Name
Attach
Name
Label on column displaying attachment field labels.
Delete
Label
Delete
Label on button or context menu used for deleting selected attachments.
Deselect
Label
Deselect
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 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
Name
Label on column containing attached file names.
File Size
Label
Max
Size
Label on column containing attached file sizes.
Save
Label
Save to
Disk
Label on button or context menu used for saving selected attachments on the client.
Label
7. Set other field properties as needed.

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.

Page 2587 of 4705
Home
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.
To delete an attachment field from an attachment pool

1. Right-click the attachment field, and select Delete.
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.
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.
Page 2588 of 4705
Home
Button fields
Button fields are control fields used to execute active links. BMC Remedy AR System supports
Regular and Flat button fields.
Regular buttons have borders and background and might or might not contain images.
These buttons are used on forms that require a user to perform an action. For example:
Buttons associated with an edit field, such as a calendar pop-up button, a menu
drop-down button, or a rich text editor
Buttons inside pop-up menus
Buttons inside tables, including attachment pools, status history, and alert lists
Buttons inside table columns
Flat buttons do not have borders or background, but they do contain images. These buttons
are used in toolbars and other places that require an icon to act as a button. These buttons
can also be used for images that do not act as a button (for example, a logo on a page).
BMC Remedy AR System provides built-in styles for buttons and the capability for
applications to specify multiple images for a button and change the appearance of buttons
depending on the states. The button states are as follows:
Default
Mouse over
On click
Disabled
Read only
The appearance of Flat buttons changes based on the values set for the following
properties in BMC Remedy Developer Studio.
When the Display as Flat Image property value is set to True for a Button field, a new
property named Mouseover Effect is available with the following values -- None,
Pointer Cursor, and Button.
The Flat button style depends on the value set for the Mouseover Effect property.
If the property is set to Pointer Cursor or Button, the cursor changes to pointer
style when you click or hover the mouse on the button.
If the property is set to None, the cursor remains in default style when you click or
hover the mouse on the button.
A property named Disabled Image has been added to store the images for the disabled
state of the button.
If an image is not specified for the Disabled Image property, the image specified for the
image property will continue to be used for the disabled state, but it will be greyed-out.
Buttons look different in the mouse-over and on-click states.
Following are the appearance changes that occur on the button field for different user
actions.
Page 2589 of 4705
Home
Change with a
user action
Regular button
appearance change?
Flat button appearance change?
Cursor change
on mouse-over
Yes Pointer style
Yes Pointer style when the Mouseover Effect property value is set to
Style change
on mouse-over
Yes
Style change
Yes
Pointer Cursor or Button. Otherwise, default style.
value is set to Button.
on click
Style change
when disabled
Button background appears only when the Mouseover Effect property
Button background appears only when the Mouseover Effect property

value is set to Button.
Yes Default style with

arrow cursor Dimmed
Yes Default style with arrow cursor Dimmed
Note
The button appearance changes are applied to all system-level components, such as
dialog boxes, and to all complex components in BMC Remedy AR System, such as tables
.
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. (To add a real URL
that links to a web page, see Adding a URL to a trim text field .)
Adding images to buttons
Creating button fields
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
Page 2590 of 4705
Home
To support the Image Reference functionality for button fields, BMC Remedy AR System
clients and supporting applications such as 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 earlier 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, dimmed, 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 select .bmp, .jpeg, .jpg, .gif, and .png files. The selected 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 Image The 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 Reference A 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 BMC Remedy AR
System server. 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 Working with images.
e. Click OK.
4. Select the button, and set the following properties in the Properties tab:
Alternative Text Provides 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.
Page 2591 of 4705
Home
Display as Flat Image Displays 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 Position Sets 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 Fit Scales 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 Ratio Retains the proportions of the 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.
Creating button fields

Use this procedure to create a button field.
Note
For an overview of button fields, see Button fields.
To create a button field

2. Right-click the form, and select Create a New Field > Button.
The new button appears on the form.
3. Select the button.
4. In the Properties tab, set these properties:
Button Label The text displayed on the button.
Display Type Select one of these button styles:
Button The button looks like a button. Users can click it to initiate active link
actions.
Menu The button field is added to the menu bar. For more information, see
Using buttons and menu bar items to execute active links .
Page 2592 of 4705
Home
URL The 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 property's drop-down list, select Custom.
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.
Trim fields
Trim fields are horizontal and vertical lines, boxes, and text (including URLs) that enable you to
modify the appearance of a form.
Trim lines, boxes, and text
Each piece of trim is treated as a field by BMC Remedy 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.
Page 2593 of 4705
Home
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.
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.
To create trim fields

2. Right-click the form, and select 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 .
5. (Trim text) Set these properties:
Text Align Specifies where text is positioned relative to the top and bottom edges
of the text box: Top, Middle (default), or Bottom.
Text Style Specifies a font type for the text field.
Note
Users can change the font family, style, and size of each font type by using
the 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: 0 0 (default), 90 0, or 270 0 degrees.
Page 2594 of 4705
Home
Note
Users must modify the size of the trim text field according to the length of the
rotated text
6. Set the remaining 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 (select 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.
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 a browser, the target opens in a new window.
To add a URL to a trim text field

2. Create a trim text field (see To create trim fields).
3. Select the trim text field.
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.
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://
Page 2595 of 4705
Home
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.
For more information about adding URLs to a form, see URLs for forms and applications.
Application list fields

Application list fields display a list of entry points. BMC Remedy AR System server 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 the following figure
). A form can have only one application list field.
Application list field in sample home page
Page 2596 of 4705
Home
For more information, see these sections:

Creating application list fields
Displaying a subset of a server's applications and entry points

To display only a subset of a server's applications and entry points in an application list field, you
can create sophisticated workflow by using the reserved character field ID 1576 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.
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.
To create an application list field

2. Right-click the form, and select Create a New Field > Application List.
The new application list field appears on the form.
4. In the Properties tab, set the field properties as needed.

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 BMC Remedy AR System forms.
To learn how to create a data visualization field on a form, see Creating data visualization fields.
For more information about developing modules for data visualization fields, see Embedding web
content in an application through data visualization fields .
Page 2597 of 4705
Home
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.
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.
Workflow considerations for navigation fields

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.
For more information about navigation fields, see the following topics:
Creating navigation fields
Page 2598 of 4705
Home
Setting navigation field color options

Navigation field display and color properties
Displaying menus for navigation fields
Applying flyout mode to navigation fields
Expanding and collapsing items in the navigation bar
Creating navigation fields

Use this procedure to create a horizontal or vertical navigation field. For an overview of navigation
fields, see Navigation fields.
To create a navigation field

1. Open the form to which you want to add a navigation field.
2. Right-click the form, and select Create a New Field > Horizontal Navigation or Create a
New Field > Vertical Navigation.
3. Right-click the navigation field and select 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 (select 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 select 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.
f.
Page 2599 of 4705
Home
f. Repeat steps b through e for each menu item.

g. Click Close.
For information about creating workflow, see Defining workflow to automate
processes.
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 item Select an option to specify if workflow is
fired again:
Do not fire workflow Workflow does not fire when the selected navigation
item is clicked again.
Fire workflow Workflow fires again when the selected navigation item is
clicked again.
Navigation Initial State If you want a particular menu item selected when the user
opens the form, select that item.
Select item on click To 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.
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 a browser if the field is not
large enough.
15. (Optional) To change the styling of menus in forms in a browser, create properties in the
application's cascading style sheet (CSS).
For more information, see BMC Remedy AR System installed forms .
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
Page 2600 of 4705
Home
items. The following figure shows the difference in colors between panel headers and navigation
field items.
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
The following figure shows a navigation field and a panel with the same color and text display
attributes.
Navigation field and panel with same color and display attributes
Each object has these properties:
Page 2601 of 4705
Home
Navigation field
Panel
Top level background

color: Maroon
Header background: Maroon
Sub level background

color: Gray
Background color: Gray
Label font: Header
Label font: Header Text (III)
Text (III)
Navigation item height
: 20
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 field's 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:
Color Top level text color, sub level text color
Display Top level background color, sub level background color, item height.
For more information about display properties, see Field Properties.
Navigation field display and color properties

Navigation fields include the following display and color properties:
Top level text color The text color of the top level of the menu
Sub level text color The text color of the menu items
Top level background color The background color (and gradient, if selected) of the menu
label
Sub level background color The background color of the area where menu items are
listed
Item height--The height of the navigation item in the navigating bar
Note
Sub level items do not support gradients.
Item height The amount of line spacing, between 20 and 50 pixels, between items in the
menu. The default is 25 pixels.
Label font The font of the menu label and menu items.
Note
Page 2602 of 4705
Home
This selection applies the chosen font to all items. You cannot select one font for the
menu labels and another for the menu items.
Displaying menus for 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.
Applying flyout mode to navigation fields

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.
Configure vertical field menu items to display them 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 the following figure, can help you
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.
Flyout navigation menu display

Page 2603 of 4705
Home
Use the Mode property in Developer Studio 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. (See Expanding and
collapsing items in the navigation bar.)
Flyout Menu 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).
Expanding and collapsing items in the navigation bar

When you open a form with a vertical navigation bar field with traditional navigation bar items, all
the items are initially collapsed. You can expand or collapse all the items of the navigation bar field
simultaneously, that is, you do not have to click all the nodes individually to search for the required
node.
Note
This feature is supported for traditional navigation bar items only.
For this, a new parameter, PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM, has been

introduced with the following syntax:
PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM FieldID state
where,
FieldID is the field ID of the navigation bar or the navigation bar item.
Page 2604 of 4705
Home
state (optional) for preserving backward compatibility. It's values can be one of the
following:
0 Collapse all items recursively
1 Expand all items recursively
2 Collapse single level
3 Expand single level
Use Case 1-Expanding all items in the navigation bar field recursively
To expand all the items in the navigation bar field, execute the following command by providing the
vertical navigation bar field ID:
PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM 536870978 1
Use Case 2-Expanding an item in the navigation bar field at a single level
To expand only a single item in the navigation bar field (non-recursively), execute the following
command by providing the vertical navigation bar field ID:
If you specify a navigation bar field ID (as given in the following command), instead of the vertical
navigation bar field ID, the first level in the navigation bar will be expanded.
Use Case 3-Selecting a navigation item with highlight

To select a navigation item with highlight, execute the following command by providing a leaf node
with no options:
PERFORM-ACTION-NAV-FIELD-SET-SELECTED-ITEM 536870980
Creating global fields

Global fields are display-only fields. BMC Remedy AR System server has two types of global fields:
Regular global fields Share data across multiple windows and forms. See Creating
regular global fields.
Window-scoped global fields Share data across multiple records in the same window.
See Creating window-scoped global fields.
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 and To create a window-scoped global field).
The following types of fields can be global fields:
Character
Page 2605 of 4705
Home
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 select Edit > Clear All or Edit > Set to Defaults .
For more information about display-only fields, see the description of Entry Mode under Field
Properties.
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.
Creating regular global fields

Use regular global fields to share data across multiple forms. 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
user's 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.
3. In the Properties tab, set the field's database ID to a value from 1000000 through 1999999.
See ID.
4. Copy the global field to multiple forms.
Make sure that each copy of the global field uses the same field ID number.
Creating 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.
Page 2606 of 4705
Home
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.
3. In the Properties tab, set the field's database ID to a value from 3000000 through 3999999.
For more information, see ID.
Executing entry points in HTML

To execute an entry point in a form, add a view field with custom HTML that uses the arInvoke
Object commands to execute entry points in a browser:

arInvokeEntryPoint ("windowID","serverName","guideName") Executes the
specified entry point guide as long as the application list field (ID 1575) is also available and
visible on the same form that contains the view field.
arInvokeGuide ("windowID","serverName","guideName") Executes the
specified guide.
arInvokeForm ("windowID","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.
2. Select the view field.
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)
Page 2607 of 4705
Home
arInvokeForm(getCurrentWindowID_NS(), server, form, mode);

else
parent.arInvokeForm(parent.getCurrentWindowID_NS(), server, form, mode);
}
function doInvokeEntryPoint(server, guideName) {
if("external" in window && "arInvokeEntryPoint" in window.external)
arInvokeEntryPoint(getCurrentWindowID_NS(), server, guideName);
else
parent.arInvokeEntryPoint(parent.getCurrentWindowID_NS(), server, guideName
);
}
function doInvokeGuide(server, guideName) {
if("external" in window && "arInvokeGuide" in window.external)
arInvokeGuide(getCurrentWindowID_NS(), server, guideName);
else
parent.arInvokeGuide(parent.getCurrentWindowID_NS(), server, guideName);
}
</script>
<body>
<form>
<a href="javascript:doInvokeForm('@','HelpDesk', 'search')">Search HelpDesk form
with arInvokeForm</a> <br> <br>
<a href="javascript:doInvokeEntryPoint('ServerA','HelpDesk:EntryPointNew_ALG')">
HelpDesk form New entry with arInvokeEntryPoint</a> <br> <br>
<a href="javascript:doInvokeGuide('@','HelpDesk:Validation_ALG')">HelpDesk form
validation activelink guide with arInvokeGuide</a> <br> <br>
</form>
</body>
</html>
In this example, doInvoke Object makes sure that the arInvoke Object functions are
available. In a browser, the functions are not available in the view field because the view
field is an HTML iframe element. To access the arInvoke Object functions in a browser,
you must reference parent.
5. Click OK.
Managing fields
The following sections explain how to modify, copy, delete, disable, and find fields in a form:
Modifying fields
Copying fields
Deleting fields
Making data fields non-operational
Finding fields in a form
Finding fields by label, name, or ID
Finding fields in a list on the Outline tab
Setting tab order for fields on a form
Page 2608 of 4705
Home
Viewing and modifying tab order in the form editor

Viewing and modifying tab order using Outline view
Viewing and modifying tab order using field properties
Z-order options for form objects
Selecting z-order from the BMC Remedy Developer Studio toolbar
Selecting z-order from the Layout menu
Positioning an object in a stack
Using Outline view for objects hidden from view
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
2. Select the appropriate field.
3. In the Properties tab, modify the field properties as needed.
See Field properties.
4. If necessary, drag the field to another position in the form, and adjust its size.
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 field's 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 field's 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.
Page 2609 of 4705
Home
To copy a field
1. Open the form from which you want to copy a field.
2. Right-click the field, and select 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 select 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.
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 select Form > Add/Remove Fields On View . See Including and
excluding fields from form views.
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 Fields Creates 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 View Adds 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.
5. Select the newly pasted field.
6. In the Properties tab, modify the field properties as necessary.
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 non-operational.
To delete a field
2.
Page 2610 of 4705
Home
2. Right-click the field, and select Delete.

You cannot delete core fields . See Core fields.
3. In the confirmation box, click Yes to delete a single field, or click Yes To All to delete multiple
fields.
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 .
Making data fields non-operational

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 non-operational

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.
4. If the form has multiple views, remove the field from all form views except the current form
view.
See Views.
5. Remove the field from the current form view.
See Including and excluding fields from form views .
The field is not hidden to current users of the form until they reopen the form or log on again.
Note
You can also set permissions to make a field available to selected users only. See
Field permissions.
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.
Page 2611 of 4705
Home
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 field's label, name, or ID.
To find a field by ID, label, or name

2. If the form has multiple views, select the appropriate view.
3. Select 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 field's label, database name, or ID.
5. In the By Type section, select the option that identifies the string entered in step 4:
Label The name of the field displayed on the form.
Name The name that identifies the field in the database.
Field ID The number that identifies the field internally in BMC Remedy AR System
server.
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.
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

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 parent-child
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.
Page 2612 of 4705
Home
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 the mid tier. Specifying a tab order can help users navigate a form and
perform related actions faster and easier. The following figure shows the tab order specified for a
form.
Tab order displayed in form editor
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. Select 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. Select 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 wanted tab order. The tab order number appears as you click each
field.
To reset the default tab order

1. Select Layout > Tab Order > Set Default .
2. Respond to the prompt by clicking OK.
Page 2613 of 4705
Home
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 wanted 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 the following figure.
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 wanted 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 (the following figure).
Page 2614 of 4705
Home
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.
Z-order options for form objects

Z-order refers to the order in which overlapping objects are positioned. In BMC Remedy Developer
Studio, z-order defines the order in which multiple overlapping objects are placed on a BMC
Remedy 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 BMC Remedy Developer Studio toolbar

The Developer Studio toolbar provides four toolbar icons (the following figure) that enable
additional layering options and allow control of the z-order of fields in a form.
Z-order toolbar icons
These icons perform the following actions, from left to right:

Bring to Front Moves an object to the front of the stack, so that it appears on top of all
other objects
Bring Forward Moves an object one position forward in the stack
Send to Back Moves an object to the back of the stack, so that it is appears behind all
other objects
Send Backward Moves an object one position backward in the stack
Page 2615 of 4705
Home
Selecting z-order from the Layout menu

The four options documented in selecting z-order from the BMC Remedy Developer Studio toolbar
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 the following figure), 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.
Moving the top panel backward
If you select Send Backward, the panel is moved one position back in the stack, as shown in the
following figure.
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.
Page 2616 of 4705
Home
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.
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.
At runtime, you can change a field's 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.
The browser validates the field when a request is created.
If the field is empty and does not have a default value, 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 field's 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 Change Field
action.
Page 2617 of 4705
Home
To reset a field's 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 field's 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.
To configure a character identifier for required fields
Note
This identifier will be added to all required field labels in all forms on the BMC Remedy AR
System server.
Server Information.
3. In the Required Field Identifier area, set the following options:
Prefix on Label Select 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.
Identifier Enter 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 .
Modify a join field's change history, color, database name, display, font, and help text
properties. See To view or modify field properties in a join form .
Page 2618 of 4705
Home
Add data fields to the join form, or create display-only or trim fields. (Display-only fields can
be inherited or created on the join form.) See Adding data fields to join forms .
Remove fields from the join form. See Removing fields from join forms.
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 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.
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

2. Right-click the form, and select 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.
Page 2619 of 4705
Home
4. Drag the fields to the appropriate position in the join form.

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

You can also select and remove multiple fields.
4. In the confirmation box, click Yes to delete a single field, or click Yes To All to delete
multiple fields.
Field Properties
For each field on a form, use the Properties tab in Developer Studio to set properties that
determine how the field looks and acts during operations performed in a browser. The properties
listed in the Properties tab vary depending on the type of field you are creating or modifying.
See also Properties tab for fields in Best Practice Customization Mode .
The following tables list the field properties in alphabetical order.
Field properties (A to C)
Field properties (D to F)
Field properties (G to L)
Page 2620 of 4705
Home
Field properties (M to P)
Field properties (Q to Z)
Field properties (A to C)
Property
Active Link(
s)
Field type
Description
See To create a button field.
Button
See To create a navigation field.

Navigation
field menu
item
Add Label
See To create an attachment pool.

Attachment
pool
Add New
Panel
See To create a panel holder.

Panel
holder (all)
Alignment
Data (all)
Display (all
Specifies whether the field's horizontal position is anchored to the Left (default) or the Right
side of a form. This property is valid in the mid tier. See Anchoring fields to the right side of a
form or panel.
except
navigation
field menu
items)
Composite (
all except
table
columns
and panels
in panel
holders)
Allow Any
See Special submit setting.
User to
Submit
Attachment
Data (all)
Alternative
Text
Button
Attach
Name
Label
Attach
Orphaned
Items
Attachment
Fields
See To add an image to a button.

Attachment
pool

Navigation (
all)
Page 2621 of 4705
Home
Attachment
pool
Attachment
Pool List
Audit Log
Key
Audit
Option
See To move an attachment field from one attachment pool to another .

Attachment
See Specifying fields to be audited.

Attachment
Data (all)
Select one of these options:

Attachment
Data (all)
None -Changes to the field are not recorded by any audits.

Audit -Changes to this field trigger an audit. New values are recorded in the audit form
or log form, depending on the audit style set at the form level.
Copy -Changes to this field are recorded during an audit, but they do not trigger an
audit.
Audit and Copy -Changes to this field trigger an audit if the field is changed, but if it is
not changed, it is still copied (that is, behaves like a copy field).
See Using buttons and menu bar items to execute active links .
Auto
See To enable or disable auto-complete.
Complete
Character
Auto
Complete
Match By
Character
Auto Fit
Columns
To configure auto-complete to match by label.
See To add a table field to a form .

Alert list
Cell-based
table
List view
table
Results list
Auto
Refresh
String
Alert list
Auto
Resize
Character
Background
Color
See To customize table labels.
See Enabling dynamic resizing of RTF fields.
Specifies the background color:

Cell-based
table
Panel (all)
Trim box
Trim text

2. (Panels and trim fields) In the Properties tab, set Background Mode to Opaque.
3. Select custom from the Background Color drop-down list.
4. Select a color from the color palette, and click OK.
The selected color is displayed in the Background cell.
Background
Image
Cell-based
table
Panel (all)
For cell-based tables, specifies the background image in all cells in the table. For panels,
specifies the image that appears in the background of the panel, and whether the image is
embedded in the panel or inserted by reference.
Page 2622 of 4705
Home
Background
Image
Horizontal
Background
Image
Vertical
Cell-based
table
Panel (all)
Cell-based
table
Panel (all)
Background
Mode
For cell-based tables, specifies the position of the image in the cells from side to side. For
panels, specifies the position of the image in the panel from side to side.
For cell-based tables, specifies the position of the image in the cells from top to bottom. For
panels, specifies the position of the image in the panel from top to bottom.
Specifies whether the background is opaque or transparent. For text fields in a browser, the
Panel
opaque background is white.
holder (all)
Trim box
Trim text
Panel
holder (all)
Specifies whether the background image for the view shows through the panel holder and all
panels.
Opaque (default) Fields on the form behind the panel in the stacking order are not
visible.
Transparent In 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.
For more information about background images and colors in views, see Setting form view
properties.
Border
Specifies how borders are shown:

Application
Default The field border is displayed only when the content of the view field is a URL.
This option works with a browser.
Hide The field border is not displayed.
Show The field border is displayed.
list
Data
visualization
View
Border
Color
Color of lines surrounding the cells.

Panel (
accordion,
collapsible,
splitter)
Border
Thickness
Dimension of lines surrounding the cells. Specify in pixels. You can specify up to 9 pixels.
Panel (
accordion,
Enter 0 to have no border. To create a border with the same number of pixels on all sides,
enter one number. To create a border with varying sizes, enter the number of pixels for each
collapsible,
splitter)
side in the following order: Top, Right, Bottom, Left. Separate each entry with a comma. For
example, to create a panel with borders that are 2 pixels on the right and left and 5 pixels on
the top and bottom, enter 5,2,5,2. To create a panel with no borders on the top and bottom
and borders of 3 pixels thick on the right and left, enter 0,3,0,3.
Borderless
Panel
holder (
Specifies whether a border appears around the panel holder. The default is True (border does
not appear).
accordion,
collapsible,
splitter)
Page 2623 of 4705
Home
Button
Label
Change
History
Button
All
Checkbox
Column
CLOB
Storage
Contains information about field modifications. BMC Remedy AR System automatically

records the owner of a field, the user who last modified the field, and the date of the
modification. To display or add to this information, use the Change History properties. For
more information, see Updating change history.
See Adding a select all or cancel all check-box column to tables .
List view
table
Results list
Specifies how CLOB (character large object) data is stored:

Character
Default Use the value of the Store CLOB In-Row option on the AR System
Administration: Server Information form's Database tab. See Setting database options.
In Row
If the length of the character data, including the LOB locator, is less than or
equal to 4000 bytes, store the data "in row."
If the length of the character data, including the LOB locator, is greater than
4000 bytes, store the LOB locator "in row" and the data "out row." In-row CLOBs
can degrade CPU performance.
Out Row Store the data "out row." Out-row CLOBs can cause the database to grow
rapidly.
Note
This property applies only to Oracle databases.
Column
All (view
and vendor
forms only)
Column
Header
Color
Column
Header
Text Color
Column
Width
Specifies the name of the database table column associated with the field. This field is
read-only. For more information, see Using buttons and menu bar items to execute active links
.
Specifies the background color for the table column header.

Tables (all
except
Cell-based
tables)
Specifies the text color for the table column header.

Tables (all
except
Cell-based
tables)
See To set column properties.

Alert list
Cell-based
table
List view
table
Results list
Page 2624 of 4705
Home
Tree view
table
Content
For cell-based tables, only when table chunking is enabled.
Clipping
Display
Currency
Types
Currency
Custom
CSS Style
All
Custom
Properties
Data
See To add a currency field to a form .
Specifies a custom CSS style for the field. For more information, see BMC Remedy AR
System installed forms.
For more information, see Data visualization fields.
visualization
Field properties (D to F)
Property
Field type
Data Font
Data (all)
Description
Specifies a font type for the data that users enter into the field. To change the data font, select
any one of the following font types from the drop-down list:
Edit Field Defines the font for data in fields. Default font: MS Sans Serif 8.
Optional Field Defines the font for tabs in page fields and for labels of optional fields.
Default font: MS Sans Serif 8.
Push Button Defines the font for buttons. Default font: MS Sans Serif 8.
System Field Defines the font for field labels set by BMC Remedy AR System. Default
font: MS Sans Serif Italic 8.
Radio Button Defines the font for radio (option) buttons. Default font: MS Sans Serif 8.
Required Field Defines the font for labels of required fields. Default font: MS Sans
Serif Bold 8.
Header Text I Defines the font in text trim for titles. Default font: MS Sans Serif Bold
12.
Header Text II Defines the font in text trim for headers. Default font: MS Sans Serif
Bold Italic 10.
Header Text III Defines an alternative font in text trim for headers. Default font: MS
Sans Serif Bold 10.
Note Text Defines the font in text trim for labels. Default font: MS Sans Serif 8.
Detail Text Defines the font in text trim for details. Default font: Arial Serif 7.
Data
Length
Data (all)
Specifies the width of the field's data entry region in pixels. This often differs from the maximum
length for data entered in the field (see "Input Length" in this section). If users enter more
characters than can be displayed, the text scrolls off the end of the field, provided the internal
field length can accommodate the input.
Data Type
All
Default
Value
Character
Specifies the type of information that the field is designed to contain, for example, character or
trim. This property is read-only. See Creating and managing fields.
Specifies the value that appears in the field when users initially open the form to perform a
search or to submit a new request in the mid tier. Default values can improve application
usability. For example, creating a default value as a prompt in a required field ("Enter your
name here") informs users what information must be entered in the field. You can use
keywords to define a default value. Keyword values that are unlikely to change, such as $
Page 2625 of 4705
Home
USER$, expand to a value when defaults are first set. Other keywords (such as $TIME$ )
expand to a value as late as possible when defaults are loaded. For more information, see
Keywords. To add a default value, select the Default Value property, click its ellipsis button,
enter the default value, and click OK.
Date
Date/Time
Decimal
Diary
Specifies the value that appears in the field whenever users load default values before
performing a search or submitting a new request. (Date and time fields) This value can be a
static value or one of these keywords: $TIME$, $DATE$, or $TIMESTAMP$. (Diary fields) You
can use keywords. For more information, see Keywords. To add a default value, select the
Default Value property, click its ellipsis button, enter the default value, and click OK.
Integer
Real
Time

Currency
Definition
Name
Delete
Button
Data
visualization
Specifies the definition name for the data visualization module. For more information, see Data
visualization fields.

Alert list
Results list
Delete
Label
Attachment
pool
Depth
Effect
Horizontal
For a box or line, specifies the appearance of depth:
None
Raised
Sunken
Etched (default)
line
Trim box
Vertical line
For examples, see Trim lines, boxes, and text.

Deselect
All

Alert list
Cell-based
table
List view
table
Results list
Deselect
Label
Disable
Change
Flag

Attachment
pool
Data (all)
Application
list
Attachment
Data
visualization
Specifies whether the change flag ("dirty bit") is affected by the field you are creating. When
this property is set to True, the field does not affect the change field status of the form. This can
be helpful when you have calculations that use hidden fields. See GET-CHANGE-FLAG and
SET-CHANGE-FLAG in Process commands.
Note
Page 2626 of 4705
Home
View
Any field not in the user's current view does not affect the change flag, even if the
Disable Change Flag property is set to False. You can associate a
SET-CHANGE-FLAG Run Process action with a field not in the view to set the change
flag as needed. See Including and excluding fields from form views and information
about special run processes and $PROCESS$ in Process commands.
Display as
Flat
Image
Display
As Text

Button
Character
Data (all)
Date/Time
Diary
Display
Label
When set to True, displays the contents of the field as plain text without a border or background
. You might want to set a default value for the field (see "Default Value" in this section).
When set to True for a character field, the text area is Read Only, and should not be editable
by changing Field Access to Read/Write from Read Only. In other words, when set to True,
Field Access has no impact on the text area of the data field. Character, date/time, and diary
fields are editable using an expand box.
Attachment
pool
Display
NULL
value As
Tree view
table
Display
Type
Button
Specifies one of these display types:

Character
Drop-Down List Users can select a value from a drop-down list. Values available in
the list are from a menu attached to the character field. This option is available only if the
character field has a menu attached to it. This option is different from the drop-down list
for a selection field although they look similar. In non-Search modes, such as New and
Modify, users can select a value from the list but cannot type directly in the field. In
Search mode, users can either select a value from the list or type directly in the field.
Users can also enter partial list values, such as "Business" instead of "Business
Services," to find all requests whose value in the field includes the word "Business."
Edit Users can type values directly into the field.
Edit Masked Users can type values directly into the field, but the values are displayed
as asterisks. This display type offers no special security. For example, the values are not
stored in the database as encrypted values. Edit masked values are exported, imported
and transmitted from client to server in clear text.
File Users can browse network file systems for a file path, which is added to the
character field. See Adding a file system browser to character fields .
Rich Text Users can make rich-text-formatting (RTF) changes in a dialog box after
they click the RTF icon next to the field.
Rich Text In Place Users can make RTF changes within the character field, or they
can click the RTF icon and make RTF changes in a separate dialog box that contains
more RTF options. For more information, see Adding rich-text-formatting capabilities to a
character field.

Date/Time
Page 2627 of 4705
Home
Date/Time Users can click a calendar to enter dates and times into the field. Users
can also directly edit dates and times.
Date Users can click a calendar to enter dates into the field. Users can also directly
edit dates.
Time Users can click increment and decrement arrows (q and p) to enter times into
the field. Users can also directly edit times.
Date
Time
Specifies this display type:* Edit Users can type values directly into the field.
Diary
Display
Type (
continued)

Integer
Edit Users can type values directly into the field.

Numeric Spinner (For Internet Explorer browsers only.) Users can click increment and
decrement arrows (q and p) to increase or decrease the number in a field. Users can
also directly edit numbers.
Horizontal Nav Bar The field is a horizontal navigation field.

Vertical Nav Bar The field is a vertical navigation field.
Navigation
This property cannot be changed, so it is not possible to convert one type of navigation field to
the other.
Panel
holder
Tabbed One panel is displayed at a time. Multiple panels are indicated by tabs.
Collapsible (Stacked) Multiple panels are displayed either horizontally or vertically.
Splitter Multiple panels are displayed either horizontally or a vertically. A splitter
control can be dragged to change the size of adjacent panels.
Accordion One panel is displayed at a time; only headers of the remaining panels
appear. When the header of another panel is selected, that panel is opened to display its
contents.

Selection
Drop-Down List Users can select from a list of choices.

Radio Button Users can select only one choice.
Check Box Users can select one or more items from a set of items.

Table
columns

Table fields
Draggable
Data (all)
Horizontal
Line
Vertical Line
Trim Text
Trim Box
Button
(Web only) Specifies whether a field can be dragged to another field. This property creates only
the effect of dragging. You must create workflow to copy and paste data between fields. (You
can, however, configure workflow to execute on the drag event.) For more information, see
Allowing data to be dragged and dropped.
Note
Page 2628 of 4705
Home
Tables (all,
except
If you enable dragging and dropping between two attachment pool fields, they should
each have only one attachment field because workflow cannot determine which field
Results List)
Attachment
is being dragged or dropped.
Pool
Panels (all)
Drop
Shadow
The default value of Draggable is false.
Specifies whether a panel, with rounded corners or not, or panel holder has a drop shadow. For
Panels (all)
Panel
holders
Droppable
Data (all)
Horizontal
more information, see Drop shadows in panels and panel holders . For floating panels and
panel holders, the default value of Drop Shadow is True. For non-floating panels and panel
holders, the default value is False.
(Web only) Specifies whether a field is highlighted when a user drags a field. For more
information, see Allowing data to be dragged and dropped. This property allows the field to
accept drop events that occur as a result of a user dragging a field and dropping on it.
Line
Vertical Line
Trim Text
Trim Box
Note
If you enable dragging and dropping between two attachment pool fields, they should
each have only one attachment field because workflow cannot determine which field
is being dragged or dropped.
Button
View
Data
Visualization
Tables (all,
except
The default value of Droppable is false.
Results List)
Attachment
Pool
Panels (all)
Edit Menu
/
Navigation
Items
Enable
Clear

Navigation
Specifies whether a (clear) item appears on character field drop-down lists.

Character
Always A (clear) item appears in all modes. This is the default setting.
Search Only A (clear) item appears in Search mode only.
This property is appears in the Properties tab only when a menu is attached to the character
field and the Display Type field property of the character field is set to Drop-Down List. See
Adding and removing (clear) from drop-down lists .
Enabled
Data (all)
(Web only) Specifies whether a field is highlighted when a value is changed through a Set
Fields action, and the color of the highlight. When set to True, you can specify a highlight start
color and a highlight end color. The default value is false (highlight not enabled).
End Color
Data (all)
Entry
Mode
(Web only) When the Enabled property is set to True, enables a smooth visual transition
following a system action. For best results, select a color that matches the background color of
the element on which the field resides, whether it is a panel or the form. The default color is
white. For display as text fields, the default color is the background color of the form.
Specifies one of these options (available options depend on field type):
Data (all)
Attachment
System The field is populated by BMC Remedy AR System. Certain core fields such
as Request ID and Last Modified By are system fields.
Page 2629 of 4705
Home
Required Field requires a value, default, user-entered, or from workflow, when a user
submits a request. Required fields have a bold label. A form has at least three required
fields: Submitter, Short Description, and Status. Make a field required only if it must
be filled in for every new request.
Optional Users can enter information in the field or leave it empty. If you have optional
fields that must be filled in under certain circumstances, you can create filters and active
links that force the user to fill in the field when specified conditions are met.
Display The field is used as a temporary field. No space is allocated for a display-only
field in the database, so a display-only field value can never be recorded in the database
. For this reason, display-only fields have a value of NULL when a request is retrieved.
In all other ways, a display-only field can be used in the same way as any other field (for
example, you can reference it in workflow).
You can select this option only when you create a field. After you save a form, the following
changes occur:
For a required or optional field, the Display option is no longer available.
For a display-only field, the Entry Mode property is disabled and cannot be changed. To
improve system performance, use display-only fields to store temporary values or to
perform calculations. Global fields (field IDs 1000001-2000000) must be display-only.
Expand
Box
Specifies whether an expand button that opens a dialog box appears next to the field. Users
Character
Currency
Date
Date/Time
Diary
Time
can enter data for the field into the dialog box. Values are
Default Hides the expand button for character fields if the field length is less than 70
bytes. Displays the expand button for currency, date, date/time, diary, and time fields
regardless of field length.
Hide Always hides the expand button.
Show Always displays the expand button.
The dialog box opened by the expand button depends on the type of data that can be entered
into the field. The button's icon shows the type of data:
Character icon
Currency icon
Date and Date/Time icon
Diary icon
Time icon
For character fields,
This feature enables you to conserve space on the user's view of the form by making the
field's display Data Length value smaller than its database Input Length value.
The text dialog box supports text editor commands, such as Select All and Copy, which
makes it easier to work with large amounts of data in the dialog box than directly in the
character field.
If you set the Display As Text property to True, you might want to hide the expand button.
Note
When a character field has an expand button, the field displays whole words only. To
see the text beyond the words displayed in the field, open the text dialog box.
Page 2630 of 4705
Home
Field
Access
Specifies how the field is initially displayed:

Alert list
Button
Cell-based
table
Horizontal
line
List view
table
Navigation (
all)
Results list
Tree view
table
Trim text
Trim box
Vertical line
Enabled (default) Results in an active field.

Disabled Results in an inactive (dimmed out) field.
Specifies how users initially access a field in the current view:

Data (all)
Read Only Users can read or access field information, but they cannot edit it.
Read/Write (default) Users can read, access (for example, copy), and edit field
information.
Disabled Users can read field information, but they cannot access or edit it.
Field ID
All (join
forms only)
Field
For fields on join forms, specifies the integer that identifies the field internally throughout BMC
Remedy AR System server. This field is read-only. See Working with fields in join forms.
For fields on join forms, specifies the field's database name. This field is read-only. See
Name
All (join
forms only)
File Name
Label
Attachment
Working with fields in join forms.

pool
File Size
Label
Fire
workflow
again on
selected
item
Fit to
Content

Attachment
pool

Navigation (
all)
See Using Fit to Content to dynamically resize panels .

Panel (
collapsible)
Fixed
Headers

Alert list
Cell-based
table
Page 2631 of 4705
Home
List view
table
Results list
Float
Style
See Creating floating panels.

Panel
Panel
holder
Form
Name
All (join
For fields on join forms, specifies the name of the underlying form (primary or secondary) in
which the field resides. This field is read-only. See Working with fields in join forms.
forms only)
Full Text
MFS
Category
Name
Character
Diary
Attachment
Specifies a category name for a field that is indexed for a full text search of multiple forms. (For
more information, see Setting up FTS to search across multiple forms.) At index time, the
server checks whether an entry has any fields with a category name (defined in the Full Text
MFS Category Name field property). If so, the server also indexes the field as that category
name as well.
Field properties G to L
Property
Header
Background
Color
Header
State
Field type
Description
Specifies the background color for the header in a panel.
Panel (
accordion,
collapsible,
splitter)
Specifies whether the panel header is visible or hidden. The default is Visible.
Panel (
collapsible,
splitter)
Height
Specifies the height of the field in pixels.

All
Help Text
Specifies the Help text for a field. To enter Help text, select this property, click its ellipsis
All
Horizontal
Space
button, enter text in the Help Text dialog box, and click OK. For information about creating
help text, see Providing help text.
See Horizontal Space.
Cell-based
table
ID
All
Identifies the field internally throughout BMC Remedy AR System. Every field in a form must
have an integer field ID that is unique in that form. If you leave the ID field empty or set it to
zero, BMC Remedy AR System automatically assigns a number from the unrestricted number
set. Restrictions on field ID numbers are as follows:
Numbers 1-99 are reserved for core fields. You cannot assign an ID in this range
unless you are modifying core fields. See Core fields.
Page 2632 of 4705
Home
Numbers 100-536868911 are reserved. If you use an ID in this range, you receive a
warning. Numbers 1000000-1999999 are reserved for regular global fields and
3000000-3999999 are reserved for window-scoped global fields. For information about
global fields, see Creating global fields.
Numbers 536868912-2147483647 are administrator-defined. There are no restrictions
on assigning numbers in this range. If you choose to assign field IDs instead of letting
BMC Remedy AR System do it automatically, be aware that view IDs are also drawn
from the low end of this range.
Columns in table fields and panels in panel holders also have an ID. To assign order in
workflow, you can assign the ID yourself or let BMC Remedy AR System assign the number
for you. The field ID remains constant even if the database name or display label changes.
You cannot modify the field ID after it is saved to the database. If you define fields that serve
the same purpose in more than one form, assign identical IDs to the identical fields in the
different forms. You can then write workflow once for that field (with minor edits to BMC
Remedy AR System field definition) and reuse the field in multiple forms. Reusing the ID
provides a consistent definition for the field across forms.
Image

Button
Image
Attachment
Character
See Allowing users to add an image to a character field .
Image
Position
Button
Index For
FTS
Initial
Currency
Type
If you are licensed for full text search, specifies whether to index a character, diary, or
Attachment
Character
Diary

Currency
Initial Panel
Panel
holder (
accordion)
Initial Row
Selection
attachment field for FTS.
Specifies the first panel displayed in an accordion panel holder. To select the initial panel, click
the property's Value cell, click the arrow button that appears in the cell, and select a panel
from the drop-down list.

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Initial Size
Specifies the size of the panel when it is initially created in a collapsible or splitter panel holder
Panel (
splitter,
collapsible)
Page 2633 of 4705
Home
Initial Value

Cell-based
table
List view
table
Results list
Tree view
table
Input
Length
Specifies the maximum number of bytes or characters, depending on the value of Length
Character
Units property, that the field can contain. Leaving this property empty or setting it to 0 specifies
an unlimited length. To use database storage most efficiently, set the Input Length of a
character field so that it will be created as a varchar database table row. Storage for a
varchar is allocated dynamically to the length of the actual field contents, not the input length.
See Character fields for the maximum values for varchar storage for each database. If you set
the Input Length to more than the maximum for varchar, the character field is created as a
clob database table column and storage is allocated in blocks that average between 1K to 2K
bytes (depending on the database). A full block is allocated for the first byte. When that block
is filled with the field contents, another full block is allocated. To control CLOB storage in an
Oracle database, see the description of "CLOB Storage" in this section. For more information
about database structure in BMC Remedy AR System, see the Understanding the AR System
database. Do not use more space than you need to store the intended field contents. If you
allocate more space for storage than your system needs, more space is searched during
queries. If the Expand Box property is set to Default and the field length is 70 or more bytes,
BMC Remedy AR System automatically inserts an expand button to the right of the field that
users can click to open a text dialog box. This can conserve space on the user's view of the
form by making the field's Data Length smaller than its Input Length property. The default
maximum input length for character fields is different for each of these databases:
Sybase and Microsoft SQL Server: 2 GB
DB2: 10 MB
Oracle: 4 GB
For scalability reasons, limit the number of long character fields in a form.
Note
To configure a different maximum input length for Oracle, Microsoft SQL Server, and
Sybase databases, use the Db-Max-Text-Size option in the BMC Remedy AR
System server configuration files. See ar.conf (ar.cfg).
You cannot use the Indexes form property to create an index for a long or character field with
an Input Length over 255 bytes. But if you are licensed for full text search, you can use the
Index for FTS field property to create a search index for the field. For more information about
FTS, see Enabling full text search. For some databases, you cannot search fields that are
over 255 bytes. See Understanding the AR System database and information in Installing old.
Label
Application
list
Attachment
Composite (
all)
Data (all)
Data
visualization
Specifies a label for the field in the current form view. You can enter a label with as many as
80 characters that describes the meaning and purpose of the field. The label can include
spaces and double-byte characters. Avoid using spaces at the beginning of field labels; such
spaces do not appear in some browsers. If you leave this property empty, the field appears on
the screen with no label. For tree view table fields, if this property has text, it becomes the root
of the tree. The label need not be unique. However, if duplicate field labels exist in a form,
BMC Remedy AR System issues a warning message every time you apply changes to the
form unless you disable the BMC Remedy Developer Studio preferences for duplicate blank
and nonblank field label warnings. You can use single quotation marks in field labels; however
Page 2634 of 4705
Home
Navigation (
all)
, when performing searches, users must enter two single quotation marks when specifying the
quotation mark in the label. This is required because field labels that contain special
View
characters must be enclosed in single quotation marks in searches, and a single quotation
mark in the label is otherwise interpreted as the end of the field label.
Label Align
Aligns labels to the top, center, or bottom of the region available for the label. The default is
Data (all)
Top for labels located to the left of the field. The default is Bottom for labels located above the
field. See Arranging fields in a form view. For text fields with one row, when this property is set
to Top, labels appear in the center in a browser. See the "Rows" description in this section.
Label Font
Specifies a font type for the field label. In a default regular form, each label style identifies a
Button
Data (all)
Panel (all)
different field behavior:
Italic Field is maintained and automatically updated by BMC Remedy AR System.

Bold Field requires a value.
Plain Field value is optional.
As the administrator, you can override the properties of the default font types, but do so
cautiously to avoid confusing users. In addition, users can use preferences to change the fonts
assigned to font types. All fields with the same type remain consistent. To change a label font:
2. In the Properties tab, select a new font type in the Label Font drop-down list.
3. In the Data Font drop-down list, select a font type for data entered into the field if
applicable.
Label
Justify
Button (
Specifies where label text is positioned relative to the left and right edges of the text box: Left,
Center, or Right.
URL style)
Data (all)
Trim text
Label
Location
Label/Text
Color
Data (all)
Button
Data (all)
Panel (all)
Trim text
Specifies where a data field's label appears in relation to the field: Top (above the field) or Left
(default).
Specifies the color of the field's label or text. For a data field, the label appears to the left of a
field or above it. For a panel field, the label appears in the panel header. Colors are set one
field at a time. To change label or text color:
2. In the Properties tab, select Custom in the Label/Text Color drop-down list.
Last
Changed
All
Specifies the user name of the last person who modified the field. This read-only field is
automatically set.
All
Specifies the date and time that the field was last modified. This read-only field is
automatically set.
By
Last
Changed
Time
Layout
Style
Cell-based
table
Panel (all)
XY Specifies that field locations in the cell or panel are set by X and Y coordinates
and sized by width and height.
Fill Specifies that fields are dynamically resized within the cell or panel.
Note
Page 2635 of 4705
Home
Flow Specifies that RTF fields are dynamically resized within the panel.
See Panel layout styles and Enabling dynamic resizing of RTF fields.
Length
Units
Character
In Regular forms, specifies whether the Input Length of a character field is calculated in Bytes
or Characters. The default is Bytes, which is the Input Length unit for all character fields in
BMC Remedy AR System server release 7.1.00 and earlier. Because character sets use
varying numbers of bytes to represent a single character, setting the Length Units property to
Characters allows better control of character field sizes in the database. When creating or
resizing a database column corresponding to a field with a Length Units value of Characters,
BMC Remedy AR System server applies a multiplier to calculate the column size for the field.
The multiplier is determined by the server character set and the database code unit. The
server uses the following multiplier values:
1 WESTERN character set.
2 UTF-8 with Microsoft SQL Server, GB2312, Big-5, EUC-CN, Shift-JIS, KSC-5601,
and EUC-KR character sets.
3 EUC-JP character set.
4 UTF-8 (except Microsoft SQL Server), EUC-TW.
For example, when you create a character field with a Length Units value of Characters and
an Input Length of 100 on a UTF-8 platform, the corresponding column is 200 nvarchar in a
Microsoft SQL Server database (multiplier value of 2), or 400 char in other databases (
multiplier value of 4).
Note
For the core fields Request ID, Submitter, Assigned To, and Last Modified By,
you can only set Length Units to Bytes. The Short Description field can use either
Bytes or Characters. For Bytes, it is limited to an Input Length of 255; for Characters
it is limited to Input Length 63.
BMC Remedy Developer Studio does not display the Length Units property if the BMC
Remedy AR System server is release 7.1.00 or earlier. To configure the default value of this
property, in BMC Remedy Developer Studio, select Window > Preferences > Form, and set
the Input Length Units value. In Display Only and Vendor forms, this property works with the
Data Length field to restrict the length of the information to display. In Join forms and View
forms, this property reflects the setting for the mapped field in the underlying form or database
table.
Line Color
Specifies the color of the line:

Horizontal
line
Panel
Trim box
2. In the Properties tab, set Depth Effect to None.
Vertical line
Literal FTS
Index
Character
Localization
Required
All
3. Select Custom in the Line Color drop-down list.
Specifies whether the FTS engine should use the literal method to search the contents of all
requests indexed for the field. For more information about FTS, see Enabling full text search.
This property is enabled when the Index For FTS property is set to True.
Page 2636 of 4705
Home
Specifies whether a field label must be translated. By default, this property is set to False.
When this property is set to True, attribute 287 in the field definition is set to 1. To ascertain
which fields 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.
Localize
Data
Localize
Label
Data (all)
Attachment
All
Specifies whether configuration data can be localized for the form. The options are True and
False (the default).
Specifies whether the field label can be localized for the form. The options are True (the
default) and False.
Field properties M to P
Property
Field type
Maintain
Aspect
Ratio
Button
Margin
Bottom
Cell-based
Description
table
Panel
holder (
accordion,
For cell-based tables, specifies the space between the bottom of the cell-based table field and
the last row of cells. Specify in points. For panel holders, specifies the amount of space
between the bottom border of the panel holder and the bottom edge of the panels in it. If the
bottom margin size is too large to allow all of the panels to be displayed, a vertical scroll bar
appears.
collapsible,
splitter)
Margin Left
Cell-based
table
Panel
holder (
accordion,
collapsible,
splitter)
Margin
Right
Cell-based
table
Panel
For cell-based tables, specifies the space between the left side of the cell-based table field
and the first column of cells. Specify in points. For panel holders, specifies the amount of
space between the left border of the panel holder and the left edge of the panels in it.
For cell-based tables, specifies the space between the right side of the cell-based table field
and the last column of cells. Specify in points. For panel holders, specifies the amount of
space between the right border of the panel holder and the right edge of the panels in it.
holder (
accordion,
collapsible,
splitter)
Margin Top
Cell-based
table
For cell-based tables, specifies the space between the top of the cell-based table field and the
first row of cells. Specify in points. For panel holders, specifies the amount of space between
the top border of the panel holder and the top edge of the panels in it. If the top margin size is
too large to allow all of the panels to be displayed, a vertical scroll bar appears.
Page 2637 of 4705
Home
Panel
holder (
accordion,
collapsible,
splitter)
Max Rows

Alert list
List view
table
Cell-based
table
Results list
Tree view
table
Max Size

Attachment
Maximum
Integer
Specifies the highest integer value that users can enter in the field during data submission and
modification. By default, integer fields accept integer values between -2147483647 and
2147483647.
Currency
Decimal
Real
Maximum
Height
Maximum
Size
Menu
Name
Specifies the highest value that the field can have during data submission and modification.
This setting is required.

Character
Specifies the maximum size allowed for a panel in a splitter panel holder.
Panel (
splitter)
Character
Attaches a character menu to a character field and inserts a menu button to the right of the
field. Character menus provide users with a fill-in aid that can help standardize the text
contents and thereby improve the accuracy of searches. Unless you specify a pattern match (
see the description of "Pattern" in this section) or change the display type to Drop-Down List (
see the description of "Display type" in this section), users can enter their own text even when
a character menu is attached to the field. To attach a menu, select it in the property's
drop-down list. The $NULL$ option allocates space for the menu button, but hides the button
in the user's client. When you use the Change Field action to associate a menu, the menu
button appears without disrupting form layout. See Using buttons and menu bar items to
execute active links. For information about designing and creating a character menu, see
Creating character menus.
Menu Style
Character
Specifies how menu text is added to the field when users selects an item from a character
menu:
Append Text is added to any text already in the field. If text is in the field, a blank
space is inserted before the menu text value is appended.
Overwrite Text replaces any text already in the field.
Minimum
Integer
Page 2638 of 4705
Home
Specifies the lowest integer value that users can enter in the field during data submission and
modification. By default, integer fields accept integer values between -2147483647 and
2147483647.
Currency
Decimal
Specifies the lowest value that the field can have during data submission and modification.
This setting is required.
Real
Minimum
Size
Specifies the minimum size allowed for a panel in a splitter panel holder.
Panel (
splitter)
Mode
Application
list
Specifies whether the entry points in an application list field are presented as a traditional list,
or with the appearance of a vertical navigation bar:
Traditional The application list appears in the traditional AR System Home Page
format, with entry points displayed as links.
Flyout The application list looks like a vertical navigation bar, and entry points are
displayed as flyout options. See Navigation fields.
Module
Type
Data
visualization
Name
All
Specifies the module type for the data visualization field: flashboard, report, or visualizer. See
Data visualization fieldsUsing buttons and menu bar items to execute active links#89961 .
Identifies the field in the database. Every field in a form must have an alphanumeric field
name that is unique in that form. Names can have up to 80 characters, including spaces. They
can include double-byte characters, but avoid using numbers at the beginning of a name. If
you leave this property empty, BMC Remedy Developer Studio generates a name based on
the field type and appends a number to the name to make it unique. For example, if the form
has a field named Column1, BMC Remedy Developer Studio names the next field of the same
type Column2. Do not use the keyword FUNCTION as a field name; if you do, the system
generates an error, and the underlying database view is not created.
Note
If you create a field with a dollar sign ($) or an apostrophe (') in the database name,
you must double the dollar sign or the apostrophe when using the field in workflow in
addition to adding the surrounding characters. For example, a field named
MyMoney$ must be entered in workflow as $MyMoney$$$, and a field named
John's Money must be 'John''s Money'.
The field name is easier to use than the field ID when you create workflow such as active links
and filters. Unlike the field label, the field name is not specific to a view of the form. Do not
confuse the field Name with the field Label, especially when creating workflow. To avoid
naming conflicts with the database server, do not use a word reserved by the database server
software as a field name. See your database documentation for a list of reserved words.
Navigation
Initial State
Navigation
Mode

Navigation (
all)
Indicates the options for displaying vertical navigation menu items.

Vertical
navigation
Expandable Submenu items are displayed in a vertical list expanded below the
parent menu item.
Page 2639 of 4705
Home
Flyout Submenu items are displayed in a vertical list expanded to the right of the
parent menu item.
New
Description
All
Next Label
Records information about a field change. To create a change description, select the New
Description property, click its ellipsis button, and enter a description into the New Description
dialog box. When you next save the field, your entry is moved to the Change History property,
where it is stored in read-only diary format.
See the description of "Next Label" and "Size of Chunk" in this section.
Cell-based
table
List view
table
Results list
Number of
Entries
Returned

Alert list
Cell-based
table
List view
table
Results list
Opacity
Panel (all)
Orientation
Horizontal
line
Vertical line
Panel
holder (
accordion,
collapsible,
splitter)
Owner
Specifies the degree of transparency of the panel's background color. If the panel does not
have a background color, this property is unavailable. See To set color opacity for a panel .
Specifies the orientation of a line: Vertical or Horizontal. For panel holders, specifies the
orientation of the panel headers: Vertical or Horizontal.
Identifies the author of each entry in the Change History property.

All
Panel
Border
Color
Cell-based
table
Panel
Border
Thickness
Cell-based
table
Panel
Bottom
Margin
Panel
Panel
Height
See the description of "Panel Border Color" in this section.
See the description of "Panel Border Thickness" in this section.
See the description of "Panel Height" in this section.

Cell-based
table
Page 2640 of 4705
Home
Panel Left
Margin
Panel
Panel Right
Margin

Panel
Panel State
Panel (
collapsible)
Panel Top
Margin
Specifies whether a panel in a collapsible panel holder is expanded or collapsed. The default
is Expand.

Panel
Panel Width
See the description of "Panel Width" in this section.

Cell-based
table
Panels

Panel
holder (all)
Pattern
Restricts what users can enter into the field. You can specify two types of character patterns:
Character
Specify a character pattern that the value must match. It is similar to that used in the
LIKE operator and can include any of the same wildcard characters (see Operator
types).
Use a keywordto specify a style for a character field. You can specify only one of the
following keywords for a pattern, and it cannot be combined with a pattern of characters
and wildcards:
$ALNUM$ The value must be alphabetic characters and digits (and blank
space).
$ALPHA$ The value must be alphabetic characters (and blank space).
$DIGIT$ The value must be digits.
$LOWER$ The value can be any character except uppercase letters. This
includes special characters, digits, and blank spaces.
$MENU$ The value must match an item defined in the default menu attached
to the field. Do not use $MENU$ together with a Change Field workflow action
that attaches a new menu (with new values) to the field. You cannot use the $
MENU$ keyword with a file menu or a data dictionary menu. You cannot use the
$MENU$ keyword with a search menu if the search menu qualification includes
a field value from the current screen or with an SQL menu if the WHERE clause
of the query includes a field value from the current screen.
$PRINT$ The value must be printable characters.
$UPPER$ The value can be any character exceptlowercase letters. This
includes special characters, digits, and blank spaces.
Note
The way that keywords are interpreted is language-dependent. For
example, $LOWER$ is not valid in Japanese, and $MENU$ is not valid
in a multilingual environment.
Permissions
Specifies which users have access to the field. To assign field permissions, select the
All
Permissions property, click its ellipsis button, and use the Permissions dialog box. For more
detail, see Field permissions.
Page 2641 of 4705
Home
Precision
Decimal
Specifies the number of decimal places displayed in the user's view. The default setting is 2
and the maximum value of precision in BMC Remedy AR System is 9.
Specifies the number of decimal places displayed in the user's view. The displayed number is
Real
Preferences
rounded off, but the value stored in the database is not changed.
Alert list
Cell-based
table
List view
table
Results list
Previous
Label
See the description of "Previous Label" and "Size of Chunk" in this section.
Cell-based
table
List view
table
Results list
Field properties Q to Z
Property
Field type
QBE Match
Description
Specifies how a match is determined when a user performs a query-by-example (QBE) in the
Character
mid tier:
Anywhere (default) Finds a match if the entered value occurs anywhere in the
corresponding field. For example, if a user enters Bob in the Submitter field, the search
returns all requests submitted by Bobby Jones, Bob Smith, and Jill Bobbington.
Leading Finds a match only if the entered value occurs at the beginning of the
corresponding field. For example, if a user enters Bob in the Submitter field, the search
returns all requests submitted by Bob Smith and Bobby Jones but not those submitted
by Jill Bobbington.
Equal Finds a match only if the entered value matches the value in the
corresponding field exactly. For example, to find requests submitted by Bob Smith, the
user must enter Bob Smith, with exact spelling and capitalization, in the Submitter field
. However, for some databases (such as Sybase or Microsoft SQL Server),
case-sensitivity depends on the underlying DBMS settings, regardless of the specified
QBE Match.
Equal and Leading generally provide better performance than Anywhere. Use them wherever
they are appropriate. You can use the Preferences dialog box ( Window > Preferences) to set
a default QBE match type for all new character fields that are not core fields.
A search on a character field with the QBE match type Anywhere performs a full table scan of
the database, reading every record in a form and ignoring any indexes for the field. Searches
on fields with the QBE match type Leading or Equal are typically faster than searches on
fields with the match type Anywhere, especially if the field is indexed. See Defining indexes.
Some relational operators and wildcards work during a QBE regardless of the QBE Match
setting. This means that users can specify an exact match in a field with the QBE Match
setting Anywhere by using the equal sign (=) relational operator. Users can also use the
Page 2642 of 4705
Home
percent sign (%) wildcard at the beginning of the search string ( %abcd ) to override the QBE
Match setting Leading or Equal. Using the % wildcard anywhere else in a string ( abcd% )
does not override the Equal setting. Overriding the Leading or Equal settings overrides the
performance benefits of using those settings.
Read
Button
Refresh
Button

Alert list

Alert list
Cell-based
table
List view
table
Results list
Refresh on
Entry
Change

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Refresh
Row
Selection

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Remote/
Local Fields
Report
Button
Opens a dialog box used to add columns to tables. See To add a table field to a form .
Cell-based
table

Cell-based
table
List view
table
Results list
Results
Color
See To set row text and background colors.

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Page 2643 of 4705
Home
Rounded
Corners
Panel (all)
Specifies the radius of roundness for the corners of a panel. The default is blank (no rounded
corners).
Note
Rounded corners are not shown in BMC Remedy Developer Studio.
Row
Header
Row
Selection

Alert list
Cell-based
table
List view
table
Results list

Alert list
Cell-based
table
List view
table
Results list
Rows
Specifies the number of rows of text that are displayed.

Character
Diary
Check box
Drop-down
list
For radio buttons, specifies the number of rows used for selection options. A setting of 1
produces one horizontal row. A setting of 2 divides the options into two horizontal rows, and
so on. For other types of selection fields, this property cannot be changed.
Radio
button
Save Label

Attachment
pool
Scale
Image to Fit

Button
Scroll Bar
Specifies how scroll bars are displayed:

Application
list
Data
visualization
View
Default Displays scroll bars only when the field content does not fit completely within
the field.
Show Always displays scroll bars.
Hide Always hides scroll bars.
Note
If the content of a field (such as a BMC Remedy AR System form) has its own scroll
bars, they appear even if you hide scroll bars for the field itself. If you can hide the
scroll bars of the content, you can remove all scroll bars from the field.
Page 2644 of 4705
Home
Select All

Alert list
Cell-based
table
List view
table
Results list
Select
Column

Alert list
Cell-based
Label
table
List view
table
Results list
Select item

Navigation (
on click
all)
Selections
See To add selection items.

Check box
Drop-down
list
Radio
button
Server
Data
visualization
Shared
Fields
See Shared fields in panel holders.

Panel
holder (all)
Size of
Chunk
Show URL
Specifies the BMC Remedy AR System server that contains the data visualization module.
See Using buttons and menu bar items to execute active links .
See the description of "Size of Chunk" in this section.

Cell-based
table
List view
table
Results list
Character
Specifies whether a URL is made active when a user types a URL address (such as http://
www.bmc.com) into a character field. The default is False, which means the URL does not
become active within the field.
If the field is not empty and Show URL is set to True, users cannot directly type into the field.
They must open the expand box to edit the contents of the field.
Slack
Distribution
Panel
See Distributing slack to avoid scroll bars.
Order
Sort
See To set sort order and visible levels.

Cell-based
table
Page 2645 of 4705
Home
Sort/Levels
See To set sort order and visible levels.

Alert list
List view
table
Results list
Tree view
table
Splitter
State
Panel
holder (
Specifies whether the splitter bars between panels in a splitter panel holder are visible and
can be dragged to resize the panels. The default is Visible.
Visible The splitter bar is visible and can be dragged.

Disabled The splitter bar is not visible and cannot be dragged.
Invisible The splitter bar is not visible but can be dragged.
splitter)
Start Color
Data (all)
(Web only) When the Enabled property is set to True, enables selection of a color for the
highlight based on the theme of the form, background color, and other factors. If no highlight
start color is specified, the mid tier uses the default color of yellow.
Sub Level
Background
Color
Vertical
Navigation
The sub level alternate background color. This setting is applicable only to Vertical Navigation
Bar in the Flyout mode.
bar
Tab Order
Application
list
Specifies the order in which the field is selected when users press the TAB key. See Setting
the tab order of fields in a form view.
Button
Composite (
all)
Data (all)
Data
visualization
Navigation (
all)
Trim text
View
Table
All (view
and vendor
forms only)
Table Drill
Down
Table
Header
Footer
Specifies the name of the database table associated with the field. This field is read-only. For
more information, see View and Vendor formsUsing buttons and menu bar items to execute
active links#89961.

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Tables (all)
Attachments
For tables, this property specifies the color for the header and footer. For attachments, this
property specifies the color for the footer. (Attachments do not support header).
Page 2646 of 4705
Home
Gradient
Background
Color
Table Not
Loaded
String

Cell-based
table
List view
table
Tabless
Borderless

Panel
holder (
tabbed)
Text
See To create trim fields.

Trim text
See To create a view field.

View
Text Align

Trim text
Text
Rotation

Trim text
Text Style

Trim text
Tree/Table
Property
Opens a dialog box used to add columns to tables. See To add a table field to a form .
Alert list
List view
table
Results list
Tree view
table
Thickness
Horizontal
line
Panel
Trim box
Vertical line
Unread
Specifies a line width of 1 to 9 pixels. The default is 2. Thickness cannot be changed if the
Depth Effect is Etched.

Alert list
URL Color

Button
See To add a URL to a trim text field .

Trim text
Use Locale
See Locale-specific refresh.
Page 2647 of 4705
Home
Alert list
Cell-based
table
List view
table
Results list
Tree view
table
Vendor
All (vendor
form only)
Vertical
Space
For fields on vendor forms, specifies the vendor name. For more information, see View and
Vendor formsUsing buttons and menu bar items to execute active links#89961 .
See Vertical Space.

Cell-based
table
Vertical
Spacing

Panel
Views
All except
table
columns
Visible
All
Visible
Columns
Specifies the form views in which a field appears. See To add or remove a field from form
views. New fields are automatically added to the current view. Depending on how your
preferences are set, new fields might also be added to all other views of the form. (In BMC
Remedy Developer Studio, select Window > Preferences. Under "BMC Remedy Developer
Studio," click Form.) Some field properties affect all form views while other field properties do
not. All display property settings apply to only the form view in which they are set. For
example, in one view a field might be visible while in another view the field might be hidden or
located elsewhere in the form. See Creating packing lists and Creating and managing fields.
Specifies whether the field is visible in the current view. When this property is set to False, the
field cannot be seen in the view, although users with Customize permissions can make a
hidden field visible. A hidden field remains in the database and can be accessed by workflow.
You can create active links to dynamically hide and unhide all fields except tree view table
column fields.
See Visible Columns.
Cell-based
table
Width
Defines the width of the field in pixels.

All
Wrap Text

Alert list
Cell-based
table
List view
table
Results list
Tree view
table
X
All
Page 2648 of 4705
Home
If the Alignment property is set to Left (default), specifies the horizontal position of the left
edge of the field relative to the left side of the form. If the Alignment property is set to Right,
specifies the horizontal position of the right edge of the field relative to the right side of the
form. The X and Y settings are relative to the top left or right corner of the form. For example,
X=0, Y=0, and Alignment=Left is the top left corner of the form.
Note
If a field is anchored to the right side of a panel in a panel holder, the field's X value
might change if either of the following actions occur:
(Tabbed only) The Display Type of the panel holder is changed.

(Accordion, collapsible, or splitter) The Orientation of the panel holder is changed.
Defines the vertical position of the left or right edge of the field in the form. The X and Y
All
settings are relative to the top left or right corner of the form. For example, X=0, Y=0, and
Alignment=Left is the top left corner of the form. If you have a series of data fields on the
same line, these fields must have the same Y coordinate for tabbing between fields to work
from left-to-right, top-to-bottom unless you define a tab order of fields in the form. See Setting
the tab order of fields in a form view.
Properties tab for fields in Best Practice Customization Mode

This topic describes the changes to the Properties tab for fields in the Best Practice Customization
Mode. For a description of all field properties, see Field Properties.
Field properties for overlays in Best Practice Customization mode

In Best Practice Customization mode, the field properties are categorized to support overlay of
granular components of field properties.
The Properties tab separates the granular components that you can overlay from the other
components. With the Overlay Type field under Permissions, you can add to (Additive) or
overwrite (Overwrite) permissions, or you can select No Overlay. With the Overlay Type field
under Other, if you select Overwrite, the properties that you can changes are enabled.
Field properties in Best Practice Customization mode
Page 2649 of 4705
Home
For example, if you selected the Alert Text field in a form, the Properties tab displays the following
view:
To modify the permissions, select Additive from the Overlay Type down-down list under
Permissions. Click Set Permissions to open the Permissions dialog box and add permission
groups.
To modify the help text, select Overwrite from the Overlay Type down-down list under Others.
The Help Text property becomes editable.
Page 2650 of 4705
Home
Custom fields in Best Practice Customization Mode

Because you cannot overlay a custom field, the Overlay Type drop-lists are disabled when you
select a custom field. You can set permissions for the custom field from the Properties tab. The
Set Permissions button is enabled for a custom field. Click the Set Permissions button to assign
permissions for the custom field. (See the following image.)
Field properties view for a custom field
Related topics
Customizing applications using overlays and custom objects
Recommendations while developing applications

This topic lists some recommendations that you can follow while developing applications by using
the BMC Remedy Developer Studio.
Basic Columns
Use the the Basic Columns feature to gain performance on Object Lists. Selecting Basic
Columns option in Object List View in the preference page reduces the time taken to open
the object list because only the basic information is fetched.
Set column display to No
If you do not want to BMC Remedy Developer Studio to fetch certain columns from the
database, set the display type for the column to No. This improves the BMC Remedy
Developer Studio performance. For information about setting the column display, see Do not
display columns that are not required .
Do not validate tables on form open
When your form contains lot of tables, it is advisable to select the Do Not Validate Table
Fields When a Form is opened option, especially when fields used in the table come from
a remote form.
Record Object Relationships
Use the Administration Console > Configurations tab > Record Object Relationships
option to improve performance when working with large applications. Setting this option
requires a server restart. When restarted for the first time, the server takes some time to get
Page 2651 of 4705
Home
started based on size of the installation. This is just a one-time activity. Once server gets
restarted you can utilize the benefit of this feature. However, since the server start time is
increased by this setting, it is recommended to only use it option in development server. This
feature is heavily used by RDP features like Analyzer, Search, and Relationships view.
Even working lists perform better if this feature is on.
Working Lists
Use Working Lists to work on selected objects. Generally, an AR System developer might
be working on a subset of objects of the application. In such cases, the Related List and
View by Form List allows the developer to work on those objects which are of interest to the
developer. There is no need to open up entire object list to find the object of interest. It also
lists all the objects in just one view, there is no need to switch between views of different
object types to find the needed object.
View by Form List allows developer to work with set of forms and their workflow objects.
Related List on the other hand, allows the developer to work with any object and their
directly related or all related objects.
All Related
Use the All Related option only if absolutely required. Related Lists, at the time of its
creation, allow a developer to configure to fetch all related objects of a selected object. This
option must never be used unless and until it is unavoidable. This option may make BMC
Remedy Developer Studio unresponsive, as it takes large amount of time to find all related
objects of a given object.
String Search
Use String Search to find objects. BMC Remedy Developer Studio's String Search is a
replacement of RDP Search. Using String Search, one can quickly find all the objects which
contain a particular string in it. For example, if you want to find workflow objects which use a
particular field in their Run-If qualifications then String Search will help you in achieving this
. There are many more locations where you can search a string.
Note
String Search will be available only if Record Object Relationships is turned on.
Relationships View
Use Relationships View to view related objects. Relationships view, as its name suggests
, lists the related objects of a given object. This view is meant to quickly view the related
objects. To see related objects of an object in the Object List view, right click on the object
and select Show Relationships. This will activate the Relationships views and show any
related objects, along with the kind of relation, in the table.
Page 2652 of 4705
Home
To see related objects of a field then open the form, select Link with Editor in
Relationships view and then select any field in the form. If the selected field has any
related objects then they will be shown.
Note
Show Relationships functionality will be available only if Record Object
Relationships is enabled in server.
Analyze objects on Save

You can analyze the objects on save operation to know whether the updated object is
violating any rules. Open Analyzer Results view when an editor is opened and select Link
with Editor option in the Analyzer Results view to bind it to the current active editor. When
this is done, Analyzer will analyze the object whenever the object gets saved through the
editor.
Note
Analyzer will be available only if Record Object Relationships is enabled in
server.
Recommendations for multiple development teams

When an application is developed by more than one person or teams, Version Control feature can
be handy in maintaining integrity and to (optionally) maintain versions of an object. Following
sub-parts of Version Control can be used.
Object Reservation
Use Object Reservation to maintain integrity. Using Object Reservation feature one can
avoid overwriting changes made by an AR System developer from other team members.
Using this feature, an AR System developer can reserve or release an object when required
and thus ensure that the object will not be overwritten by other team members till the task is
completed.
Object Modification Log
Use Object Modification Log to track changes and optionally enable versioning. Using this
feature keeps track of all changes made to an object and revert to the older version if
required (optional).
Note
Page 2653 of 4705
Home
Object Reservation/Object Modification Logging feature must be enabled in the

server in order to use it in the BMC Remedy Developer Studio.
Adding graphics to an application with

flashboards
The following sections explain the process for adding graphics to an application with flashboards:
Types of flashboards
Process for creating a flashboard

Flashboards are a dynamic, graphical representations of data in BMC Remedy AR System forms.
You can use BMC Remedy Flashboards to perform the following data manipulations:
Process, store, and display data from the BMC Remedy AR System in the form of graphs,
charts, text boxes, and meters.
To display information about several variables or to compare historical data, use a
chart.
To display information about single variables, use meters or text boxes.
Meters display a statistic whose value normally lies within a specific range. Meters
display only the most recently received values.
Text boxes display information in text form.
Summarize and display real-time, historical, summary, or historical and real-time data in new
or existing BMC Remedy AR System forms for trend or historical analysis. To display
historical or summary data, use the following types of flashboards: line, bar, stacked bar,
area, stacked area, and table.
Warning
You cannot use pie, meter, or text flashboards to display historical or summary data.
Provide visual alerts with the alarm component.

Drill down to see what data was gathered to produce a flashboard.
Page 2654 of 4705
Home
You must refresh a flashboard to view the most recent historical, summary, and real-time data.
BMC Remedy Flashboards is fully integrated with BMC Remedy Developer Studio.
Note
BMC Remedy Mid Tier versions 7.5.00 and later use Adobe Flash technology by default
to enable a sleeker look and feel that allows more user interaction with the BMC Remedy
Flashboard. You can choose not to use Adobe Flash technology. For more information,
see Modifying flashboard properties.

This section describes how historical and summary data is created.
Data flow when working with flashboards
Runtime behavior
Data flow when retrieving historical or summary data
Data flow when working with flashboards

To create, modify, and delete flashboards, use BMC Remedy Developer Studio (as described in
Creating and managing flashboards). The AR System server processes the information from the
flashboard and its variables and returns the information about the new or modified flashboard to
BMC Remedy Developer Studio. Then, BMC Remedy Developer Studio retrieves the flashboard
image from the mid tier. For information about how to configure the AR System server to point to a
specific mid tier, see Default Web Path.
Runtime behavior
BMC Remedy Mid Tier is used to display graphical information from flashboards into a browser.
The mid tier passes access permission information to the AR System server, holds requested
Flashboards image information in a cache, and translates the image information so that the display
client can view it. When a display client requests a Flashboards image, the mid tier checks whether
the information is in the mid tier cache and if the cache has not expired. If so, the mid tier generates
an image and sends it to the display client. If the information is not in the cache or the cache has
expired, the mid tier requests the information from the AR System server, updates the cache,
generates an image, and sends it to the display client.
Page 2655 of 4705
Home
Data flow when retrieving historical or summary data

You can use BMC Remedy Flashboards to retrieve historical data and summary data from the BMC
Remedy AR System.
The BMC Remedy Flashboards server is used to collect historical data. To start and stop the BMC
Remedy Flashboards server, see Starting or stopping the Flashboards server manually .
Creating historical and summary data

1. As determined by the collection interval, the BMC Remedy Flashboards server retrieves
statistics on the form data from the AR System server.
2. The BMC Remedy Flashboards server returns statistical data to the AR System server and
data is added to the FB:History form.
3. As determined by the collection interval, the BMC Remedy Flashboards server retrieves data
from the FB:History form through the AR System server.
4. The BMC Remedy Flashboards server summarizes the historical data.
5. The BMC Remedy Flashboards server adds the data to the FB:History Summary form
through the AR System server.
6. The historical data is presented in the Flashboard.
Types of flashboards
Flashboards can display:
Real-time data as a single point

Historical or summary data over a period of time
Historical and real-time data over a period of time
For more information about how to represent data in flashboards, consult a statistics book.
Note
Use no more than 50 data points (points on the graph) for each flashboard. Displaying
more than 50 data points might affect the BMC Remedy Mid Tier performance.
The following sections explain the types of flashboards:

Line chart
Bar chart
Stacked bar chart
Area chart
Stacked area chart
Page 2656 of 4705
Home
Pie chart
Meter chart
Text chart
Capacity chart
Line chart
Line charts (the following figure) are most often used to display trends. Line charts display values
along a common baseline, which allows quick and accurate comparisons. You can also use line
charts to display grouped data represented by different symbols and colors for each component.
For example, you can display the number of High tickets (yellow diamonds), Medium tickets (red
squares), or Low tickets (green triangles) that were closed last month.
Line chart
Bar chart
Bar charts (the following figure) are most often used for direct comparison of magnitude between
categories. Bar charts can also be used to show time-dependent data when the time interval is
small. For example, a bar chart might be useful to compare the number of tickets assigned to
various employees in one month.
When the bars in a bar chart are of equal width, the length of each bar is proportional to its value,
allowing you to compare the differences between bars more easily.
Vertical bar charts are most often used to portray time series, such as the number of high tickets
during the course of a month. Horizontal bar charts are most often used to compare data directly,
such as the number of tickets assigned to several employees.
If your bar labels contain a lot of text, consider using horizontal bars that allow you to have more
room on the vertical axis.
Page 2657 of 4705
Home
Bar chart
Stacked bar chart

Stacked bar charts (the following figure) consist of segmented bars. Each segment represents a
share of the total value in the bar. Stacked bar charts are suitable for presenting discrete data.
Stacked bar charts are not recommended for:
Subtle comparisons, as comparisons are difficult among the second, third, or subsequent
segments in a stacked bar because there is no common baseline.
Components that exhibit irregular or sharp changes in represented values.
Stacked bar chart
Page 2658 of 4705
Home
Area chart
Area charts (the following figure) are used to display a limited number of related, continuous
variables.
Area chart
Stacked area chart

Stacked area charts (the following figure) consist of irregular segments, each of which represents a
share of the total value in the graph. Stacked area charts are suitable for displaying the trend of a
values over categories or time. They are not recommended for subtle comparisons, as
comparisons are difficult among the second, third, or subsequent segments because there is no
common baseline.
Stacked area chart
Page 2659 of 4705
Home
Pie chart
Pie charts (the following figure) are most often used to display a few components that are easily
distinguishable. Typically, each slice of a pie chart displays statistics from one variable. For
example, a pie chart can display one employee's High, Medium, and Low tickets. When you display
a pie chart flashboard, the individual percentages of each slice are displayed. You can display both
percentages and actual values of each slice by setting the showvalues parameter to 1. (See
Customizable parameters.)
Pie chart
Pie charts are not recommended to display:

Subtle or slight changes in the segments.
Many components at once.
Relative size of components.
Variables using a double Group By option.
Note
You cannot use a pie chart flashboard to display historical data or summary data. If you
try to use a pie chart to display this type of data, an error is displayed.
Meter chart
Meter charts (the following figure) measure the most recent variable value from the variable
associated with that meter. Meters can be configured to show increasing levels of severity. For
example, you can create a meter that measures the total number of unassigned High priority tickets
. You can configure the meter to display the total number of tickets in colored zones (up to 20 ticket
counts in the green zone, between 20 and 40 tickets in the yellow zone or Warning Threshold, and
40 to 50 tickets in the red zone or Alert Threshold).
Page 2660 of 4705
Home
Meter chart
You can also set up a Flashboards Alarm to send a warning to a specified recipient when the
needle enters the Alert Threshold.
Text chart
Text charts (the following figure) display one value and its associated text. For example, you might
use a text chart to display the average number of daily unassigned tickets at the end of one week.
Text chart
Capacity chart
Capacity charts (the following figure and the following figure) display the value in the percentage
form. Capacity chart can be a single bar with two or more sections or multiple bars that are of equal
size stacked one above the other.
Some features of the capacity flashboards are:
embedded, stacked bar with horizontal layout
Page 2661 of 4705
Home
Y axis line and labels are invisible

X axis line is invisible but labels are visible on the top of the bars
Each colored bar or section represents a task or an entity. The length of the bar represents 100%
of the task or the entity. The tooltip on the flashboard displays the percentage of task progress or
entity group.
Note
The value on each bar or section is the actual value and the tooltip on the bar or section
displays the percentage value for the task or entity.
For example, assume a storage memory of size 260 TB.

Companies A, B, and C are allotted with memory space of 70 TB, 90 TB, 100 TB respectively. To
compare the allowed memory percentage for each company, you can use a capacity flashboard.
See the following figure.
Capacity flashboard to verify percentage memory shared
The following figure illustrates the memory usage percentage by each individual company.
Capacity flashboard to verify memory usage
Page 2662 of 4705
Home
Note
When you view the capacity flashboard using BMC Remedy Mid Tier 7.6 or earlier, it
appears like a regular flashboard without displaying the percentage.
Process for creating a flashboard

This section defines the process you require to follow to create a flashboard. The steps involved in
creating a flashboard are listed below:
Creating a flashboard is accomplished through the following process:
1.
2.
3.
4.
Planning the flashboard

Creating flashboard variable
5. Making your application accessible
This section uses an example to illustrate how you plan and create a flashboard.
Defining business needs

Jane is the manager of a small department that is responsible for resolving the company's
hardware and software issues. Company employees who experience problems with their
computers create tickets in BMC Remedy Mid Tier. The tickets are assigned to Mary, Pat, and
Chris, who report to Jane. Chris is assigned to the department only part time. Jane wants to assign
Chris to help Mary and Pat on the day that receives the highest number of tickets. The employees
in her department tell her that Mondays are the highest traffic days, but she wants to be sure before
she rearranges Chris' schedule.
Defining the purpose of the flashboard

Jane wants to create a flashboard that meets the following criteria:
Collects data for each day of the week for one week.
Summarizes that data per day.
Displays the summarized data each day of the week for one week.
Allows Jane and her group to view the data.
Afterwards, Jane might like to add a notification function to the flashboard so that Chris is notified if
the total number of tickets on a particular day exceeds an acceptable number, so he can rearrange
his schedule to respond to the extra calls.
Page 2663 of 4705
Home
Designing the flashboard

Jane's flashboard must display data gathered over the course of one week, so she selects a bar
graph flashboard to display the historical data. She could also select a line chart or area chart, but
not a pie, meter, or text flashboard because these types of flashboards cannot display historical
data.
The information is gathered over a short period of time, so choosing a stacked chart is not a useful
way to display the data.
For more information about choosing the best type of flashboard for your needs, see Types of
flashboards.

Variables specify the information you want to monitor from a single form. A variable represents the
data, such as a slice of a pie graph, a bar in a bar graph, or a line in a line graph. For example,
high-priority service requests, requests created within the last hour, or requests assigned to one
employee could each be represented by a bar. Variables have unique names and can be
associated with more than one flashboard.
Note
To optimize display time, avoid using too many variables in your flashboard.
The following sections provide information about creating, modifying, deleting, or renaming
variables and the steps to set up row-level security:
Creating a variable
Modifying, deleting, or renaming variables
Setting row-level security for variables
Creating a variable
Creating a variable is accomplished through the following process:
To create a variable
1. Open BMC Remedy Developer Studio.
2. In BMC Remedy AR System Navigator, expand serverName > All Objects.
3. Right-click Flashboard Variables, and select New Flashboard Variable.
To add a variable to an application, expand serverName > Applications. Then, right-click
on the application, and select New Object > New Flashboard Variable.
4.
Page 2664 of 4705
Home
4. In the New Flashboard Variable wizard, select the form from which you want to gather
statistics, and click Finish.
5. Use the following table to enter values in each field.
Fields used to create a flashboard variable
Field or Area
Description
Variable panel
Drill Down
Controls what happens when users click an item on a flashboard. The options are:
To View Enter the form view that users see. For example, you might create a different view
for managers that displays only information that will affect them directly.
Send Event Enter the value that is entered if the $EVENTTYPE$ keyword is used in an
active link that is triggered.
This option is available for real-time data only (not historical or summarized data). For more
information about sending events, see Ability to highlight required fields through workflow.
(Optional)
Qualification
Search criteria (including field references, values, and arithmetical and relational operators) used to
find a set of data that matches the conditions specified. For example, if Jane Manager wants to create
a variable that displays the total number of requests for each day, but she does not want to include
Low priority requests, she might enter the following qualification:
'Priority' != "Low"
To search for values that are null, use the $NULL$ keyword in the qualification.
Operation panel
Count
Sum
Average
Minimum
Maximum
(Optional)
Expression
Statistical operation that the server performs on the data that the query returns. Examples include:
Select Average to display the average number of calls that Customer Support receives in one
week.
Select Minimum or Maximum to display the lowest or highest number of calls received during
the same week.
Select Sum to display the sum of all the calls received during the month.
Definition of the type of operation to perform. An expression is required if the operation is Sum,
Minimum, Maximum, or Average. It is optional for Count. An expression performs an operation on
selected form fields and keywords. You can use expressions with operations that use numeric data
types, but not with operations that use character or diary data types. For example, your Customer
Support employees might receive many calls from an important customer, whose customer support
identification number (Cust ID) is 25. You already have a form that collects all the calls to Customer
Support over the course of one month. You might then create individual variables with each of the
Average, Minimum, Maximum, and Sum operations selected in the Operation option. Each of these
flashboards would contain the following expression:
'Cust ID' = "25"
Your flashboards display the average, minimum, maximum, and sum of the number of calls from
customer 25 over the course of one month.
(Optional)
Group By
Displays statistics for the distinct values within a field. You can select a primary field and a secondary
field. For example, if you group a Count operation by Status, the resulting flashboard is a graph of the
counts of each individual status value, such as New, Assigned, or Closed. For Group By fields, you
cannot perform an operation, such as Count, on a primary flashboard field if that field is a currency
Page 2665 of 4705
Home
field, unless you specify the currency field part. For example, if your flashboard displays a count on
Field A that is grouped by Field B, you must specify the type of currency parameter for Field A, for
example Curr1.date or Curr1.value, not just Curr1. In addition, you cannot use a currency field for
the Group By field, Field B.
(Optional) Sort
After selecting the primary and secondary fields for the Group by field, you can select any one of the
following values for the Sort field:
No Sort (default) Do not use the sort option.
By Value Sort by value.
By Attribute Sort by attribute. When you select this option, the Sort Attribute field is
enabled. If the secondary Group by field value is an enum field, attribute values are listed in a
drop-down menu. If the secondary Group by field value is a non-enum field, you must enter the
attribute value in the text field.
Note
You can change the sort order from ascending (default) to descending by clicking the radio
buttons.
(Optional) Data Collection panel

Collect Data
Enables collection of the data you want to view in your flashboard. The server saves the collected
information in the FB:History form. You must start the BMC Remedy Flashboards server before you
collect data.
To start the server on Windows, use the Control Panel or type start.bat from the command
prompt.
To start the server on UNIX, type server.sh start from the command line.
Summarize
Data
Instructs the server to save the collected information in the FB:History Summary form. If you select
this option, the Summary section of the Data Collection panel is enabled.
Note
The Summarize Data option is enabled if you select Collect Data.
Interval
Sets the frequency at which the BMC Remedy Flashboards server polls the BMC Remedy AR System
database for information that matches a query. You can specify intervals such as yearly, monthly, and
daily. When setting the interval, consider how often the server group generates the type of data you
are interested in, and how much database space the data requires.
Expiration
The interval that sets the frequency at which the BMC Remedy Flashboards server deletes or expires
History
subpanel:
Collection
data. The options are:

None Data is not expired or deleted.
Expire Data cannot be displayed and is disabled in the database after the period set in the
After field.
Delete Data cannot be displayed and is removed from the database after the period set in
the After field. If you choose to delete data, you cannot retrieve the data.
From the After field and drop-down list, set an interval of minutes to years. Consider how long you will
need your data and how much database space is needed to keep it.
Summary
subpanel:
Collection
Interval
Sets the frequency at which the BMC Remedy Flashboards server polls the BMC Remedy AR System
database for information that matches a query. Sets the frequency for how often data is collected to
populate the flashboard. You can specify intervals in months and days. When setting the interval,
consider how often the server group generates the type of data you are interested in, and how much
database space the data requires. For example, you might choose to count the total number of help
Page 2666 of 4705
Home
desk tickets received in one hour, and summarize the average ticket count for each day at the end of
the day. You must select a summary interval that is one level above your data collection interval. For
example, you cannot choose to summarize hourly on data that is collected hourly; you must
summarize the data by day, week, month, or year.
Expiration
The interval that sets the frequency at which the BMC Remedy Flashboards server deletes or expires
data. The options are:
None Data is not expired or deleted.
Expire Data cannot be displayed and is removed from the database after the period set in
the After field.
Delete Data cannot be displayed and is removed from the database after the period set in
the After field. If you choose to delete the data, you will not be able to retrieve it again.
From the After field and drop-down list, set an interval of minutes to years. Consider how long
you will need your data and how much database space is needed to keep it.
6. In the Properties tab, set the values for the following properties, as needed:
New Description (description for Change History)
Permissions
7. Save the variable.
8. If you set the drill-down option for the variable (see Drilling down to information in a
flashboard), set this option in the flashboard (see Creating flashboards).
Modifying, deleting, or renaming variables

Use the procedures in this section to modify, delete, or rename variables.
Warning
If you modify or delete variables, you also affect the flashboards and alarms associated
with them. For example, you might need to modify any filters you created for the alarms.
To modify a variable
2. Double-click Flashboard Variables.
3. In the Flashboard Variables list, double-click the variable name.
4. Modify the data as needed.
5. Save the variable.
To delete a variable
3. In the Flashboard Variables list, right-click the variable name, and select Delete.
To rename a variable
2.
Page 2667 of 4705
Home

3. In the Flashboard Variables list, right-click the variable name, and select Rename.
4. In the New Name field, enter a name, and click OK.
Setting row-level security for variables

For real-time data, flashboard grants access to statistical data based on user login information.
For historical and summary data in multi-tenant environments, you can grant access to flashboards
variables by implementing row-level security. If you do not set permissions for a variable, only the
administrator who created the variable can see the information in the flashboard.
This row-level security enables you to show and hide information based on a user's permissions.
For example, if you place a flashboard on a Help Desk form, you can display one set of data to
support representatives and a different set of data to requesters.
To set row-level security for variables

1. In BMC Remedy Mid Tier, open the FB:User Privilege form in New mode.
2. From the Variable list, select the variable.
3. From the User list, select a user with group permissions to the data.
Warning
You can select any user in the group, but select a user that will not be deleted. If
the user is deleted, permissions to the variable are lost, and you must select a new
user in the FB:User Privilege form.
4. From the Group list, select the group to which you want to give row-level security.
You can enter more than one group in this field by selecting from the Group list multiple
times.
5. Click Save.
6. Repeat these steps for each group.
If you delete a variable, the corresponding records you created in the FB:User Privilege form
are automatically deleted.

This following sections explain the procedure to create and manage flashboards:
Modifying a flashboard
Deleting a flashboard
Setting up notifications for a flashboard
Page 2668 of 4705
Home
Creating alarms
Modifying, disabling, or deleting alarms
After creating your variables, as described in Creating a variable, you are ready to create your
flashboard. Different flashboards can use the same variables.
Note
You can use flashboards with deployable applications and BMC Remedy AR System
applications. However, if you use flashboards with BMC Remedy AR System applications,
you cannot view Flashboards objects in applications or packing lists. You must access the
objects through the All Objects list.
To create a flashboard
2. Right-click Flashboards, and select New Flashboard.
To add a flashboard to an application, expand serverName > Applications. Then, right-click
on the application, and select New Object > New Flashboard.
3. Enter values for the fields on each panels.
Fields used to create a flashboard
Field or
Area
Description
Flashboard panel
Title
The title that you want to appear in the graphical display on the form. The flashboard title should reflect its
function. For example, a flashboard that collects tickets that the server receives in one month might be
titled: Total Tickets for April 2010.
Chart type
Type of chart you want to create. The options are:

Line
Bar
Stacked Bar
Area
Stacked Area
Pie
Meter
Text
Capacity
For more information about choosing the best type of flashboard for your needs, see Types of
flashboards.
Drilldown in
Variables
Allows users to drill-down in the flashboard to view, modify, and delete the underlying data associated with
the visual display.
Page 2669 of 4705
Home
User Can
Customize
Note
This option is used for previous "image-based" formats only. (For more information, see
Modifying flashboard properties.)
Enables users to customize the flashboard. Default customized flashboards options are:
Chart title
Chart type
Legend title
X axis label
Y axis label
Time frame to be displayed
This option is valid for the 7.1.00 and 7.0.01 format. For more information about the various flashboards
formats, see Modifying flashboard properties. For more customizable options, see Changing display
parameters for flashboards. To limit the number of options that users can select:
a. Open the form that contains the Data Visualization field for your flashboard.
b. In the Properties tab, for the Custom Properties property, enter customizableparams= immediately
followed by the customizable options to display, in lower case and separated by single spaces. For
example, if you enter the following line, users can only customize the chart title, chart type, and X
axis labels:
customizableparams=charttitle charttype xaxislabel Users can view the customizable options menu on
the flashboard. For example, to change the time frame display, the user selects Time Frame from the
menu on the flashboard, and then selects the time frame (for example, Today ).
Display
Type
Type of flashboard that you are creating:

Real Time Displays the data as it is collected.
History Displays the historical data collected over a time interval.
Summary Displays a summary of historical data.
History till date Displays historical and real-time data in a single flashboard.
Note
Page 2670 of 4705
Home
If you want to display historical or summarized data, you cannot select a pie, meter, or text
flashboard because these types of flashboards can display only real-time data. Instead, select a
line, bar, or area chart.
Background
Color
Background color for the flashboard. Select a color that increases readability and contrast.To change the
color:
a. Click the Color button.
b. In the dialog box that appears, select a Primary Color.
c. To display a graduated color pattern, select Gradient, and select a Target Color. Then, select the
gradient pattern.
Legend
Legend for a flashboard.To enable the legend:

a. Select Show Legend.
b. Enter a title for the legend in the Legend field.
c. Select where you want to place the legend:
Right
Left
Top
Bottom
Orientation
Orientation of the X and Y axes on a chart.
Variables panel
Name
List of the variables for the flashboard.To add variables to the list:
a. Click Add.
b. Select a variable, and click OK.
c. Repeat these steps for each variable.
To set the format for each variable:
a. Select the variable.
b. Set the remaining fields on the Variables panel. (The fields are described in the following rows of
this table.)
Enable
Variable
Option to set whether the selected variable is displayed in the flashboard.
Label
Label for the selected variable.
Color
Color for the selected variable.To change the color:

a. Click the Color button.
b. In the dialog box that appears, select a Primary Color.
c. To display a graduated color pattern, select Gradient, and select a Target Color. Then, select the
gradient pattern.
If you group variables (see Creating a variable), flashboards automatically assigns colors to those
variables. However, you can change the variable colors with the Group By button, as described in this
table. (You can also use the gbcolors parameter, described in Adding a flashboard to a BMC Remedy AR
System form)
Style
Style of the lines for the variable in the flashboard. The options are Solid and Dashed. This option is
enabled when you are creating a Line chart.
Group By
Option that allows you to select the color for each item of a variable in the flashboard. For example, you
might have a selection field that contains the options Urgent, High, and Medium. With the Group By option,
you can select a separate color for each option. Urgent might be red, High might be orange, and Medium
might be blue. The Group By button is available only if you enter a selection field (radio button, drop-down
list, or check box) in the Primary field on the Operation panel when creating a flashboards variable. (See
Creating a variable.)
Page 2671 of 4705
Home
Note
When creating a variable, select only the Primary Group By field. If both the Primary and
Secondary options are used, the Group By button on the Variables panel is disabled.
To use the Group By option:

a. Select the variable.
b.
c.
d.
e.
Click the Group By button.

In the Group By Colors dialog box, select a category from the list, and select a color.
Repeat step 3 for each category.
Click OK.
X Axis panel (Line, bar, area, and pie charts only)

Label
Label to display on the X axis.
Show Grid
Option to display the X axis grid on the flashboard.
Show As
Time
Option to display the time frame on the X axis. You can display all dates or a specific date, such as
yesterday. You must select the Show As Time option if your flashboard is a line chart and contains a
variable that is enabled for data collection. For more information, see Creating a variable.
Note
This field is enabled only when the History or Summary chart is selected. If the Real time chart is
selected, all the variables in the flashboard must have the primary Group By on date-time field.
Time
Frame
Time frame for the flashboard:

All dates
Custom
Today
Yesterday
This Month
Last Month
Year to Date
Last Year
Last Week
This Week
Next Week
Next Month
Note
The future time options, such as Next Week and Next Month, are not available for History and
Summary charts.
Start Date
and Time
End Date
and Time
Start and end times to display data on the X axis.
Note
These fields are enabled only when you select Custom for the Time Frame.
Page 2672 of 4705
Home
Y Axis panel (Line, bar, area, and pie charts only)

Label
Label to display on the Y axis.
Show Grid
Option to display the Y axis grid on the flashboard.
Range Auto
Range
Range of values. The options are:

Range Auto Range of values that the BMC Remedy Flashboards server selects.
Custom
Range Custom Minimum and maximum values to display on the Y axis. Enter those values in the
Min and Max fields that are enabled when you select Range Custom.
Meter panel (Meter charts only)

(Optional)
Label
Label for the variable. (This is not displayed anywhere.)
Range
Minimum and maximum values for the meter's range.
Thresholds
Thresholds that are displayed on the meter:

Warning Sets the start point for a yellow band on the meter, which stops where the Alert
Threshold starts. The Warning Threshold must be lower than the Alert Threshold.
Alert Sets the start point for a red band on the meter, which stops at the Range Maximum value.
Text panel (Text charts only)

Label
Label for the text flashboard.
4. In the Properties tab, set the values for Permissions.

For information about permissions, see Access control overview.
5. In the Properties tab, enter details for the New Description property to record the change
history.
To view the change history, click the Change History property, and then click the ellipsis (...)
button that appears.
6. To modify other properties (such as font and color details) for the flashboard, edit the
properties in the Properties tab.
For more information, see Modifying flashboard properties.
7. Save the flashboard.
8. To place the flashboard on BMC Remedy AR System form, see Adding a flashboard to a
BMC Remedy AR System form.
Modifying a flashboard
Follow the steps given below to modify a flashboard:
To modify a flashboard
2. Double-click Flashboards.
3. In the Flashboards list, double-click the flashboard name.
4. Make the necessary changes to the flashboard.
5. Save the flashboard.
Page 2673 of 4705
Home
Deleting a flashboard
Follow the steps given below to delete a flashboard:
To delete a flashboard
2. Double-click Flashboard.
3. In the Flashboards list, right-click the flashboard name, and select Delete.
Setting up notifications for a flashboard

This section provides information to setup the notifications for the flashboards that you create. An
alarm enables you to send notifications to specific users based upon a threshold value.
Creating alarms
Alarms can trigger notifications through email based on the threshold level of the associated meter.
The BMC Remedy Flashboards server checks the threshold, based on the Check interval. If the
threshold limit is reached, the server generates an entry in the Alarm Events form.
To create an alarm
2. Right-click Flashboard Alarms, and select New Flashboard Alarm.
To add an alarm to an application, expand serverName > Applications. Then, right-click on
the application, and select New Object > New Flashboard Alarm.
3. Use the following table to enter values in each field.
Fields used to create a flashboard alarm
Field
Description
Active
Enables the alarm if the option is selected.
Variable
Name of the variable associated with this alarm (required).
Threshold
Threshold level beyond which the alarm will trigger. Select an operator and enter an integer value,
depending on the type of statistics your flashboard gathers. For example, you might have a flashboard that
tracks the number of unassigned help desk tickets. Based on the number of unassigned tickets from
previous days, you know that you must assign tickets immediately if the number of unassigned tickets
reaches 50. So, you set the threshold level to trigger the alarm when the number of tickets reaches 50.
Remind
when
Frequency with which reminders are sent to the user defined in the Notify section of this panel, while the
threshold conditions are met (required).
Check
every
Amount of time that must pass before the variable value is checked to verify that the alarm conditions are still
in effect. The default value is 5 minutes.
Notify by
Delivery mechanism for the message that the alarm sends out when the trigger conditions are met:
Email (through BMC Remedy Email Engine)
User Default, which obtains the user's default mechanism from the User form
None
Page 2674 of 4705
Home
You might select None if you want to gather information in the FB:Alarm Events form to be analyzed at a
later date. You might also want to create workflow on the data.
User
Name of the user who receives the alert message or the email notification.
Message
Message that the alarm or email displays. You can click the ellipsis (...) button to open the Alarm Message
dialog box.
4. Save the alarm.
Modifying, disabling, or deleting alarms

Use the procedures in this section to modify, disable, or delete alarms.
To modify an alarm
2. Double-click Flashboard Alarms.
3. In the Flashboard Alarms list, double-click the alarm name.
4. Modify the data as needed.
5. Save the alarm.
To disable an alarm
1. Open the alarm.
2. Clear the Active check box.
3. Save the alarm.
To delete an alarm
2. Double-click Flashboard Alarms.
3. In the Flashboard Alarms list, right-click the alarm name, and select Delete.

The following sections explain more about adding a flashboard to a BMC Remedy AR System form:
Changing flashboard parameters
Flashboard parameter and value conventions
Changing display parameters for flashboards
Display parameters
Configuring a flashboard's display
Customizable parameters
Display parameters for charts
Identification parameters
Login parameters
Meter parameters
Page 2675 of 4705
Home
Time parameters
Using dynamic qualifications
Changing flashboard parameters

You can change field parameters in the Data Visualization field that holds the flashboard. You can
also use Set Field actions to modify flashboard fields at run time. For example, you might want to
change the flashboard data display from a bar chart to a pie chart, or attach a different flashboard
to the field.
Active links affect only the properties you modify, and the modifications you make apply only until
you close the form.
Note
If the server does not support the modifications you make, you might cause unexpected
results if you override the existing parameter values. Test your modifications before you
apply them.
Flashboard parameter and value conventions

Apply the following rules when you enter flashboard parameters or values into workflow or the
Custom Properties value for a Data Visualization field:
Type key names without regard to case sensitivity.
Enter dates in seconds since January 1, 1970 00:00:00 GMT for date/time related properties
. You cannot use values from date/time fields.
Note
The active link uses aliases for selection fields, such as radio buttons and menus, rather
than the enumerated values of the selection fields.
Enter the parameters and values without using spaces, and use commas to separate the
parameter=value pairs in the field values, for example:
chartType=0,chartTitle=TestFB
Use the following escape characters:
Escape characters for parameters
Active link value
Escape character for value
Example
comma (, )
comma
chartTitle=FB,,Test,chartType=0
double quote (" )
double quote (" )
chartTitle=FB""Mine"",chartType=0
Page 2676 of 4705
Home
Active link value
Escape character for value
Example
keyword
backslash
customqual='Submitter'=$\USER$
Changing display parameters for flashboards

This section contains two procedures that describe how to enter or change flashboard display
parameters in a Data Visualization field and in an active link. See Display parameters for a list of
all display parameters.
To enter parameters in a Data Visualization field

1. Create a Data Visualization field on a form as described in Adding a flashboard to a BMC
Remedy AR System form.
3. In the Properties tab, click Custom Properties, and enter a parameter and value using the
following format:
parameter=value
4. Save the form.
To enter parameters in an active link

1. Create an active link.
See Creating active links.
2. Add a Set Fields If action.
3. From the Data Source list, select the location of the Data Visualization field that references
the flashboard.
If you enter an option other than Current Screen, complete the other fields above the Field/
Value table as needed.
4. In the Field column, enter the name of the Data Visualization field that references the
flashboard.
Hint: Click the ellipsis (...) button to select from the available fields.
5. In the Value column, enter the parameters and values to apply to the field in the following
format (comma separated):
parameter= value
When you modify flashboard values, use the conventions in Flashboard parameter and
value conventions.
For more information about display parameters, see Display parameters.
Example
If you want to display the Chart1 flashboard in the Field1 Data Visualization field as a pie chart:
1. Enter Field1 in the Field column.
2.
Page 2677 of 4705
Home
2. Enter "flashboard=Chart1,chartType=5" in the value field OR Use the following field

reference to dynamically select the flashboard name from the FlashboardName character
field and chart type from the ChartType integer field:
"flashboard="$FlashboardName$",chartType="+$ChartType$
Display parameters
The tables in this section show the name and value of the parameters that you can change in
workflow or in a Data Visualization field (update the Custom Properties property value).
Each table specifies the type of flashboard to which the parameter is applicable (default format with
Flash technology or the format used in 7.0.01 and 7.1.00 versions of BMC Remedy AR System).
For more information, see Modifying flashboard properties.
Configuring a flashboard's display

To ensure a similar look and feel across BMC products, BMC Remedy Flashboards 8.1 has the
same color scheme and look as the BMC Dashboards product.
The following table describes parameters used if you want to display the colors and format of
flashboards from versions 7.1.00 and 7.0.01. For a list of properties that are supported in the
current and earlier versions of BMC Remedy Flashboards, see Modifying flashboard properties.
Parameters for display in earlier versions
Parameter
flashdisplay
Description
Value indicating whether to display the 7.5.00 and later version format
of BMC Remedy Flashboards, which is powered by Adobe Flash and
Powered by
Adobe Flash
Image-based
Default
format
and
color
scheme
7.1.00/
7.0.01
color
scheme
7.1.00/7.0.01
color and
format
enables users to manipulate the flashboards (by zooming, changing

the chart type, changing labels, and so on). The values are 0 and 1.
The default is 1--use the Adobe Flash format. To change the default
format and display to the format of the 7.1.00 or 7.0.01 version, enter:
flashdisplay=0
Note
If the flashdisplay parameter is not set, the value is
retrieved from the flashboards.showgraphinflash entry in
the config.properties file. The default is to display the
7.5.00 and later format: flashboards.showgraphinflash=1
defaultlookandfeel
Page 2678 of 4705
Home
Value indicating whether to display the default flashboard format (

which has the BMC Dashboards look and feel) with the default axes,
value labels, grids, gradient colors, title, legend, and background and
foreground colors and border. The values are 0 and 1. The default is 1
. To be able to customize parameters and use the colors from the
7.1.00 or 7.0.01 version, enter:defaultlookandfeel=0
The following table describes customizable parameters.
Parameter
Description
Powered by
Image
Adobe Flash
based
Default
format
7.1.00/
7.0.01
7.1.00/
7.0.01
and
color
color
color
scheme
and
format
scheme
customizable
Value indicating whether to display the user customization flashboard

option on the chart:
0 Do not display the flashboard customization option

1 Display the flashboard customization option If this option is
enabled, users see a flashboard that contains a Customize Chart
button and two fields that allow users to select the type of change
and the value for the change. The customize options and values are
:
Chart Title Any value.
Chart Type The values are:
Line Chart
Bar Chart
Stacked Bar Chart
Area Chart
Stacked Area Chart
Pie Chart
Legend Title Any value.
X Axis label Any value.
Y Axis label Any value.
The six default customizable options display automatically. See User Can
Customize and the description of the customizableparams parameter
that follows for more information about limiting the customizable options
that users see.
customizableparams
The parameters specified in the Custom Properties property for the Data
Visualization field.To use this parameter for a flashboard:

2. Select the Data Visualization field that references the flashboard.
3. In the Properties tab, click Custom Properties, and enter the
expression customizableparams= followed by the customizable
options to display (in lowercase and separated by single spaces).
Page 2679 of 4705
Home
For example, if you enter the following line, users can customize only the
chart title and chart type:
customizableparams=charttitle charttype
customQual
A custom qualification you specify that overrides the qualification defined
in the variable. See Using dynamic qualifications. The customQual

parameter is used for real-time data. If you want to query on scheduled
data, use varhistoryqual or varsummaryqual. To search for values that
are null, use the $NULL$ keyword in the qualification.
enableDrilldown
Value indicating whether to allow data drill-down:

0 Disable drill-down.
1 Enable drill-down.
prefixseriesnames
Value indicating how to include a prefix in series names for variables that
have a Group By option:
0 (default) The variable label and name appears only if a series
with the same name already exists. (This was the behavior for BMC
Remedy Flashboards prior to version 7.6.03.)
1 The variable label is added at the front of all series' names (set
by the Group By option) in the legend (if shown) or when the user
moves the cursor over the flashboard. If a label is not entered in the
Label field, the variable name is displayed.
Note
To add a label, enter it in the Label field on Variables panel when
creating or editing a flashboard.
varcustomqual
A custom qualification you specify that overrides the qualification defined

in the variable.
For example:
varcustomqual=varIndex1:customQual1:varIndex2:customQual2
varcustomqual=0:'4'="Demo":1:'2'="User"
varindex begins its numbering sequence at 0, and the index is the
position at which the variable appears on the Variables panel of the
flashboard in BMC Remedy Developer Studio.
Warning:
If you set the varcustomqual parameter to empty (), it overrides
customQual when you use both parameters at the same time. This can
lead to unexpected results.
vargbvalcolors
A parameter used to set custom colors to each value in a variable.

vargbvalcolors=varIndex1:val1-colorStr1-val2-colorStr2-...:varIndex2:...
vargbvalcolors=0:0-ff0000-1-00ff00-2-0000ff:1:
Demo-LHFF000000FF00-User-RVFFFFFF000000-...:2:...
varhistoryqual
A qualification used for scheduled data. The values are varindex and
historyqual, for example:
Page 2680 of 4705
Home
varhistoryqual=varindex1:historyqual1:varindex2:historyqual2
varindex is 0 to the number of variables in the flashboard, and the index is
the position at which it appears on the Variables panel of the flashboard in
BMC Remedy Developer Studio. The history qualification can contain the
following special fields:
Value The statistical value.
SampleTime The time at which the history sample was taken.
PrimaryGBVal The primary Group By value.
SecondaryGBVal The secondary Group By value (Even though
this value is not plotted, one can still use it for qualifications, history,
and summary).
For example:'SampleTime' > "10/10/2005" AND 'SampleTime' < "11/10/
2005" AND 'PrimaryGBValue' = "john"
varsummaryqual
A qualification used for scheduled data. The values are varindex and
summaryqual, for example:

varsummaryqual=varindex1: summaryqual1:varindex2:
summaryqual2
varindex is 0 to the number of variables in the flashboard, and the index is
the position at which it appears on the Variables panel of the flashboard in
BMC Remedy Developer Studio. The summary qualifications can contain:
Value The statistical value.
PeriodStartTime The starting time for the summary interval.
PeriodEndTime The ending time for the summary interval.
PrimaryGBVal The primary Group By value.
SecondaryGBVal The secondary Group By value.

The following table describes chart parameters.
Parameter
axisOrientation
Description
Axis orientation:
Powered by
Adobe Flash
Image-based
Default
7.1.00/
7.1.00/7.0.01
format
and
7.0.01
color
color and
format
color
scheme
scheme
0 X bottom Y left
1 X top Y left
2 X top Y right
3 X bottom Y right
4 Y bottom X left
5 Y top X left
6 Y top X right
7 Y bottom X right
Page 2681 of 4705
Home
backgroundColor
Background color, specified as a hexadecimal string in the format
RRGGBB, where RR, GG, and BB represent values for red, green
and blue, respectively.
chartBorderWidth
Width of the chart border in pixels.
chartTitle
Chart title.
chartType
Type of chart:
0 Line
1 Bar
2 Stacked bar
3 Area
4 Stacked area
5 Pie
display3d
Value indicating whether to display the flashboard in 3D:
0 Do not display in three dimensions (default).

1 Display in three dimensions.
displayTable
Value that indicates whether to display chart data in table form:
0 Do not display chart data in table form (default).

1 Always display chart data in table form.
endDate
Time frame custom end date, in seconds, since January 1, 1970,

00:00:00 GMT. You can change this parameter only if the
timeFrame parameter is set to Custom. Optionally, you can also
set the end date using the following format:MM/DD/YYYY HH:NN:
SS For example: endDate = 11/30/2011 16:55:11
Note
Applies only to trend charts.
fgTransparency
Foreground transparency level for the flashboard. This value must

be a real number between 0 and 1.
flashboardType
Type of flashboard to be displayed:
0 Chart
1 Meter
2 Text
foregroundColor
Foreground color, specified as a hexadecimal string in the

RRGGBB format, where RR, GG, and BB represent values for red,
green, and blue, respectively.
Note
You can specify the foreground color for meters, but not
for other types of flashboards.
Page 2682 of 4705
Home
gbcolors
Specifies the colors of the chart elements, such as individual bars,
for the Group By variables. The color order is dependent on the

Group By order. The gbcolors parameter is specified as a
hexadecimal list separated by spaces in the RRGGBB format,
where RR, GG, and BB represent values for red, green, and blue,
respectively. For example, a value of FF0000 designates a red
color, a value of 00FF00 designates a blue color, and 0000FF
designates a green color. The syntax for this example would be:
gbcolors=FF0000 00FF00 0000FF In this example, the resulting
chart displays a bar chart with red, blue, and green bars for the
corresponding Group By order.
height
Height of the flashboard image in pixels.
label
Label for meters or text boxes.
legendBorderWidth
Width of the legend border in pixels.
legendPlacement
Location of legend in display:
0 Right
1 Left
2 Top
3 Bottom
legendShow
Value indicating whether to display the legend:

0 Do not show legend (default).
1 Show legend.
legendTitle
String to be used as the legend title.
outlineLegendKeys
Value indicating whether to draw an outline around legend keys:
0 Do not draw outline.

1 Draw an outline (default).
rangeMaximum
Maximum Y axis value, if yAxisRangeAuto is:

Not set.
Maximum value on a meter.
rangeMinimum
Minimum Y axis value, if yAxisRangeAuto is:

Not set.
Minimum value on a meter.
showValues
Value indicating whether to show point values in flashboard:

0 Do not show point values on chart (default).
1 Show point values on chart (values display only in line,
bar, and pie charts, not in stacked charts).
sortType
Type of sorting:
0 (default) Do not use the sorting option.
1 Sort by Value.
Page 2683 of 4705
Home
2 Sort by Attribute.
sortOrder
Sort order:
0 Ascending (default)
1 Descending
sortAttribute
Text value from the secondary Group by field.
sortIsAttributeEnum
Whether the value of the secondary Group by field is enum or

non-enum:
0 Value in secondary Group by field is non-enum.

1 Value in secondary Group by field is enum.
startDate
Time frame custom start date, in seconds, since January 1, 1970,

00:00:00 GMT.
Note
This parameter is valid only when the timeFrame
parameter value is set to "Custom".
Optionally, you can set the start date using the following format:MM
/DD/YYYY HH:NN:SS For example: startDate = 11/30/2011 16:55:
11
Note
This parameter applies only to charts that show trends.
topgbnum
The number of primary Group By values to be drawn on the

flashboard and shown on the legend. The default value is 0, which
indicates that the top legend values are off.
topgbshowother
Value indicating whether to show or hide the "Other" item (the

consolidated series) and its values:
0 (default) Do not show the Other item; show only the
number of graph series set in the topgbnum parameter.
1--Show the Other item.
topgbsort
Value indicating the sort order for the legend:

0 Ascending order; shows the bottom n values (default).
1 Descending order; shows the top n values.
topgbotheralias
The alias for the "Other" Group By value in the legend and tooltips.
The default is Other. The format is as follows: topgbotheralias=
string
topggbothercolor
The color value to be used while drawing the "Other" item. The
default is auto color choosing. The format is as follows:
topggbothercolor= c olorString
Page 2684 of 4705
Home
The type of variable information to display:
varDataType
0 Real time
1 History
2 Summary
3 History till date
width
Width of the flashboard image in pixels.
xAxisLabel
Label to appear on the X axis. This parameter is not applicable to

pie charts, meters, and text.
xAxisShowGridLines
Value indicating whether to show gridlines on the X axis:
0 Do not show gridlines (default).

1 Show gridlines.
This parameter is not applicable to pie charts, meters, and text.
Value indicating whether to display time on the X axis:
xAxisTime
0 Do not display time.

1 Display time.
With xAxisTime set to 1, you can create a real-time-based chart
when you group by a date/time or date field.
yAxisLabel
Label to appear on the Y axis. This parameter is not applicable to

pie charts, meters, and text.
yAxisRangeAuto
Value indicating whether to automatically determine the range of

the Y axis:
0 Do not automatically determine range.

1 Automatically determine range (default).
yAxisShowGridLines
Value indicating whether to show gridlines on the Y axis:

0 Do not show gridlines (default).
1 Show gridlines.
The following table describes identification parameters.
Parameter
flashboard
Description
Name of the flashboard.
server
Image-based
Default format and

color scheme
7.1.00/7.0.01
color scheme
7.1.00/7.0.01 color
and format
Page 2685 of 4705
Home
BMC Remedy AR System server where you

created the flashboard.
Login parameters
The following table describes login parameters that you should use when no session is running.
Login parameters
Parameter
Description
Image-based
Default format and
7.1.00/7.0.01 color
7.1.00/7.0.01 color
color scheme
scheme
and format
auth
Authorization string for the BMC Remedy

AR System user.
locale
Browser locale.
pwd
BMC Remedy AR System login password

.
username
BMC Remedy AR System server login

user name.
Meter parameters
The following table describes parameters that apply to meters.
Meter parameters
Parameter
alertThreshold
Description
Percentage of the meter range dedicated to the alert
Image-based
Default format
and color
scheme
7.1.00/7.0.01
color
scheme
7.1.00/7.0.01
color and
format
threshold (red section).

label
Meter label.
meterType
Type of meter displayed:
+
+
0 Pie (part of a circle)

1 Circle (full circle)
2 Chord (half circle)
3 Thermometer
rangeMaximum
Maximum Y axis value of the variable if

yAxisRangeAuto is not set or is set to the maximum
value on a meter.
rangeMinimum
Minimum Y axis value of the variable, if

yAxisRangeAuto is not set or is set to the minimum
value on a meter.
title
Meter title.
Page 2686 of 4705
Home
warningThreshold
Percentage of the meter range dedicated to the warning

threshold (yellow section).
Time parameters
The following table describes time-related parameters for flashboards that display trends (history
and summary charts).
Time parameters
Parameter
Description
Powered by
Adobe Flash
Image-based
Default
format
7.1.00/
7.0.01
7.1.00/7.0.01
color and
and
color
color
scheme
format
scheme
customTimeFormat
Customized time format:
Y Year. If the number of pattern letters is two, the year is

truncated to two digits; otherwise, it appears as four digits.
The year can also be zero-padded. For example: Y = 05
YYYY = 2005
M Month in a year (localized). If the number of pattern
letters is one, the format is interpreted as numeric in one or
two digits. If the number of pattern letters is two, the format is
interpreted as numeric in two digits. If the number of pattern
letters is three, the format is interpreted as short text. If the
number of pattern letters is four, the format is interpreted as
full text. For example: M = 7 MM= 07 MMM=Jul MMMM= July
D Day in a month. A single-letter or two-letter pattern string.
For example: D=4 DD=04 DD=10
E Day in a week (localized). If the number of pattern letters
is one, the format is interpreted as numeric in one or two digits
; If the number of pattern letters is two, the format is
interpreted as numeric in two digits; If the number of pattern
letters is three, the format is interpreted as short text; If the
number of pattern letters is four, the format is interpreted as
full text. For
customTimeFormat
example: E = 1 EE = 01 EEE = Mon EEEE = Monday

A a.m./p.m. indicator
J Hour in a day (0 - 23)
H Hour in a day (1 - 24)
K Hour in a.m./p.m. (0 - 11)
L Hour in a.m./p.m. (1 - 12)
N Minute in an hour. For example: N = 3 NN = 03
S Second in a minute. For example: SS = 30
Q Quarter of a year. For example: QQ = 78 QQQ = 078
W Week number of the year. For example: WW= 31
Page 2687 of 4705
Home
To format the pattern string, you can add text to the string. You can
also use punctuation, numbers, and all lowercase letters. For
example:EEEE, MMM. D, YYYY at L:NN A = Tuesday, Sept. 8,
2005 at 1:26 PM
Note
Do not use uppercase letters because they might be
interpreted as pattern letters.
For information about other date and time formats, see Date and
time formats.
timeFormat
Browser time format:
0 Date and time is displayed.

1 Time is displayed.
2 Date is displayed.
timeFrame
Value indicating the interval to display if the X axis displays time:

0 All dates
1 Custom (specify the start and end dates)
2 Today
3 Yesterday
4 This Month
5 Last Month
6 Year to Date
7 Last Year
8 Last Week
9 This Week
10 Next Week
11 Next Month
12 Last Year by Month
13 Last Year by Quarter
14 This Year by Month
15 This Year by Quarter
16 Next Year by Month
17 Next Year by Quarter
timeView
Note
This parameter is valid only when the timeFrame
parameter value is set to Custom.
Data unit for displaying the chart:

Seconds
Minutes
Hours
Days
Weeks
Months
Page 2688 of 4705
Home
Years
Quarter
timeZone
Browser time zone.
Using dynamic qualifications

You can use the customqual parameter to enable dynamic qualifications in a form. For example,
suppose you create an AllDefects variable that tracks all bugs. You then associate the variable
with the Defect Tracking form, where defect information is collected. The Defect Tracking form has
a field named Assigned To.
You also create a flashboard that appears on a second form (Defect Console) to display the defect
information. The Defect Console form has a field called Submitter. The Submitter field is a
dynamic field whose value changes depending on who accesses the Defect Console form. In this
case, the field is populated with the name of the person who is viewing the defect assigned to him
or her. You must create workflow to populate the Submitter field with the $USER$ value.
For example, Chris, a coworker, wants to know how many defects are assigned to him. To enable
him to view the tickets assigned to him, you can use the customqual parameter for the flashboard
URL qualification in an active link. The customqual parameter enables dynamic qualification on
the Submitter field, so all submitters can view tickets assigned to them.
To enable dynamic qualifications

1. Open the active link that contains the Set Fields action you want to modify.
See Active links and Creating active links.
2. Open the Set Fields panel.
3. From the Data Source list, select the location of the Data Visualization field that references
the flashboard.
If you enter an option other than Current Screen, complete the other fields above the Field/
Value table as needed.
4. In the Field column, enter the name of the Data Visualization field that references the
flashboard.
Hint: Click the ellipsis (...) button to select from the available fields.
5. In the Fields section, type the customqual parameter expression in the Value field.
Generic syntax:
"customqual='FieldName'=" +""""+ $Field$+""""
Syntax for this example:
"customqual='Assigned To'=" + """" + $Submitter$ + """"
Page 2689 of 4705
Home
After saving the active link changes, Chris opens the Bugs Console. He sees the bugs
assigned only to him.
In the generic syntax example, FieldName corresponds to the Assigned To field (on the
Defect Tracking form), and $Field$ corresponds to the value of the Submitter field (on the
Defect Console form).
When you use the customqual parameter to enable a dynamic qualification on the value of
a selection field, set the qualification equal to the label value, not the alias value. (Using the
alias value generates an error while parsing the qualifier.)
Note
If you enter a qualification in the flashboard variable and use this procedure, the
qualification is overridden.
The changes you make affect only the current session. The original variable syntax remains
intact in the flashboard variable definition.
Securing your application

The following sections explain the details about securing your application:
Access control for a deployable application
Granting permission to applications and their objects
Related topics
The following section provides more information about security administration:
Access control for a deployable application

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 BMC Remedy 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 it's 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.
Page 2690 of 4705
Home
When a user attempts to reference a form, field, active link, active link guide, or web service, the
BMC Remedy 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 about 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
application's entry points. See Creating and managing fields.
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.
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.
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, to
these objects and fields as needed.
Page 2691 of 4705
Home
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 form's
permissions, from the permissions of its fields, and from all active links and active link guides
associated with the form.

This section explains the following topics:
Introducing workflow
Configuring workflow forms and execution options
Building qualifications and expressions
Specifying workflow actions
Workflow processing
Workflow extras
Introducing workflow
This section introduces the three BMC Remedy AR System workflow objects: active links, filters,
and escalations. By using workflow, you can define a set of processes to enforce business rules
such as approval and service level requirements, tracking defects or assets, and so on.
For background information about workflow, see Workflow overview. For more information about
workflow, see the following sections:
Workflow basics
Workflow objects
General procedures for workflow objects
Graphical representation of workflow events
Shared workflow
Workflow basics
BMC Remedy AR System server workflow consists of active links, filters, and escalations that carry
out business processes. For information about what these three main types of workflow, see
Workflow objects.
All workflow objects include the following elements:
Page 2692 of 4705
Home
An associated form is the basis for every workflow action. Sometimes a workflow object
has more than one associated form, but one form is defined as the primary form and acts as
the reference for fields and data used by the workflow. See Configuring workflow forms and
execution options and Shared workflow.
Workflow execution options determine when the workflow runs. See Configuring workflow
forms and execution options.
Run If qualifications (optional) determine whether the workflow's If Actions or Else Actions
are carried out. See Using buttons and menu bar items to execute active links .
Workflow actions determine what an active link, filter, or escalation does when it runs. See
Using buttons and menu bar items to execute active links .
You can use active link guides and filter guides to control the order of workflow actions and
organize a related set of workflow objects. See Creating and managing fields.
Active links allow you to create workflow designed for user interaction. You can use buttons and
field menus with active links to assist the user. See Using buttons and menu bar items to execute
active links.
For information about how BMC Remedy AR System server processes, active links, filters, and
escalations, see Using buttons and menu bar items to execute active links .
Workflow objects
Workflow objects automate your organization's business processes. You can create active links,
filters, and escalations to perform actions on one form or several forms. When workflow is attached
to multiple forms, it is considered shared workflow. See Shared workflow for more information.
Active links, filters, and escalations share many similarities, but also have several differences that
are described in this section.
Active links
Filters
Escalations
Workflow comparison
Active links
An active link is an action or a series of actions that are triggered when a user performs an
operation and are conditionally interpreted. The interpretation occurs on the BMC Remedy AR
System client in the current form window, and run with the permission of the user. For example, you
might define an active link that displays a list of all problems reported for the current workstation
whenever a user presses Enter in the Workstation field.
When an active link is executed, it can trigger varying actions as the result of a single user action.
Page 2693 of 4705
Home
When you design an active link, you specify the conditions under which the active link executes,
and further conditions to determine which action it will take. For example, if the user is a member of
the Human Resources department, an active link could attach one menu to the Short Description
field, or else attach a different menu if the user is a member of the Shipping department.
Active links can be grouped into execution groupings called active link guides that allow procedural
processing.
Note
Active links cannot be triggered through the use of an API program.
Filters
Filters implement and enforce your organization's business rules. A filter tests every request
transaction to see if certain conditions are met, and then responds to the conditions by taking
specific actions. For example, a filter can notify support staff members when they are assigned
responsibility for a new request.
Filters can act on virtually any condition that arises in a request. For example, filters can restrict
how users create or modify a request. As another example, a filter can check for conditions in
requests that are submitted by a network management system for a device that the system is
monitoring. Then, the filter can automatically call a program to control that device.
Filters execute on the BMC Remedy AR System server and run with administrator permissions.
This means that filters can access any field in the BMC Remedy AR System server database, even
if the field is not available to the user (no view or change access).
Filters can be grouped into filter guides to control the order of processing. For more information,
see Defining guides and guide actions.
Escalations
An escalation causes a condition to be checked on a regular basis and, depending on whether and
how the condition is met, performs one or more actions. For example, an escalation can set the
priority of a request to Urgent if the request is not closed within 24 hours, or send a page to a
support staff member if a critical request has not been addressed in one hour.
Escalations execute on the BMC Remedy AR System server and run with administrator
permissions. Unlike filters, which run in response to a specific operation, escalations run at a
specific time or after a defined time interval. Also, when they run, escalations find and act on all
requests that meet a qualification, while filters act on the current request if it meets a qualification.
At the time specified in the escalation, BMC Remedy AR System server searches for requests that
Page 2694 of 4705
Home
match the escalation qualification and performs the specified escalation actions on those requests
that match.
Escalations can be assigned to pools so the escalations from each pool run in parallel on separate
threads within the escalation queue. To use escalation pools, you must first configure multiple
threads for the escalation queue as described in AR System server queues. If you assign an
escalation to a pool that has no thread configured, the escalation is run by the first thread.
All escalations in a particular pool run on the same thread, so the execution of escalations within a
pool is serialized. Escalations run in the order of their firing times, but an escalation is delayed if an
escalation from the same pool is currently running. If two or more escalations have dependencies
and must not run at the same time, put them into the same pool to make sure they run in sequence.
Workflow comparison
The following table summarizes the functionality of active links, filters, and escalations.
Workflow comparison
Active Links
Filters
Escalations
Where
performed
Client, current form

window
Server
Server
Executed
by
A user performing an
action
A specific operation
A specific time
Purpose
Help the user to do

something
Implement and enforce business rules
Initiate and ensure timely actions
What they
do
Start a series of actions

that are conditionally
interpreted.
Test every server transaction on the

form to see if conditions are met in
the current request, and respond by
taking specific actions.
At a specified time or time interval, check

whether conditions are met for requests
existing in the form, and if so, perform actions
on requests that meet conditions.
Run with
User
Administrator
Administrator
Populate all name and

address fields when
Notify support staff members when

they are assigned a new request.
Page a support staff member if a Critical

request has not been addressed in one hour.
permissions
of
Example
user presses Enter in

Last Name field.
General procedures for workflow objects

You create and manage workflow objects in BMC Remedy Developer Studio. Although active links,
filters, and escalations have different purposes and properties, many procedures for working with
them are the same.
This guide describes some common procedures for working with workflow objects. Other common
procedures are described in other documents, as shown in the following table.
Page 2695 of 4705
Home
Where to find information about workflow objects

For Information about
See
Creating, copying, renaming, and deleting BMC Remedy AR System server objects
Application development with BMC

Assigning permissions (enables you to specify users and groups who can access an object
)
Workflow object properties and

Assigning permissions.
Entering change history (a record of an object's owner, the user who last modified the
Updating change history.
object, and the date of modification)

Creating and modifying help text for objects
Providing help text.
Creating a log file for tracing object activity (You can create a record of an object's
Tracing active link, filter, or
operation, including what executed and whether it was successful.)
escalation activity.
Using the workflow editor in BMC Remedy Developer Studio

When you open an active link, filter, or escalation, it appears as the active tab in the editor area of
BMC Remedy Developer Studio. The information that defines the workflow object is organized into
collapsible panels that you open to modify the object. The following figure shows the workflow
editor, with the active link Sample:ShowAllClasses open in the active tab.
The workflow editor with open workflow objects
You can open multiple editing panels to create or modify the active links, filters, and escalations
that you have permission to administer. In the following figure, a new active link, the filter Sample:
Enroll, and the escalation Sample:SetToCompleted are also open.
Tip
To maximize the editor, double-click the tab. You can also use the Editor perspective in
BMC Remedy Developer Studio to make the editor area larger. See Opening an object for
editing.
The tab label for each workflow object displays the following information:
Page 2696 of 4705
Home
When you create a new object, the tab label indicates whether you are working on an active
link, filter, or escalation.
The tab's icon also indicates whether the open object is an active link, filter, or escalation.
After you save the workflow object, the tab label displays the name of the object.
When you make changes to a workflow object, an asterisk indicates that the changes have
not been saved. When you save the object, the asterisk disappears.
When you save a new active link, filter, or escalation, the workflow object title changes to include
the name of the object and the server it is located on. If the object is part of an application, the
application name also appears in the object title.
The following table provides an overview of the settings located in each of the expanding panels in
a workflow object.
Workflow editor panels
Panel label
Active links
Filters
Escalations
Associated forms See

Associating workflow
objects with forms.
Select the form or forms associated with the active link, filter, or escalation.
Identify the primary form, if there is more than one associated form.
Execution options
See Defining workflow
execution options.
Set the state to Enabled or
Set the state
Set the state to Enabled or
Disabled.
Select the user actions and
associated fields (including
buttons and menu options)
that execute the active link.
Select the execution order
and interval, if any.
to Enabled or
Disabled.
Set the escalation pool number, if
any.
Define the escalation time criteria,
including whether the escalation
runs at the specified days and
times, or at an time interval.
Run If See Using

buttons and menu bar
items to execute active
links.
Error handler See
Error handling filters.
Disabled.
Select the
actions that
cause the
server to
execute the
filter.
Select the
execution
order.
Define the Run If conditions that determine whether the active link, filter, or escalation will run.
Not applicable
Not applicable.
Enable or
disable the
use of an
error handler.
Select the
error-handling
filter, if any.
If Actions See Using

buttons and menu bar
items to execute active
links.
Define the actions that execute when the Run If conditions are met.
Page 2697 of 4705
Home
Else Actions See

Using buttons and
menu bar items to
Define the actions, if any, that execute when the Run If conditions are not met. The Else action is
optional.
execute active links.
Graphical representation of workflow events

The Event Navigator and Workflow Execution Viewer interfaces have been introduced in BMC
These interfaces are supported for version 7.6.04 or later of the BMC Remedy AR System server.
Context menus that enable you to launch the Workflow Execution Viewer and Event Navigator are
available only if you select Record Object Relationships on the Configuration tab of the AR
For more information, see Setting administrative options.
The following sections provide more information about these interfaces:
Workflow Execution Viewer
Event Navigator
Launching the Workflow Execution Viewer

Application developers often need to understand how workflows associated with a single form are
linked to each other, or how one workflow triggers some other workflow of a different form. In this
regard, the Workflow Execution Viewer enables developers to do the following, without having to
open forms and workflow objects:
Generate a graphical representation of a workflow process, known as a workflow diagram.
Document the flows and objects in a workflow.
See Launching the Workflow Execution Viewer.
The workflow diagram depicts a series of activities, with an event as the starting point followed by
sequential flow of control from one workflow object to another. Workflow objects appear in their
order of execution. The workflow diagram ends when the last workflow object completes its
execution.
Developers can expand each workflow object to view the actions and conditions involved. Workflow
actions are executed in sequence.
Page 2698 of 4705
Home
The Workflow Execution Viewer is an editor that is always in the read-only state, and appears at
the center of the workbench. It can utilize the maximum available space, which helps to view
workflows that expand horizontally and vertically, when a developer drills down into a workflow.
This section describes the following aspects of the Workflow Execution Viewer:
Events depicted in the Workflow Execution Viewer
Elements of the Workflow Execution Viewer
Operations in the Workflow Execution Viewer
Events depicted in the Workflow Execution Viewer

The Workflow Execution Viewer depicts Form events and Side-effect events.
Form events
A form event could be one of many events that occur in sequence, in which case previous events
might affect the current event. For example:
When a form is opened, depending on the mode, the On Window Loaded event occurs,
followed by On Display or On Window Opened.
When an Apply action is performed, depending on the mode, the active link Modify or active
link Submit, active link After Modify or active link After Submit, and Filter On Submit events
occur sequentially.
For more information about form operations, see Active link processing.
The following table lists the form events (excluding those triggered by user actions) that can be
depicted in the Workflow Execution Viewer.
Form operations depicted in the Workflow Execution Viewer
Super
event
Launch
Form
for New
Launch
Form
for
Search
Component
events
AL: On
Window
Open
AL: On
Window
Loaded
AL: On
Set
Default
AL: On
Window
Description
This super event is triggered if the Open Window action is defined on the form to open the same form
or another form; the On Set Default active link is triggered only if the option to set fields to default
values is specified in the Open Window action for the Search or Submit window types.
Open
Page 2699 of 4705
Home
AL: On
Window
Loaded
AL: On
Set
Default
Launch
Form
for
Modify
AL: On
Window
Open
AL: On
Window
Loaded
AL: On
Set
Note
The active link is invoked twice in the second instance of On Window Open.
Default
AL: On
Search
AL: On
Window
Close
AL: On
Window
Open!
Filter:
On Get
Entry
AL: On
Display
Save
Modified
Save
New
AL-On
Modify
FilterOn
Modify
Filter-On
Get
Entry
AL-On
After
Modify
AL-On
Submit
Filter-On
Submit
Filter-On
Get
Entry
AL-On
After
Submit
This super event can occur when a user invokes the Save action (or the workflow performs a commit
action) in Modify mode.
Filter-On Get Entry is invoked only if the AL-On After Submit handler is defined. AL-On Set Default
depends on the user preference. Set Default processing occurs only if the Set Default option has
been specified for an Open Window action.
Page 2700 of 4705
Home
AL-On
Set
Default
Search
This super event is triggered when a user performs a search action on the form.
AL-On
Search
AL-On
Window
Close
AL-On
Window
Open
Filter-On
Get
Entry
AL-On
Display
Side-effect events
Actions in the workflow objects can trigger some other events, for example:
The Gain Focus event on a field can cause a Lose Focus event on some other field, which is
difficult to capture.
The Change Field action can trigger many events like Table Refresh, Gain Focus, and so on
, which might have further workflow associated with them.
The Push Fields action can trigger Modify, Submit, or Create events on the server, which in
turn might have many filters associated with them.
A Service Action almost always causes filters to fire.
Some special Run Process commands in active links can trigger events.
When creating a workflow, application developers can benefit from viewing events (and the related
workflow objects) that could possibly be triggered. To do so, developers can introduce related
diagrams into the Workflow Execution Viewer on demand.
Elements of the Workflow Execution Viewer

The Workflow Execution Viewer contains items that depict the various elements in workflow like the
form and object for which the workflow is defined, the qualifications and actions in a workflow, and
so on.
The following figure depicts the following elements in the Workflow Execution Viewer:
1. Form node Appears as rectangle that contains the form type icon (regular, join,
display-only, vendor, or view) on the left and the form name on the right. It represents a form
object, and is included to show the source of an event. In most cases, a form and its fields
are the sources of events.
2.
Page 2701 of 4705
Home
2. Transition Appears as a simple, directed line. The arrow head in a transition indicates the
direction of flow of control between actions within a workflow object or between workflow
objects.
Some transitions have labels associated with them. A label could be an event name, which
indicates that the following workflow is triggered on that event. A label could also indicate the
condition on which the transition occurs. For example, a transition from a Run-If qualification
to the first action in the workflow can be labeled "Y," indicating that the transition occurs if
the Run-If condition is satisfied.
If accompanied by a plus sign
, it indicates that super events are associated with the
parent node. Click the plus sign to launch the super events.
3. Workflow object node Appears as a rectangle that contains the object type icon (active
link, filter, or escalation) on the left and the object name on the right. The number on the
node represents the execution order of that workflow object. If accompanied by a plus sign (
+ ), it indicates that the node can be expanded to views its qualifications and actions.
4. Qualification node Appears as a rhombus that contains the qualification name. Depending
on the possible outcomes, one or more flows can originate from a qualification node.
5. Action node Appears as a rounded rectangle that contains the action name. If
accompanied by a plus sign
, it indicates one of the following:
The action node has side-effect events associated with it; click the plus sign to launch
the side-effect events.
The action node indicates a Call Guide action; click the plus sign to expand the
details-the guide name and its associated actions are displayed.
6. End of workflow Appears as two concentric circles (with a filled inner circle), indicating
that the workflow actions have been completed and no further activity will take place for this
workflow.
A form event displayed in the Workflow Execution Viewer
Generally, after the execution of a workflow action is completed the flow proceeds to the next action
. However, in some cases, the flow might not proceed sequentially. For example:
If the workflow being executed is contained in a guide, then actions such as Exit Guide and
Goto Label can cause the flow to proceed either to the end of the guide execution or to some
other node in the guide.
Page 2702 of 4705
Home
For a Push Fields or Set Fields action, if a side-effect event is defined for the records that
match the Run-If qualification, a plus sign appears next to the node. You can click the plus
sign to expand and view the side-effect event.
If a developer specifies the Display 'No Match' Error option, then the workflow diagram
depicts that:
The flow associated with the failure of this qualification proceeds directly to the end of
the workflow node.
The flow associated with the success of this qualification proceeds to the next action.
For a Message action, if the message type is Error, then the flow proceeds directly to the
end of the workflow node.
Operations in the Workflow Execution Viewer

You can perform the following operations in the Workflow Execution Viewer:
Open Right-click a node and select Open from the context menu to open the object in an
editor. For example, an action node opens in the workflow editor.
Document Select one or more nodes and select Document from the context menu. The
Document Objects dialog appears with the selected nodes already added to the Select
Objects panel. You can then proceed to document the selected objects by using the
Documenter tool.
Save As Image File Select a node or right-click anywhere in the blank editor area and
select File > Save As Image File from the context menu. The Save As Image File dialog
box prompts you to provide a file name, location, and format. The diagram is saved in the
current state nodes are neither expanded nor collapsed when saving. You can also export
the entire workflow diagram or the selection to HTML by using this menu.
Print Select one or more nodes and click File > Print. On the Print dialog, select an
option from the Diagram Print Range. Alternatively, right-click an empty region in the
Workflow Execution Viewer and use the File > Print context menu.
Expand or Collapse Select Expand or Collapse from the context menu of a node. The
Expand action expands a node and all its children; it expands the current activity but not its
related activities. The Collapse action collapses all the child nodes of the selected node.
If you select the Expand or Collapse context menu from a blank area in the workflow
diagram, all the nodes in the diagram are expanded or collapsed, except side-effect events,
super events, and active link or filter guides.
Zoom Use the Zoom In or Zoom Out toolbar buttons to zoom in or zoom out of the current
diagram.
Refresh Click Refresh to reload the entire workflow diagram. This operation reloads the
workflow only if it was modified after being opened in the Workflow Execution Viewer.
Show workflow details Hover over an action node to see its workflow details as a tool tip.
The tooltip displays details similar to those seen in the active link, filter, and escalation
editors when their actions are in the collapsed state.
Page 2703 of 4705
Home
Marquee Use the Marquee tool to select one or more nodes in the Workflow Execution
Viewer. A dotted rectangle appears when you click and drag the mouse in an empty region,
and all the nodes located in that region are selected. To select a node, you need to cover the
complete area of that node; it does not get selected if you drag the mouse partially over the
node.
The Marquee tool is useful when you want to perform the Save As Image File, Open,
Document, Expand, or Collapse operations on multiple nodes (those selected by the
marquee and not all the nodes or a single node).
Launching the Workflow Execution Viewer

The Workflow Execution Viewer is associated with events because workflows are executed on:
Field events like Gain Focus, Button Click, Menu Choice, and so on
Form events like Submit, Merge, On Display, and so on
Time-based events like at certain intervals or on certain calendar days
To launch the Workflow Execution Viewer from the Form editor

If you know the exact field with which the workflow is associated:
1. Open the appropriate form in the Form editor.
2. From the context menu of the field, select Show Workflow > eventName.
If the field does not have any workflow associated with it, the context menu appears as
Show Workflow > No Workflows.
The Show Workflow menu is also available in the Outline view.
Note
The Show Workflow menu is not available for newly created forms and fields
unless you commit the changes so that they are saved on the server.
To launch the Workflow Execution Viewer from the Event Navigator

If you know the exact form and event to which the workflow is related:
1. From the context menu of the form in the Object List view, select Show Event Navigator.
The Show Event Navigator menu is also available for fields listed in the Outline view.
2. From the context menu of an event in the Event Navigator, select Show Workflow.
Note
The Show Workflow menu works only with a single event. If you select multiple
events in the Event Navigator, this menu is disabled.
Page 2704 of 4705
Home
Shared workflow
In BMC Remedy AR System server, all workflow (active links, filters, and escalations) is based on
forms. Workflow can be attached to one or multiple forms. For example, you can create an
employee information active link that populates generic identification and address fields anytime a
user enters a name or use this on multiple forms.
Shared workflow lets you efficiently build, maintain, and troubleshoot versions of forms and
applications. Fewer workflow objects need to be stored on the server because any changes you
make only need to be made once for all forms that use the objects.
Warning
Use caution when sharing active links among forms in different deployable applications.
Role permissions are resolved based on which application has ownership . The
deployable application that contains the active link's primary form owns that active link or
active link guide. If the non-owner application has identical roles mapped to different
groups, these mappings are ignored. If only implicit groups have permission (no role
permissions), there are no conflicts. For more information, see Access control.
The way you define shared active links, filters, or escalations is similar to the way you define
workflow for an individual form. The main difference is that instead of attaching the workflow to one
form, you attach it to multiple forms. If you do not want the workflow to be shared, select only one
form. See Associating workflow objects with forms.
Workflow actions interact with fields based on field ID (not the field name). Plan carefully how you
will use shared workflow before attaching it to multiple forms. To make it easier to administer
shared workflow, create fields with the same ID and the same field name on each form. Otherwise,
the workflow might not fire or the shared workflow actions might still be triggered but might not use
the expected field. If fields have matching IDs but are different data types, BMC Remedy AR
System server attempts to convert them appropriately.
After you have created a form with which you want to share workflow, you can:
Create a new workflow object and then attach it to the forms.
Select an existing workflow object and then attach it to the forms.
When exporting definitions, you can choose whether to maintain an association between the
selected workflow and all related forms. For more information, see Importing and exporting object
definitions and locking objects.
Page 2705 of 4705
Home
When you delete a form that uses non-shared workflow, the workflow is deleted along with the form
. However, if workflow is shared by multiple forms, it is not deleted until the last form that uses it is
deleted.
Configuring workflow forms and execution options

This section describes how to associate a workflow object with a form, how to select the execution
options for the workflow object, and how to set the time criteria for an escalation. It also briefly
describes the properties of workflow objects.
Associating workflow objects with forms
Defining workflow execution options
Workflow object properties
Saving and copying workflow objects
Associating workflow objects with forms

Because BMC Remedy AR System server workflow enforces business rules based on data that is
stored in forms, all workflow objects must be associated with at least one form. To associate a form
with a workflow object, use the Associated Forms panel.
To associate a workflow object with a form

1. Open an existing active link, filter, or escalation, or create a new one.
2. Expand the Associated Forms panel if it is not already expanded.
3. Click Add.
4. In the Form Selector, select the form to associate with the workflow object, and click OK.
Tip
To locate a form quickly in a long list, you can use the Filtering Options or the
Locate field in the Form Selector dialog box. See To filter the contents in an object
list.
5. To associate the workflow object with an additional form, repeat steps 3 and 4.
The workflow object is attached to all of the forms you select. The first form you select
automatically becomes the primary, or reference, form for the active link, filter, or escalation.
See Primary form overview.
6. To change the primary form in cases where you have associated more than one form to the
workflow object, select a different form from the Primary Form drop-down list.
Page 2706 of 4705
Home
Primary form overview

All field references in the workflow refer to the primary form (also called the "reference form"), and
these fields appear in the other panels as you define the workflow object. If you associate more
than one form to a workflow object, make sure that any fields appearing on both forms have the
same field ID on each form.
Shared workflow can use fields from the other associated forms that are not on the reference form,
but you must define them by entering the field ID rather than the name. BMC recommends that you
avoid doing this, however, because it makes applications more difficult to maintain.
Defining workflow execution options

The Execution Options panel contains settings that determine when the active link, filter, or
escalation runs. For active links and filters, you specify what event or events trigger the workflow;
for escalations, you specify the execution schedule for the workflow.
For all three workflow components, you can refine the execution options by adding a qualifying
statement in the Run If panel. For information about creating a Run If qualification, see Using
buttons and menu bar items to execute active links .
Examples of how you might use execution options include:
An active link executes when the user presses Enter in a specified field or clicks a button on
the form.
A filter executes when a user submits a request.
An escalation executes when a request more than eight hours old has not been closed by
support personnel.
Creating active links
Creating filters
Creating escalations
Creating active links

Active link execution options cause the active link to execute based on actions taken by the user.
Some actions are specific to the open request or open window, while other actions are associated
with fields in the referenced form. The following figure shows the execution options panel for an
active link.
If an active link is part of a guide, you do not need to select an execution option.
Active link execution options
Page 2707 of 4705
Home
To define the execution options for active links

1. Open an existing active link or create a new one.
2. Make sure there is an associated form selected. Select one in the Associated Forms panel if
necessary. See Associating workflow objects with forms.
3. Expand the Execution Options panel.
4. Set the State field to Enabled or Disabled.
When the state is Enabled, the active link becomes active as soon as it is saved. You might
want to set the state to Disabled during development or when troubleshooting.
5. If necessary, enter a number in the Execution Order field.
The value that you enter in the Execution Order field determines the order in which this
active link is executed relative to other active links with the same triggering conditions.
Numbers between 0 and 1000 are valid execution order values; lower numbers are
processed first. The default value is 0.
6. Select the execution options for request and window actions, if any.
The execution options for request and window actions that trigger active links are described
in the following table. You can select any combination of these execution conditions, or none
of them, as appropriate. If you select multiple options, the active link or filter executes when
any one of the selected operations occurs.
7. Define the execution options for field actions, if any. To do so:
a. Click the Field ellipsis button.
The fields that appear in the field list are taken from the Primary Form defined in the
Associated Forms panel.
To locate a field quickly in a long list, use the Filtering Options or the Locate field in
the Field Selector dialog box. See To filter the contents in an object list .
Tip
Instead of clicking the ellipsis button, you can also press Ctrl+Space with
the cursor in the Field field. This brings up a list of the available fields from
the form. Begin to type the field name to narrow the list, and then select the
field you want.
b.
Page 2708 of 4705
Home
b. Select the appropriate field from the Field Selector dialog box and then click OK.
When you select a field, the field execution options appropriate to the field type
become active. The field-based, button, and menu execution options for active links
are described in the following table.
c. Select one or more field execution options for the field.
8. To cause the active link to execute when the user clicks a button:
a. Click the Button/Menu Field ellipsis button.
b. Select the appropriate button field and then click OK.
Tip
You can also associate an active link with a button by selecting the active
link in the button's field properties.
9. In the Interval field, select an execution interval, if any. The minimum interval is three
seconds, and the maximum interval is 7200 seconds.
When this is selected, the active link executes when the form is open at the specified time
interval. (If two or more active links on a form have the same interval, they execute at the
same time unless the execution order is set.)
Warning
In workflow triggered by the Interval condition, avoid the use of Message actions
and Open Window (of type Dialog) actions. This is to prevent an uncontrolled loop
of messages or opened windows, which could consume resources on the client
computer and make it difficult for the user to close the form.
The following table describes active link execution options relevant to request and window
actions.
Active links: Execution options for request and window actions
Execution
option
Description
After
Executes when a user modifies an existing request and after the request is written to the database. If the
Modify
modification fails, the active link is not executed. (The active link does not execute during a Modify All
operation.)
After
Submit
Executes after a user submits a new request and after the request is written to the database. If the
submission fails, the active link is not executed. If you use this condition for a set fields action on the current
entry, the set value is not stored in the database.
Display
Executes after an existing request is loaded into a form, but before the request appears in the Details Pane.
Event
Page 2709 of 4705
Home
Executes when a window has changed its application state, for example, when one window wants to send
an event to one or more windows; when one window has caused data to change and another window
references that data; or when one window is closed and other windows must be notified. This capability
allows one part of an application in a client environment to notify other parts that an "event" has occurred.
Other parts of the application can then react by performing actions such as refreshing table fields. The
Event condition provides a mechanism in the context of a single client environment (for example, in a web
client) for a parent window to be notified when a child window has been closed, so that workflow can refresh
related data on the parent window. Events are constrained to the client environment. Windows in two
separate client environments cannot send messages to each other. See Ability to highlight required fields
through workflow.
Warning
In some cases, event driven workflow can fail when executed on the mid tier. To avoid this issue,
explicitly define the parent-child relationship.
Modify
Executes when a user modifies an existing request. The active link is executed before the request is sent to
the server. (The active link does not execute during a Modify All operation.)
Search
Executes when a user performs a search operation. The active link executes before the search operation so
that, if the active link criteria is not met, the If actions are not performed. (If Else actions exist, they are
performed.) To prevent a specific search from occurring (such as an unqualified search), you can have the
active link return a message (such as an error); otherwise, the search is performed. You can also use active
links to set fields to modify the search.
Note
The active link can access and assign values in the Search window, including the Search Bar if
the reserved Search Bar field is present on the form.
Set
Default
Executes when the user selects Edit > Set to Defaults from the menu bar. It can also happen after Window
Open if default field values have been set in the form through user preferences.
Submit
Executes when a user submits a new request. The active link is executed before the request is sent to the
server.
Un-Display
Executes when a request is removed from the Details pane because a new request was selected in the
Results pane or because the window is closing. The workflow actions execute before the request is
removed from the form.
Window
Closed
Executes when a user closes a window.
Window
Loaded
Executes after all the data values have been loaded into a Submit or Search window (from defaults, from a
Copy to New action, or from an Window Open action).
Window
Open
Executes when any of the following actions occur:

A form window opens in New, Search, Modify, or Modify All operation mode.
The mode of the Detail pane switches to New, Search, Modify, or Modify All mode.
The form is opened by using the Open Window action.
This is useful for establishing the initial environment when a user opens a new window or changes
modes. The active link is executed before any data is loaded into the window, except when the form
is opened in Dialog mode by the Open Window action.
Page 2710 of 4705
Home
Note
If you use a Set Fields action with the Window Open condition, the set fields values might
be deleted if the user preference is set to Clear All Fields On Search or On New. To avoid
this when using a Set Fields action, use the Window Loaded execution option, which
executes after preferences are loaded, instead.
The following table describes active link execution options relevant to field actions.
Active links: Field-based execution options
Execution
Description
option
Button/
Menu
Field
Executes when a user selects a button or a menu button.
Collapse
Appears when the selected field is a Panel field type.

For Accordion and Stacked panel fields, executes when the user collapses a panel field.
For tabbed panel fields, executes with the user leaves the tab.
For a panel field of the Splitter type, this option causes no action.
Drag
Executes when the mouse moves over a field, and the user presses the left mouse button and drags the
mouse. See Allowing data to be dragged and dropped.
Drop
Executes when the left mouse button is released over a "droppable" field after being dragged from a "
draggable" field. See Allowing data to be dragged and dropped.
Expand
Appears when the selected field is a panel field type.

For Accordion and Stacked panel fields, executes when the user expands a panel field.
For Tabbed panel fields, executes when the user selects the tab.
For a panel field of the Splitter type, this option causes no action.
Gain
Focus
Executes when the specified field receives the focus. If you select this option, the Field list is enabled so
that you can specify the field that causes the active link to execute.
Note
If you use the Gain Focus condition to execute an active link on a view field, the active link might
not execute as expected. This is because the HTML page in the view field is taking the focus.
If the Gain Focus option is defined on a column field and if the table does not currently have focus, the Gain
Focus is also fired for the table. For example, if a table has columns A and B and if the current focus is on
column A and the user shifts focus to column B, the Gain Focus is not fired on the table because the table
already has the focus. However, if the current focus is on another field outside the table and the user shifts
focus to a column inside the table, the Gain Focus will be fired for the table.
Note
This Gain Focus option for column fields is applicable only for cell based and list view tables. For
list view tables, only the columns with display type not set to "read only" fire focus events.
Page 2711 of 4705
Home
Hover On
Field
Executes when the user hovers the mouse pointer over a field, field data, or a field label in the web client.
Along with the Message active link action, enables the use of tooltips to display a brief informational
Hover On
Data
message. If the selected field is a data field, all three options are enabled. If the selected field does not have
distinguishable label and data areas, only the "Hover on field" option is enabled. For information about
Hover On
Label
creating tooltips, see Message action.
Level
Choice
Appears when the selected field is a tree-view table field type. Executes when a user selects a level in the
tree.
Level
Appears when the selected field is a tree-view table field type. Executes when a user double-clicks a leaf in
Double
Click or
a tree view table or selects a leaf and then presses Enter to drill down to the source for

BMC Remedy Action Request System 9.0 en

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

BMC Remedy Action Request System 9.0 en

Caricato da

Copyright:

Formati disponibili

BMC Software Confidential