BMC Remedy AR Systems 8.1.00 Online Documentation PDF

BMC Software Confidential
BMC Remedy Action Request System 8.1
Date: 29-Jan-2014 14:56

URL: https://docs.bmc.com/docs/display/ars81/Home
Home BMC Software Confidential
Table of Contents
1 Featured content _____________________________________________________________________ 28
2 Where to start ________________________________________________________________________ 29
3 About BMC Remedy AR System ___________________________________________________________ 30
4 About BMC Remedy Encryption Premium Security ____________________________________________ 31
5 About BMC Remedy Encryption Performance Security _________________________________________ 32
6 About BMC Remedy Migrator ____________________________________________________________ 33
7 What's new __________________________________________________________________________ 34
7.1 Urgent issues _____________________________________________________________________ 34
7.1.1 Issue when using BMC Remedy IT Service Management Suite 8.1 on Microsoft Windows 8.0 with IE
10 or Microsoft Windows 8.1 with IE 11 ___________________________________________________ 35
7.1.2 Issue while logging in to the BMC Remedy IT Service Management application _____________ 35
7.2 Documentation updates ____________________________________________________________ 36
7.2.1 Added BIRT report documentation _______________________________________________ 36
7.2.2 Added videos _______________________________________________________________ 36
7.2.3 Added recommendations for analyzing AR System Log Analyzer output and troubleshooting issues
connecting to the AR System server _____________________________________________________ 36
7.2.4 Added an example for customizing AR forms _______________________________________ 36
7.3 Service Pack 1: 8.1.01 _______________________________________________________________ 37
7.3.1 Enhancements ______________________________________________________________ 37
7.3.2 Known and Corrected issues ____________________________________________________ 38
7.3.3 Downloading the service pack __________________________________________________ 39
7.3.4 Installing the service pack ______________________________________________________ 39
7.3.5 Applying Service Pack 1: 8.1.01 __________________________________________________ 39
7.3.6 Other enhancements for Service Pack 1 ___________________________________________ 40
7.4 Patch 2 for version 8.1.00: 8.1.00.002 __________________________________________________ 42
7.4.1 Reviewing the patches currently installed on your computer ___________________________ 43
7.4.2 Installing the patch and reviewing the result ________________________________________ 43
7.4.3 Disabling escalations _________________________________________________________ 46
7.4.4 Applying the Data Management Hotfix ____________________________________________ 46
7.4.5 Performing a silent installation __________________________________________________ 46
7.4.6 Reconciling your customizations ________________________________________________ 47
7.5 Patch 1 for version 8.1.00: 8.1.00.001 __________________________________________________ 47
7.5.1 Reviewing the patches currently installed on your computer ___________________________ 48
7.5.2 Installing the patch and reviewing the results _______________________________________ 49
7.5.3 Removing a server from a server group ____________________________________________ 52
7.5.4 Disabling escalations __________________________________________________________ 52
7.5.5 Performing a silent installation __________________________________________________ 52
7.5.6 Reconciling your customizations ________________________________________________ 53
BMC Remedy Action Request System 8.1 Page 2 of 4492

7.6 8.1.00 enhancements ______________________________________________________________ 53

7.6.1 BMC Remedy AR System enhancements in version 8.1.00 _____________________________ 54
7.6.2 BMC Remedy Migrator enhancements in version 8.1.00 _______________________________ 60
7.7 Locating white papers, guides, and technical bulletins _____________________________________ 60
7.7.1 BMC Remedy AR System online documentation _____________________________________ 60
7.7.2 BMC Remedy Encryption online documentation ____________________________________ 64
7.7.3 BMC Remedy Migrator online documentation ______________________________________ 65
7.7.4 BMC Remedy IT Service Management Preconfigured Stack online documentation ___________ 65
7.7.5 White papers online __________________________________________________________ 65
8 FAQ ________________________________________________________________________________ 67
9 Key concepts ________________________________________________________________________ 68
9.1 Business Service Management ________________________________________________________ 68
9.2 Business value ____________________________________________________________________ 69
9.2.1 Building a foundation for ITIL service support _______________________________________ 69
9.2.2 How BMC provides value ______________________________________________________ 69
9.2.3 How BMC Remedy AR System enables business process automation _____________________ 70
9.2.4 How BMC Remedy AR System products and related products enable additional value and BSM ___
72
9.2.5 How BMC Remedy Migrator automates migration of data and objects between AR System servers
74
9.2.6 How BMC Remedy Email Engine enables email-driven business processes _________________ 74
9.2.7 How BMC Remedy Encryption Security enables secure communication between the client and
server ____________________________________________________________________________ 76
9.2.8 How BMC Remedy Distributed Server Option manages distributed business requests _________ 77
9.2.9 How BMC Remedy Approval Server automates approval-driven business processes __________ 78
9.2.10 How BMC Remedy AR System integrates with third-party products ______________________ 80
9.3 User goals and features _____________________________________________________________ 82
9.3.1 User roles __________________________________________________________________ 83
9.4 License overview __________________________________________________________________ 85
9.4.1 Differences in licensing in earlier versions __________________________________________ 85
9.4.2 License notes _______________________________________________________________ 86
9.4.3 License types overview ________________________________________________________ 87
9.5 Access control overview ____________________________________________________________ 88
9.5.1 User and group access overview _________________________________________________ 89
9.5.2 Role-based access overview ____________________________________________________ 92
9.5.3 Multitiered access control model ________________________________________________ 92
9.5.4 How licensing affects access control _____________________________________________ 94
9.6 Application development overview ____________________________________________________ 94
9.6.1 BMC Remedy AR System application types _________________________________________ 94
9.6.2 BMC Remedy AR System application components ___________________________________ 95
9.6.3 Application localization _______________________________________________________ 111
9.6.4 An example BMC Remedy AR System application ___________________________________ 112
9.7 Architecture _____________________________________________________________________ 121

9.7.1 BMC Remedy AR System architecture ____________________________________________ 122

9.7.2 AR System server architecture and scalability ______________________________________ 128
9.7.3 AR System database server ____________________________________________________ 137
9.7.4 BMC Remedy Mid Tier architecture ______________________________________________ 138
9.7.5 BMC Remedy Migrator architecture _____________________________________________ 142
9.7.6 BMC Remedy AR System web services architecture __________________________________ 143
9.7.7 BMC Remedy AR System API architecture _________________________________________ 145
9.7.8 BMC Remedy Email Engine architecture __________________________________________ 149
10 Planning ___________________________________________________________________________ 152
10.1 Available BMC Remedy AR System features and configurations ______________________________ 153
10.1.1 Features you can install _______________________________________________________ 153
10.1.2 Configuration Types _________________________________________________________ 155
10.2 Installation and upgrade paths _______________________________________________________ 157
10.2.1 Planning to upgrade BMC Remedy AR System ______________________________________ 157
10.2.2 Planning a server group installation _____________________________________________ 160
10.2.3 Planning BMC Remedy AR System installation in an enterprise environment _______________ 169
10.3 BSM environment recommendations __________________________________________________ 170
10.3.1 BSM Interoperability _________________________________________________________ 171
10.3.2 Mainframe integrations _______________________________________________________ 177
10.3.3 BSM Reference Stack _________________________________________________________ 177
10.3.4 Related topics ______________________________________________________________ 178
10.4 Deployment architecture ___________________________________________________________ 178
10.4.1 Email deployment use cases ___________________________________________________ 179
10.4.2 Performance benchmarks and tuning ____________________________________________ 191
10.5 System requirements ______________________________________________________________ 320
10.5.1 Checking system requirements and supported configurations _________________________ 320
10.5.2 Hardware requirements ______________________________________________________ 322
10.5.3 Software requirements _______________________________________________________ 325
10.5.4 Server operating system platforms ______________________________________________ 327
10.5.5 Unicode requirements _______________________________________________________ 328
10.5.6 Portmapper service introduction ________________________________________________ 335
10.5.7 BMC Remedy Migrator memory usage and disk space requirements _____________________ 337
10.6 Security ________________________________________________________________________ 337
10.6.1 Security considerations for BMC Remedy AR System _________________________________ 337
10.6.2 General security guidelines ____________________________________________________ 340
10.6.3 BMC Remedy Encryption Security options ________________________________________ 345
10.6.4 Security policy impact on client-server communication ______________________________ 345
10.6.5 BMC Remedy Encryption Security compatibility ____________________________________ 346
10.6.6 BMC Remedy Encryption Security modifications to the JRE ___________________________ 347
10.6.7 Standard security modifications to the IBM JDK ____________________________________ 347
10.6.8 Single sign-on authentication systems integration __________________________________ 348
10.6.9 Security assessments ________________________________________________________ 369
10.7 Language information _____________________________________________________________ 374

10.7.1 Supported languages and character encodings _____________________________________ 374

10.7.2 Localized forms _____________________________________________________________ 376
10.7.3 Installing BMC Remedy AR System in an international environment: Oracle on UNIX ________ 377
10.7.4 BMC Remedy Email Engine internationalization support ______________________________ 378
10.8 BMC Remedy AR System standards ___________________________________________________ 378
10.8.1 AR System server standards ____________________________________________________ 378
10.8.2 Mid Tier standards ___________________________________________________________ 378
10.9 Support for IPv6 _________________________________________________________________ 379
10.9.1 Post-installation or post-upgrade considerations ___________________________________ 380
10.9.2 Supported operating systems for IPv6 ___________________________________________ 380
10.9.3 Supported databases for IPv6 __________________________________________________ 380
10.9.4 Supported database clients for IPv6 _____________________________________________ 380
10.9.5 Tested web servers for IPv6 ___________________________________________________ 380
10.9.6 IPv6 considerations with BMC Remedy AR System __________________________________ 381
11 Installing ___________________________________________________________________________ 382
11.1 Preparing for installation ___________________________________________________________ 383
11.1.1 Installation process overview __________________________________________________ 383
11.1.2 Reviewing the compatibility matrix ______________________________________________ 384
11.1.3 Reviewing the requirements ___________________________________________________ 385
11.1.4 Downloading the installation files _______________________________________________ 391
11.1.5 Preparing your database ______________________________________________________ 393
11.1.6 Obtaining BMC Remedy license keys ____________________________________________ 423
11.1.7 Completing the planning spreadsheet ___________________________________________ 426
11.1.8 Preparing your environment to install ____________________________________________ 439
11.1.9 Preparing your components and applications ______________________________________ 455
11.2 Performing a new installation _______________________________________________________ 466
11.2.1 Choosing products __________________________________________________________ 466
11.2.2 Minimum set of features need to install other BMC products __________________________ 467
11.2.3 To install BMC Remedy AR System ______________________________________________ 467
11.2.4 To install BMC Remedy Mid Tier ________________________________________________ 468
11.2.5 Related topics ______________________________________________________________ 469
11.2.6 Where to go from here _______________________________________________________ 469
11.3 Installing a server group ___________________________________________________________ 469
11.3.1 Preparing to install your server group ____________________________________________ 470
11.3.2 Server group installation flow __________________________________________________ 471
11.3.4 Installing the first AR System server ______________________________________________ 472
11.3.5 Configuring the first server to be a server group member _____________________________ 481
11.3.6 Testing and confirming that the first server is working properly ________________________ 483
11.3.7 Installing the next AR System server in the server group ______________________________ 483
11.3.8 Configuring the next server for the server group ___________________________________ 485
11.3.9 Configuring the approval servers in a server group __________________________________ 487
11.3.10Testing and confirming that the current server is working properly _____________________ 488

Testing and confirming that the current server is working properly ____________________ 488
11.4 Performing other installations _______________________________________________________ 490
11.4.1 Installing silently ____________________________________________________________ 490
11.4.2 Configuring your web server and installing BMC Remedy Mid Tier with a .war file __________ 494
11.4.3 Remotely installing or upgrading Email Engine _____________________________________ 502
11.4.4 Remotely installing or upgrading Flashboards ______________________________________ 505
11.4.5 Installing BMC Remedy Encryption Security _______________________________________ 506
11.4.6 Installing BMC Remedy Migrator ________________________________________________ 512
11.4.7 Installing SSO with the AR System server and mid tier ________________________________ 513
11.4.8 Installing a stand-alone Atrium Integrator server ____________________________________ 531
11.4.9 Installing multiple instances of BMC Remedy AR System on one computer ________________ 534
11.5 Post-installation procedures ________________________________________________________ 536
11.5.1 BMC Remedy AR System server post-installation procedures __________________________ 536
11.5.2 Mid Tier post-installation procedures ____________________________________________ 539
11.5.3 Flashboards post-installation procedures _________________________________________ 543
11.5.4 IPv6 post-installation procedures _______________________________________________ 544
11.5.5 Post-installation checks ______________________________________________________ 549
11.6 Uninstalling BMC Remedy AR System features and clients __________________________________ 555
11.6.1 Uninstalling BMC Remedy AR System features _____________________________________ 555
11.6.2 Uninstalling encryption security ________________________________________________ 556
11.6.3 Uninstalling BMC Remedy Migrator ______________________________________________ 557
11.6.4 Uninstallation tips for BMC Remedy Mid Tier ______________________________________ 558
12 Configuring after installation ____________________________________________________________ 559
12.1 Logging on to the system __________________________________________________________ 560
12.2 Modifying the config.properties file ___________________________________________________ 560
12.3 Working with BMC Remedy AR System licenses __________________________________________ 561
12.3.1 Adding or removing licenses ___________________________________________________ 561
12.3.2 Exporting or importing licenses ________________________________________________ 562
12.3.3 Displaying license usage ______________________________________________________ 564
12.3.4 Reviewing license usage ______________________________________________________ 567
12.3.5 Generating a license usage report _______________________________________________ 569
12.3.6 Licensing for server groups ____________________________________________________ 570
12.4 Configuring AR System servers ______________________________________________________ 571
12.4.1 Configuring clients for AR System servers _________________________________________ 573
12.4.2 Configuring firewalls with AR System servers ______________________________________ 573
12.4.3 Running a stand-alone AR System server on Windows _______________________________ 574
12.4.4 Configuring a server for alerts __________________________________________________ 575
12.4.5 Configuring the AR System server for external authentication __________________________ 575
12.4.6 Configuring a server to use plug-ins _____________________________________________ 577
12.4.7 Setting version control options _________________________________________________ 578
12.4.8 Setting timeout options _______________________________________________________ 579
12.4.9 Setting a connection to the BMC Atrium SSO server _________________________________ 580
12.4.10Setting a connection to the BMC Atrium Web Services Registry ________________________ 580
12.4.11Setting platform options ______________________________________________________ 581

Setting platform options _____________________________________________________ 581
12.4.12Setting log files options ______________________________________________________ 582
12.4.13Setting server logging options _________________________________________________ 586
12.4.14Setting ports and RPC numbers ________________________________________________ 587
12.4.15Setting database options _____________________________________________________ 589
12.4.16Setting currency types _______________________________________________________ 590
12.4.17Setting license options _______________________________________________________ 592
12.4.18Setting external authentication options __________________________________________ 593
12.4.19Setting performance and security options ________________________________________ 595
12.4.20Setting server passwords, RPC options, and plug-in timeouts _________________________ 598
12.4.21Setting administrative options _________________________________________________ 600
12.4.22Defining queues and configuring threads _________________________________________ 605
12.4.23Changing a server name when using a duplicated or migrated environment ______________ 607
12.4.24Setting security restrictions on file uploads _______________________________________ 621
12.4.25Setting server statistics options ________________________________________________ 625
12.5 Configuring server groups __________________________________________________________ 627
12.5.1 Configuring the server group check interval _______________________________________ 629
12.5.2 Setting failover rankings for servers and operations _________________________________ 630
12.5.3 Configuring the server group signaling option _____________________________________ 631
12.5.4 Configuring full text search for a server group _____________________________________ 633
12.5.5 Configuring DSO for a server group _____________________________________________ 636
12.5.6 Configuring the Email Engine for a server group ____________________________________ 638
12.5.7 Configuring flashboards for server groups ________________________________________ 638
12.5.8 Bypassing the load balancer to work on a specific server _____________________________ 639
12.5.9 Using data archiving with server groups __________________________________________ 640
12.5.10Configuring logging for server groups ___________________________________________ 640
12.5.11Removing a server from a server group or remove an unused server name ________________ 641
12.5.12Sharing a database without using a server group ___________________________________ 641
12.6 BMC Remedy AR System cache management ___________________________________________ 642
12.6.1 Configuring the server cache __________________________________________________ 642
12.6.2 Guidelines for resolving cache memory issues _____________________________________ 648
12.6.3 Setting the distributed mapping cache refresh interval _______________________________ 651
12.6.4 Actions that trigger cache events _______________________________________________ 652
12.6.5 Mid Tier cache configuration __________________________________________________ 654
12.6.6 Actions in ITSM 7.0.00 applications that trigger caching ______________________________ 665
12.7 BMC Remedy Mid Tier configuration __________________________________________________ 665
12.7.1 Configuring the mid tier through a firewall ________________________________________ 666
12.7.2 Configuring mid tier memory __________________________________________________ 667
12.7.3 Accessing the Mid Tier Configuration Tool ________________________________________ 668
12.7.4 Configuring the Change Password page __________________________________________ 670
12.7.5 Configuring the Overview page ________________________________________________ 670
12.7.6 Configuring the General Settings page ___________________________________________ 672
12.7.7 Configuring the AR Server Settings page __________________________________________ 674
12.7.8 Configuring the Cache Settings page ____________________________________________ 677

12.7.9 Configuring the Report Settings page ____________________________________________ 689

12.7.10Configuring the Web Service Settings page _______________________________________ 691
12.7.11Configuring the Connection Settings page ________________________________________ 691
12.7.12Configuring a mid tier to launch a browser in a different mid tier _______________________ 694
12.7.13Cookies used by BMC Remedy Mid Tier __________________________________________ 696
12.8 Configuring a hardware load balancer with BMC Remedy AR System _________________________ 697
12.8.1 What a load balancer does ____________________________________________________ 697
12.8.2 How load balancers route requests ______________________________________________ 698
12.8.3 Considerations for configuring load balancers with AR System servers ___________________ 699
12.8.4 Using a load balancer with server groups _________________________________________ 699
12.8.5 Load balancer configuration examples ___________________________________________ 701
12.8.6 Sample load-balancer- Cisco 11500 Series Content Services Switch _____________________ 705
12.8.7 Special considerations and known issues _________________________________________ 707
12.8.8 Load balancing with Email Engine _______________________________________________ 712
12.9 Configuring a Unicode server ________________________________________________________ 712
12.9.1 Running your Unicode server __________________________________________________ 712
12.9.2 How BMC Remedy AR System works with Unicode __________________________________ 713
12.9.3 Specifying a character set for data import to a Unicode AR System server _________________ 717
12.9.4 Filter and escalation workflow considerations ______________________________________ 718
12.10BMC Remedy SNMP Agent configuration ______________________________________________ 719
12.10.1SNMP introduction __________________________________________________________ 719
12.10.2SNMP access control ________________________________________________________ 720
12.10.3Monitoring BMC Remedy AR System ____________________________________________ 724
12.10.4Sending traps to clients ______________________________________________________ 725
12.10.5SNMP configuration files _____________________________________________________ 726
12.10.6arsnmpd configuration file purpose _____________________________________________ 727
12.10.7snmpd configuration file purpose _______________________________________________ 728
12.10.8armonitor configuration file purpose ____________________________________________ 730
12.10.9Starting the SNMP Agent _____________________________________________________ 730
12.10.10Stopping the SNMP Agent ____________________________________________________ 731
12.10.11SNMP Configuration form in the AR System Administration Console ____________________ 731
12.11Configuring BMC Remedy Distributed Server Option ______________________________________ 733
12.11.1Setting up DSO _____________________________________________________________ 733
12.11.2Enabling DSO on an AR System server ____________________________________________ 734
12.11.3Configuring a password for the DSO user _________________________________________ 735
12.11.4Assigning an RPC program number to DSO ________________________________________ 736
12.11.5Configuring remote AR System servers for DSO ____________________________________ 737
12.11.6Configuring DSO for firewalls __________________________________________________ 738
12.11.7Specifying a DSO host name ___________________________________________________ 739
12.11.8Configuring the RPC timeout setting ____________________________________________ 740
12.11.9DSO for load balancing _______________________________________________________ 741
12.11.10AR System Administration - Server Information form - DSO tab _______________________ 741
12.12Configuring full text search _________________________________________________________ 743

Configuring full text search ________________________________________________________ 743
12.12.1FTS tab configuration options __________________________________________________ 743
12.12.2High-availability architecture for FTS ____________________________________________ 745
12.12.3FTS Configuration form in the AR System Administration Console ______________________ 747
12.12.4Creating index files in a different directory from the default ___________________________ 751
12.12.5Scheduling scans for updates __________________________________________________ 751
12.12.6Configuring the Ignore Words List ______________________________________________ 752
12.12.7Displaying FTS weight in a results list ____________________________________________ 753
12.12.8Providing a shortcut for specifying expanded FTS qualifications ________________________ 753
12.12.9Configuring FTS for localization ________________________________________________ 754
12.12.10Advanced FTS configuration files ______________________________________________ 755
12.12.11Adding FTS licenses _________________________________________________________ 757
12.12.12Upgrading with FTS installed __________________________________________________ 757
12.13Configuring reporting _____________________________________________________________ 758
12.13.1Modifying the config.properties file for limiting report entries __________________________ 758
12.13.2Configuring web and BMC Remedy AR System reports _______________________________ 758
12.13.3Using Crystal reports with BMC Remedy AR System _________________________________ 773
12.13.4Managing localized Crystal and Web reports ______________________________________ 782
12.14Configuring the BMC Remedy Approval Server __________________________________________ 785
12.14.1Working with the AP-Administration form ________________________________________ 786
12.14.2Process administrator overview ________________________________________________ 787
12.14.3Configuring process administrator capabilities _____________________________________ 787
12.14.4Configuring Approval Server to work with flowcharts ________________________________ 788
12.14.5Configuring BMC Remedy Approval Server with a separate plug-in server instance _________ 789
12.14.6Starting and stopping the Approval Server ________________________________________ 791
12.15Configuring BMC Remedy Email Engine _______________________________________________ 793
12.15.1Configuring outgoing mailboxes ________________________________________________ 793
12.15.2EmailDaemon.properties file ___________________________________________________ 796
12.15.3Settings in the EmailDaemon.properties file _______________________________________ 799
12.15.4BMC Remedy Email Engine mailboxes ___________________________________________ 805
12.15.5Saving outgoing notifications in MAPI ___________________________________________ 806
12.15.6Changing the default time interval ______________________________________________ 806
12.15.7Testing your mailbox configuration _____________________________________________ 807
12.15.8Configuring incoming mailboxes _______________________________________________ 808
12.15.9Stopping and starting the Email Engine ___________________________________________ 812
12.16Configuring BMC Remedy Flashboards ________________________________________________ 813
12.16.1Setting up flashboard update intervals ___________________________________________ 813
12.16.2Starting or stopping the Flashboards server manually ________________________________ 814
12.16.3Setting up a headless environment with Tomcat to display flashboards __________________ 815
12.16.4Configuring the display properties for a flashboard _________________________________ 816
12.16.5Modifying the config.properties file for flashboards _________________________________ 822
12.16.6Multiple Flashboards servers and AR System servers _________________________________ 823
12.17Configuring BMC Remedy Migrator __________________________________________________ 824
12.17.1Removing an AR System server and its BMC Remedy Migrator license from view ___________ 824

Removing an AR System server and its BMC Remedy Migrator license from view __________ 824
12.17.2Adding AR System server into server account ______________________________________ 824
12.17.3Adding a licensed AR System server in BMC Remedy Migrator _________________________ 826
12.17.4Adding or transferring BMC Remedy Migrator license to an AR System server _____________ 827
12.17.5Starting BMC Remedy Migrator _________________________________________________ 827
12.17.6Setting-up BMC Remedy Migrator ______________________________________________ 827
12.18Configuring the Assignment Engine __________________________________________________ 828
12.18.1Configuring Assignment Engine properties ________________________________________ 828
12.18.2Stopping and starting the Assignment Engine ______________________________________ 829
12.19Securing BMC Remedy AR System ___________________________________________________ 830
12.19.1Configuring SSL for the email engine ____________________________________________ 830
12.19.2Resetting the Application Service password _______________________________________ 834
12.19.3Securing incoming and outgoing email __________________________________________ 835
12.20Configuring BMC Remedy Encryption Security __________________________________________ 839
12.20.1Configuring the data key _____________________________________________________ 840
12.20.2Configuring the public key ____________________________________________________ 842
12.20.3Activating encryption ________________________________________________________ 843
12.20.4Deactivating encryption ______________________________________________________ 844
12.20.5Activating FIPS compliance ___________________________________________________ 844
12.21Using Oracle CLOBs with BMC Remedy AR System _______________________________________ 846
12.21.1About Oracle LOBs __________________________________________________________ 846
12.21.2Storage size impact _________________________________________________________ 847
12.21.3Performance impact _________________________________________________________ 849
12.21.4Converting LOB storage ______________________________________________________ 850
13 Upgrading __________________________________________________________________________ 855
13.1 Preparing for upgrade _____________________________________________________________ 855
13.1.1 Reviewing the compatibility matrix before upgrading ________________________________ 856
13.1.2 Reviewing the upgrade requirements ____________________________________________ 857
13.1.3 Preparing your database for an upgrade __________________________________________ 863
13.1.4 Completing the planning spreadsheet for an upgrade _______________________________ 892
13.1.5 Downloading the installation files to upgrade ______________________________________ 893
13.1.6 Preparing your components and applications for an upgrade __________________________ 893
13.2 Upgrading with overlays already present _______________________________________________ 897
13.2.1 Prepare to upgrade __________________________________________________________ 897
13.2.2 Complete the upgrade stages __________________________________________________ 898
13.2.3 Migrate your data ___________________________________________________________ 898
13.2.4 Understanding how upgrading with overlays works _________________________________ 898
13.2.5 Stage 1 - Setting up a staging server for upgrades with overlays already present ___________ 902
13.2.6 Stage 2 - Upgrade AR System server with overlays present ____________________________ 909
13.2.7 Stage 3 - Upgrade applications and adjust customizations with overlays present ___________ 919
13.2.8 Stage 4 - Test and promote staging server with overlays to production __________________ 924
13.2.9 Setting up a staging server for upgrades with overlays already present (new) ______________ 925
13.3 Upgrading without overlays already present ____________________________________________ 925
13.3.1 Prepare to upgrade __________________________________________________________ 926

13.3.2 Complete the upgrade stages __________________________________________________ 926

13.3.3 Migrate your data ___________________________________________________________ 927
13.3.4 Understanding how upgrading without overlays works _______________________________ 927
13.3.5 Stage 1 - Setting up a staging server for upgrades without overlays _____________________ 932
13.3.6 Stage 2 - Upgrade AR System server without overlays present _________________________ 941
13.3.7 Stage 3 - Create overlays for existing customizations ________________________________ 949
13.3.8 Stage 4 - Acquire origin objects: optional _________________________________________ 970
13.3.9 Stage 5 - Restore origin objects to the staging server: optional _________________________ 971
13.3.10Stage 6 - Minimize overlays: optional ____________________________________________ 972
13.3.11Stage 7 - Upgrade applications and adjust customizations with new overlays ______________ 976
13.3.12Stage 8 - Test and promote staging server to production with new overlays ______________ 981
13.3.13Stage 6 - Adjusting customizations when upgrading ________________________________ 982
13.4 Migrating delta data after an upgrade _________________________________________________ 982
13.4.1 Before you begin ___________________________________________________________ 982
13.4.2 Overview of delta data migration tasks ___________________________________________ 982
13.4.3 Components of the Delta Data Migration Tool _____________________________________ 984
13.4.4 What is included in the application package _______________________________________ 985
13.4.5 Related topics ______________________________________________________________ 986
13.4.7 Supported migration paths ____________________________________________________ 987
13.4.8 Infrastructure requirements for migration _________________________________________ 987
13.4.9 Migrator tools ______________________________________________________________ 988
13.4.10Preparing the source and destination servers for Delta Data Migration ___________________ 990
13.4.11Performing the data migration _________________________________________________ 997
13.4.12Reviewing the migration results and resolving issues _______________________________ 1002
13.4.13Extending Delta Data Migration to include customizations ___________________________ 1007
13.4.14Performing the data migration for server groups ___________________________________ 1011
13.4.15Post-migration procedures ___________________________________________________ 1012
13.5 Upgrading server groups __________________________________________________________ 1030
13.5.1 To upgrade with server groups if you are migrating data _____________________________ 1031
13.5.2 To perform an in-place upgrade _______________________________________________ 1031
13.6 Upgrading encryption security ______________________________________________________ 1032
13.7 Post-upgrade procedures _________________________________________________________ 1032
13.7.1 After upgrading from BMC Remedy AR System 7.6.04 with view overlays present __________ 1032
13.7.2 Comparing objects after you upgraded with overlays already present ___________________ 1032
13.7.3 Disabling ServletExec after an upgrade __________________________________________ 1033
13.7.4 Approval Server post-upgrade procedures _______________________________________ 1034
13.7.5 Developer Studio post-upgrade procedures ______________________________________ 1038
13.7.6 Enabling LDAP plug-ins for SSL connections post-upgrade ___________________________ 1038
13.7.7 IPv6 post-upgrade procedures ________________________________________________ 1040
14 Integrating ________________________________________________________________________ 1044
14.1 Integration considerations _________________________________________________________ 1045
14.1.1 Where to integrate BMC Remedy AR System ______________________________________ 1045

14.1.2 Multiplatform issues ________________________________________________________ 1047

14.1.3 Choosing an implementation method ___________________________________________ 1047
14.1.4 Integration technologies _____________________________________________________ 1047
14.2 Enabling plug-ins _______________________________________________________________ 1049
14.2.1 AR System plug-ins introduction _______________________________________________ 1049
14.2.2 Plug-in types supported by BMC Remedy AR System _______________________________ 1050
14.2.3 AR Filter API plug-ins introduction _____________________________________________ 1052
14.2.4 AREA plug-ins introduction ___________________________________________________ 1075
14.2.5 ARDBC plug-ins introduction _________________________________________________ 1078
14.2.6 Installed plug-in components _________________________________________________ 1098
14.2.7 Creating C plug-ins _________________________________________________________ 1099
14.2.8 C plug-in naming conventions ________________________________________________ 1100
14.2.9 Configuring the Java plug-in server ____________________________________________ 1100
14.2.10Creating Java plug-ins ______________________________________________________ 1106
14.2.11Configuring the AR System server to access a plug-in server __________________________ 1108
14.2.12Running the plug-in server ___________________________________________________ 1110
14.2.13Common plug-in C functions and Java methods ___________________________________ 1112
14.2.14Opening Knowledge Management System Configuration form ________________________ 1113
14.3 Integrating with a directory service __________________________________________________ 1114
14.3.1 LDAP plug-ins in BMC Remedy AR System ________________________________________ 1114
14.3.2 Using the ARDBC LDAP plug-in ________________________________________________ 1114
14.3.3 Configuring the ARDBC LDAP plug-in ___________________________________________ 1115
14.3.4 Building BMC Remedy AR System forms for directory services _________________________ 1117
14.3.5 Using the AREA LDAP plug-in _________________________________________________ 1123
14.3.6 ARDBC LDAP example - Accessing inetorgperson data ______________________________ 1129
14.3.7 Enabling LDAP plug-ins to establish SSL connections with LDAP servers _________________ 1134
14.4 AR System external authentication ___________________________________________________ 1155
14.4.1 Enabling AREA authentication _________________________________________________ 1155
14.4.2 Configuring authentication processing __________________________________________ 1156
14.4.3 Setting up the AREA hub _____________________________________________________ 1161
14.4.4 Enabling FIPS support for BMC Atrium SSO _______________________________________ 1163
14.5 Data and database integrations _____________________________________________________ 1163
14.5.1 Creating vendor forms _______________________________________________________ 1163
14.5.2 View forms _______________________________________________________________ 1166
14.5.3 SQL database access ________________________________________________________ 1172
14.5.4 ODBC database access introduction ____________________________________________ 1174
14.6 Extending BMC Remedy Developer Studio _____________________________________________ 1185
14.6.1 Creating plug-ins to extend BMC Remedy Developer Studio __________________________ 1185
14.6.2 Prerequisites for creating plug-ins ______________________________________________ 1187
14.6.3 Extension points for BMC Remedy Developer Studio ________________________________ 1188
14.6.4 Developer Studio Java API ____________________________________________________ 1188
14.6.5 Installation directory for the BMC Remedy Developer Studio plug-ins ___________________ 1189
14.7 BMC Atrium Orchestrator integration ________________________________________________ 1189

14.7.1 Defining BMC Atrium Orchestrator web services ___________________________________ 1190

14.7.2 Modifying entries in the AR System Orchestrator Configuration form ___________________ 1191
14.7.3 BMC Remedy AR System workflow for BMC Atrium Orchestrator integration _____________ 1192
14.7.4 Obtaining job status for asynchronous execution operations _________________________ 1195
14.8 Atrium Integrator adapter for BMC Remedy AR System ___________________________________ 1196
14.8.1 Data integration ___________________________________________________________ 1196
14.8.2 AR System permissions scheme ________________________________________________ 1198
14.8.3 Related topics _____________________________________________________________ 1198
14.8.4 ETL in the Atrium Integrator adapter ____________________________________________ 1198
14.8.5 Input, output and file input steps _______________________________________________ 1201
14.8.6 AR Connection module ______________________________________________________ 1212
14.8.7 Error handling _____________________________________________________________ 1214
14.8.8 BMC Remedy AR System forms for data management _______________________________ 1225
14.8.9 Atrium Integrator Spoon client ________________________________________________ 1247
14.8.10Scheduling and manually executing a transformation or job __________________________ 1247
14.9 Running external processes with the Run Process action __________________________________ 1248
14.9.1 Running external processes introduction ________________________________________ 1248
14.9.2 Triggering Run Process on clients and servers _____________________________________ 1249
14.9.3 Starting applications with the Run Process action __________________________________ 1249
14.9.4 Retrieving data from applications with Run Process ________________________________ 1253
14.9.5 Using Run Process for the web ________________________________________________ 1256
14.10Integrating the BMC Remedy Assignment Engine into an application ________________________ 1257
14.10.1To integrate the BMC Remedy Assignment Engine with your application ________________ 1257
14.10.2Preparing for the auto-assignment process ______________________________________ 1257
14.10.3Adding fields to the assignee and request forms ___________________________________ 1258
14.10.4Adding assignee and request forms ____________________________________________ 1259
14.10.5Adding assignment rules _____________________________________________________ 1263
14.10.6Setting sequencing for rules __________________________________________________ 1264
14.10.7Adding and executing assignment processes _____________________________________ 1264
14.11Using DSO with BMC Atrium CMDB __________________________________________________ 1265
14.11.1Setting up DSO to use CMDB data ______________________________________________ 1266
14.11.2Join forms and BMC Atrium CMDB _____________________________________________ 1267
14.11.3Writing to the CMDB production dataset _________________________________________ 1267
14.11.4Examples of using DSO to replicate CMDB data ___________________________________ 1268
14.11.5Recommendations for using DSO with BMC Atrium CMDB ___________________________ 1269
14.11.6Performance considerations __________________________________________________ 1270
15 Using _____________________________________________________________________________ 1272
15.1 Navigating the BMC Remedy AR System interface _______________________________________ 1272
15.1.1 Using the AR System Object List _______________________________________________ 1272
15.1.2 Opening Approval Central ____________________________________________________ 1293
15.1.3 Copying field information to a new request _______________________________________ 1293
15.2 Running and saving searches _______________________________________________________ 1294
15.2.1 Finding a request by example _________________________________________________ 1294

15.2.2 Running a saved, recent, or defined search _______________________________________ 1297

15.2.3 Loading search criteria without execution ________________________________________ 1297
15.2.4 Saving searches ____________________________________________________________ 1298
15.2.5 Managing saved searches ____________________________________________________ 1298
15.2.6 Running searches __________________________________________________________ 1299
15.2.7 Types of searches __________________________________________________________ 1300
15.2.8 Using the advanced search bar ________________________________________________ 1300
15.3 Reporting on BMC Remedy AR System data ____________________________________________ 1308
15.3.1 BMC Remedy AR System Report Console ________________________________________ 1309
15.3.2 Report designer screen ______________________________________________________ 1310
15.3.3 Report types ______________________________________________________________ 1310
15.3.4 Running reports in the Report Console __________________________________________ 1311
15.3.5 Creating reports ___________________________________________________________ 1320
15.3.6 Editing and deleting reports __________________________________________________ 1333
15.3.7 Scheduling reports _________________________________________________________ 1333
15.3.8 Publishing reports __________________________________________________________ 1334
15.3.9 Saving or exporting BMC Remedy AR System reports _______________________________ 1336
15.3.10Using a BIRT editor to create or modify web reports ________________________________ 1337
15.4 Approving requests ______________________________________________________________ 1361
15.4.1 Approval notification through email ____________________________________________ 1361
15.4.2 Configuring the Request ID link on Approval Central ________________________________ 1365
15.4.3 Setting previews for approval requests __________________________________________ 1366
15.4.4 Processing approval requests _________________________________________________ 1366
15.4.5 Using the Get Agreement sample application _____________________________________ 1382
15.5 Using BMC Remedy Flashboards ____________________________________________________ 1388
15.5.1 Viewing flashboards ________________________________________________________ 1388
15.5.2 Sorting flashboards _________________________________________________________ 1389
15.5.3 Refreshing flashboards ______________________________________________________ 1391
15.5.4 Displaying tooltips __________________________________________________________ 1392
15.5.5 Manipulating BMC Remedy Flashboards _________________________________________ 1392
15.5.6 Drilling down to information in a flashboard ______________________________________ 1393
16 Administering ______________________________________________________________________ 1394
16.1 Navigating the BMC Remedy AR System Administration console interface _____________________ 1395
16.1.1 Opening the AR System Administration Console ___________________________________ 1395
16.1.2 AR System Administration Console introduction ___________________________________ 1395
16.2 BMC Remedy AR System configuration files ___________________________________________ 1398
16.2.1 ar ______________________________________________________________________ 1398
16.2.2 ar.cfg or ar.conf ____________________________________________________________ 1399
16.2.3 ardb.cfg or ardb.conf _______________________________________________________ 1438
16.2.4 armonitor.cfg or armonitor.conf _______________________________________________ 1442
16.3 AR System server components and external utilities _____________________________________ 1443
16.3.1 AR System server components ________________________________________________ 1443
16.3.2 External utilities ____________________________________________________________ 1450

16.4 Security administration ___________________________________________________________ 1457

16.4.1 Creating users, groups, and roles _______________________________________________ 1457
16.4.2 Access control _____________________________________________________________ 1478
16.4.3 Setting up an authentication alias ______________________________________________ 1520
16.4.4 Restrictions when logging in to a BMC Remedy AR System server ______________________ 1523
16.4.5 Defining your user base ______________________________________________________ 1524
16.4.6 Understanding database security issues _________________________________________ 1529
16.4.7 Using audit records _________________________________________________________ 1531
16.5 Setting user preferences __________________________________________________________ 1534
16.5.1 Accessing preference forms for centralized preferences _____________________________ 1534
16.5.2 Restricting preferences from users _____________________________________________ 1535
16.5.3 Configuring clients to use a preference server _____________________________________ 1535
16.5.4 Establishing a mandatory preference server ______________________________________ 1535
16.5.5 Behaviors associated with preference server configuration ___________________________ 1536
16.5.6 Setting the AR System User Preference form ______________________________________ 1537
16.5.7 Setting user preferences in the BMC Remedy Mid Tier _______________________________ 1558
16.6 Defining business schedules using Business Time _______________________________________ 1559
16.6.1 Business Time introduction ___________________________________________________ 1559
16.6.2 Scheduling a time segment ___________________________________________________ 1562
16.6.3 Using time zones ___________________________________________________________ 1568
16.6.4 Business Time 2.0 commands _________________________________________________ 1573
16.6.5 Using the old Business Time forms _____________________________________________ 1581
16.6.6 Migrating Workdays and Holidays to the Business Time Segment form __________________ 1589
16.7 Enabling alert notifications ________________________________________________________ 1589
16.7.1 Alert system architecture ____________________________________________________ 1590
16.7.2 Alert Events form introduction ________________________________________________ 1590
16.7.3 Viewing alerts _____________________________________________________________ 1591
16.7.4 Deleting unread alerts _______________________________________________________ 1591
16.7.5 Registering users for alerts ___________________________________________________ 1592
16.7.6 Using the alert list in a browser ________________________________________________ 1593
16.7.7 Using Web services with alerts ________________________________________________ 1594
16.8 Assigning requests with the Assignment Engine _________________________________________ 1597
16.8.1 Auto-assignment methods ___________________________________________________ 1598
16.8.2 Assignment process flow _____________________________________________________ 1598
16.8.3 Assignment Engine Administration Console introduction ____________________________ 1598
16.8.4 Configuring a private queue for the Assignment Engine _____________________________ 1599
16.8.5 Assignment Engine forms ____________________________________________________ 1600
16.9 Enabling full text search ___________________________________________________________ 1601
16.9.1 To enable FTS _____________________________________________________________ 1601
16.9.2 Setting up FTS to search across multiple forms ____________________________________ 1601
16.9.3 Re-indexing considerations ___________________________________________________ 1609
16.9.4 Defining a field for FTS _______________________________________________________ 1611
16.9.5 How FTS indexing works _____________________________________________________ 1614

16.9.6 Performing searches with FTS _________________________________________________ 1618

16.10Controlling BMC Remedy AR System through email _____________________________________ 1627
16.10.1BMC Remedy Email Engine terminology _________________________________________ 1627
16.10.2How BMC Remedy Email Engine works _________________________________________ 1628
16.10.3Setting up outgoing email ____________________________________________________ 1632
16.10.4Setting up incoming email ___________________________________________________ 1675
16.10.5Setting up UNIX mailboxes ___________________________________________________ 1705
16.10.6Creating and using email templates ____________________________________________ 1706
16.10.7Email Engine forms _________________________________________________________ 1744
16.11Setting up the approval process _____________________________________________________ 1761
16.11.1Approval Server concepts ____________________________________________________ 1761
16.11.2Defining an approval process _________________________________________________ 1787
16.11.3Defining approval rules ______________________________________________________ 1795
16.11.4Using the Lunch Scheduler sample application ____________________________________ 1825
16.11.5Worksheets for setting up processes and rules ____________________________________ 1831
16.11.6Approval forms ____________________________________________________________ 1843
16.11.7Running the approval utilities _________________________________________________ 1909
16.12Setting up DSO to synchronize data across multiple AR System servers _______________________ 1911
16.12.1Distributed operations introduction ____________________________________________ 1912
16.12.2Distributed operations components ____________________________________________ 1918
16.12.3Implementing DSO _________________________________________________________ 1923
16.12.4Distributed operations scenarios _______________________________________________ 1947
16.12.5Chained and broadcast distributed transfers ______________________________________ 1954
16.12.6Distributed Server Administration program _______________________________________ 1965
16.12.7Managing request IDs in distributed environments _________________________________ 1968
16.12.8Overwriting all fields in duplicate requests _______________________________________ 1969
16.13Capturing server events for workflow or API calls _______________________________________ 1970
16.13.1Understanding the Server Events form __________________________________________ 1970
16.13.2How the Server Events form is created __________________________________________ 1971
16.13.3Types of events you can record ________________________________________________ 1971
16.13.4Viewing the server changes you recorded ________________________________________ 1972
16.13.5Using server events in workflow _______________________________________________ 1987
16.14Managing data _________________________________________________________________ 1987
16.14.1Auditing data _____________________________________________________________ 1988
16.14.2Archiving data ____________________________________________________________ 2002
16.14.3File types used in migrations _________________________________________________ 2009
16.14.4Importing data into BMC Remedy AR System forms ________________________________ 2011
16.14.5Importing and exporting Flashboards objects _____________________________________ 2022
16.14.6Exporting and importing data and definitions _____________________________________ 2022
16.14.7Using the Request ID to improve performance or security ___________________________ 2046
16.14.8Understanding the AR System database _________________________________________ 2058
16.14.9SQL definitions of the data dictionary tables _____________________________________ 2088
16.15Migrating applications and data between AR System servers _______________________________ 2089

Migrating applications and data between AR System servers ______________________________ 2089
16.15.1Migration overview _________________________________________________________ 2089
16.15.2Navigating the BMC Remedy Migrator interface ___________________________________ 2099
16.15.3Setting BMC Remedy Migrator options __________________________________________ 2130
16.15.4Performing migrations ______________________________________________________ 2156
16.15.5Working with migration scripts ________________________________________________ 2200
16.15.6Using migration reports _____________________________________________________ 2210
16.16Enabling social collaboration in BMC Remedy AR System _________________________________ 2234
16.16.1Receiving alerts through Twitter _______________________________________________ 2234
16.16.2Configuring RSS feeds ______________________________________________________ 2238
16.16.3Configuring chat __________________________________________________________ 2243
16.17Displaying a BMC Remedy AR System form in a portlet ___________________________________ 2261
17 Developing an application _____________________________________________________________ 2262
17.1 Application development with BMC Remedy Developer Studio _____________________________ 2263
17.1.1 Determining what your application needs to track _________________________________ 2264
17.1.2 Determining what to track ___________________________________________________ 2265
17.1.3 Determining how your application should work ___________________________________ 2265
17.1.4 Designing effective and more usable applications __________________________________ 2266
17.1.5 Designing the user interface effectively __________________________________________ 2267
17.1.6 Resources for product design and usability _______________________________________ 2268
17.1.7 Providing accessibility for users with disabilities ___________________________________ 2269
17.1.8 About the Sample application _________________________________________________ 2269
17.2 Navigating the BMC Remedy Developer Studio interface __________________________________ 2269
17.2.1 About BMC Remedy Developer Studio __________________________________________ 2269
17.2.2 Starting and logging on to BMC Remedy Developer Studio ___________________________ 2272
17.2.3 Using menu options in BMC Remedy Developer Studio ______________________________ 2273
17.2.4 Event Navigator ____________________________________________________________ 2274
17.2.5 Using buttons and menu bar items to execute active links ___________________________ 2276
17.2.6 Modifier keywords for use in workflows _________________________________________ 2279
17.2.7 Understanding the AR System Navigator _________________________________________ 2280
17.2.8 Working with perspectives ___________________________________________________ 2281
17.2.9 Creating objects ___________________________________________________________ 2285
17.2.10Working with existing objects _________________________________________________ 2287
17.2.11Finding objects ____________________________________________________________ 2295
17.2.12Using working lists _________________________________________________________ 2304
17.2.13Using the Outline tab _______________________________________________________ 2307
17.2.14Using the Messages tab _____________________________________________________ 2309
17.2.15Printing from BMC Remedy Developer Studio _____________________________________ 2309
17.2.16Creating reports for selected objects ___________________________________________ 2310
17.2.17BMC Developer Studio frequently asked questions _________________________________ 2312
17.2.18Differences between BMC Remedy Administrator and BMC Remedy Developer Studio _____ 2314
17.3 Setting up the development environment _____________________________________________ 2319
17.3.1 Packing lists ______________________________________________________________ 2320
17.3.2 Creating packing lists _______________________________________________________ 2320

17.3.3 Saving packing lists as XML import or export command files __________________________ 2322
17.3.4 Working with applications and packing lists ______________________________________ 2323
17.3.5 Version control in BMC Remedy AR System ______________________________________ 2325
17.3.6 Using object reservation _____________________________________________________ 2327
17.3.7 Using the object modification log ______________________________________________ 2329
17.3.8 Development modes ________________________________________________________ 2336
17.4 Defining and managing an application ________________________________________________ 2343
17.4.1 Local applications __________________________________________________________ 2343
17.4.2 Deployable applications _____________________________________________________ 2343
17.4.3 Alternatives for presenting applications to users ___________________________________ 2363
17.4.4 Deleting an application ______________________________________________________ 2366
17.5 Developing the application interface _________________________________________________ 2366
17.5.1 BMC Remedy AR System forms ________________________________________________ 2366
17.5.2 BMC Remedy AR System installed forms _________________________________________ 2395
17.5.3 Using templates to dynamically present HTML content from a form ____________________ 2401
17.5.4 Working with panels ________________________________________________________ 2406
17.5.5 Working with tables ________________________________________________________ 2437
17.5.6 Working with menus ________________________________________________________ 2498
17.5.7 Working with images _______________________________________________________ 2520
17.5.8 Creating and managing fields _________________________________________________ 2525
17.5.9 Recommendations while developing applications __________________________________ 2626
17.6 Adding graphics to an application with flashboards ______________________________________ 2629
17.6.1 BMC Remedy Flashboards overview ____________________________________________ 2629
17.6.2 Data flow in flashboards _____________________________________________________ 2629
17.6.3 Types of flashboards ________________________________________________________ 2630
17.6.4 Process for creating a flashboard ______________________________________________ 2637
17.6.5 Planning a flashboard _______________________________________________________ 2637
17.6.6 Creating flashboard variables _________________________________________________ 2638
17.6.7 Creating and managing flashboards ____________________________________________ 2642
17.6.8 Adding a flashboard to a BMC Remedy AR System form _____________________________ 2649
17.7 Securing your application _________________________________________________________ 2662
17.7.1 Related topics _____________________________________________________________ 2663
17.7.2 Access control for a deployable application ______________________________________ 2663
17.7.3 Granting permission to applications and their objects _______________________________ 2664
17.8 Defining workflow to automate processes ____________________________________________ 2664
17.8.1 Introducing workflow _______________________________________________________ 2664
17.8.2 Configuring workflow forms and execution options ________________________________ 2677
17.8.3 Building qualifications and expressions __________________________________________ 2689
17.8.4 Specifying workflow actions __________________________________________________ 2740
17.8.5 Workflow processing _______________________________________________________ 2847
17.8.6 Workflow extras ___________________________________________________________ 2856
17.9 Mid tier application development guidelines ___________________________________________ 2868
17.9.1 Managing resource files _____________________________________________________ 2868

17.9.2 URLs for forms and applications _______________________________________________ 2870

17.9.3 Creating login and logout buttons _____________________________________________ 2878
17.9.4 Creating customized login pages ______________________________________________ 2880
17.9.5 Using the Object List ________________________________________________________ 2880
17.9.6 Embedding web content in an application through data visualization fields ______________ 2882
17.9.7 Browser settings for scripting and ActiveX controls ________________________________ 2896
17.9.8 How a view is selected ______________________________________________________ 2898
17.9.9 How the locale is established _________________________________________________ 2898
17.9.10Types of browser searches for end users ________________________________________ 2898
17.9.11Setting up the query builder widget for end users __________________________________ 2899
17.9.12Including parameters in saved or defined searches _________________________________ 2901
17.9.13Creating help for web applications _____________________________________________ 2902
17.10Adding approvals to an application __________________________________________________ 2903
17.10.1Designing an approval application _____________________________________________ 2903
17.10.2Integrating Approval Server with an application ___________________________________ 2903
17.10.3Adding notifications to the approval process _____________________________________ 2909
17.10.4Creating notifications _______________________________________________________ 2910
17.10.5Enhancing your approval forms _______________________________________________ 2916
17.10.6Adding previews to your approval application _____________________________________ 2919
17.10.7Using the multi-process preview _______________________________________________ 2921
17.10.8Using a custom ad hoc dialog box with the approval server __________________________ 2921
17.10.9Calling Approval Server application commands in your application ____________________ 2922
17.11Building performance into applications and workflow ____________________________________ 2924
17.12Customizing applications using overlays and custom objects ______________________________ 2927
17.12.1About origin objects and custom objects ________________________________________ 2928
17.12.2About overlays ____________________________________________________________ 2929
17.12.3Creating custom objects _____________________________________________________ 2943
17.12.4Creating overlays to customize objects _________________________________________ 2944
17.12.5Working with overlays and custom objects _______________________________________ 2953
17.12.6Hiding unmodified objects in Best Practice Customization mode ______________________ 2970
17.12.7Converting custom objects to origin objects ______________________________________ 2971
17.12.8Converting origin objects to custom objects _____________________________________ 2972
17.12.9About export and import operations on overlays and custom objects ___________________ 2974
17.12.10About auditing and archiving overlays and custom objects __________________________ 2975
17.13Customizing the interface for multiple consumers ______________________________________ 2977
17.13.1Customizing applications with Cascading Style Sheets ______________________________ 2977
17.13.2Customizing views for forms in browsers ________________________________________ 2991
17.13.3Defining and managing form views _____________________________________________ 2998
17.13.4Customizing the home page and entry points ____________________________________ 3032
17.14Localizing an application to other languages __________________________________________ 3055
17.14.1Localizing BMC Remedy AR System applications ___________________________________ 3055
17.14.2Using the localization toolkit to localize your applications ___________________________ 3072
17.15Making your application accessible - Section 508 compatibility ____________________________ 3096

Making your application accessible - Section 508 compatibility ___________________________ 3096
17.15.1What Section 508 support means ______________________________________________ 3097
17.15.2Setting accessibility options __________________________________________________ 3097
17.15.3Accessibility features _______________________________________________________ 3098
17.15.4Section 508 testing _________________________________________________________ 3099
17.15.5Web settings to support Section 508 ___________________________________________ 3099
17.15.6JAWS settings for the Web ___________________________________________________ 3101
17.15.7Low Vision users and BMC Remedy AR System clients ______________________________ 3104
17.15.8No Vision support for BMC Remedy AR System features _____________________________ 3104
17.15.9Shortcut keys for BMC Remedy AR System _______________________________________ 3116
17.15.10Executing active links on the Web _____________________________________________ 3118
17.15.11BMC Remedy Mid Tier and caching ____________________________________________ 3118
17.15.12BMC Remedy Mid Tier and RTL _______________________________________________ 3119
17.15.13Form design ______________________________________________________________ 3119
17.15.14Verifying your BMC Remedy AR System forms ____________________________________ 3122
17.15.15Section 508 rules for application designers ______________________________________ 3122
17.15.16Section 508 rules for others _________________________________________________ 3129
17.16Testing and debugging a BMC Remedy AR System application _____________________________ 3130
17.16.1Application debugging process ________________________________________________ 3130
17.16.2Debugging tools ___________________________________________________________ 3132
17.16.3Active link debugging example ________________________________________________ 3132
17.16.4The BMC Remedy AR System workflow debugger __________________________________ 3133
17.16.5Using Analyzer to find problems in your applications _______________________________ 3142
17.16.6Working with the Analyzer View tab ____________________________________________ 3154
17.16.7Launching the Analyzer from a command line ____________________________________ 3156
17.16.8Capturing application performance with the Mid-Tier Profiler ________________________ 3162
17.16.9HTTP tracing in the mid tier __________________________________________________ 3162
17.16.10Measuring BMC Remedy AR System application performance ________________________ 3163
17.17Moving to production ____________________________________________________________ 3250
17.17.1Importing and exporting object definitions and locking objects _______________________ 3250
17.17.2BMC Remedy AR System definitions ____________________________________________ 3251
17.17.3Exporting and importing definitions ____________________________________________ 3252
17.18Distributing an application ________________________________________________________ 3263
17.18.1Locking objects ____________________________________________________________ 3263
17.18.2Making applications licensable for integration system vendors ________________________ 3268
17.19Publishing the BMC Remedy AR System functionality as a web service _______________________ 3274
17.19.1AR System and web services introduction ________________________________________ 3275
17.19.2Web service standards ______________________________________________________ 3275
17.19.3Predefined BMC Remedy AR System web services _________________________________ 3278
17.19.4Forms and field mappings for web services _______________________________________ 3278
17.19.5Basic and custom web services ________________________________________________ 3278
17.19.6Creating web service clients __________________________________________________ 3279
17.19.7Setting up the environment for web services _____________________________________ 3283
17.19.8Publishing a web service _____________________________________________________ 3287

Publishing a web service ____________________________________________________ 3287
17.19.9Registering a web service ____________________________________________________ 3293
17.19.10Consuming a web service ___________________________________________________ 3300
17.19.11Mapping web service data ___________________________________________________ 3306
17.19.12Using join forms in web services ______________________________________________ 3314
17.19.13Web service operation types _________________________________________________ 3316
17.19.14Web service scenarios ______________________________________________________ 3321
17.19.15XML editing ______________________________________________________________ 3341
17.19.16Supported schema constructs and web service limitations __________________________ 3350
17.19.17SOAP headers and authentication _____________________________________________ 3352
18 Developing an API program ____________________________________________________________ 3358
18.1 API overview ___________________________________________________________________ 3359
18.2 When to use API programming _____________________________________________________ 3359
18.3 BMC Remedy AR System C API overview ______________________________________________ 3360
18.3.1 Client-server application model _______________________________________________ 3360
18.3.2 BMC Remedy AR System API library functions _____________________________________ 3362
18.3.3 BMC Remedy AR System C API program structure _________________________________ 3362
18.3.4 Multithreaded API clients ____________________________________________________ 3363
18.3.5 Using the BMC Remedy AR System API for integration ______________________________ 3364
18.3.6 BMC Remedy AR System API issues and considerations _____________________________ 3366
18.4 BMC Remedy AR System C API installation and compilation requirements ____________________ 3366
18.4.1 BMC Remedy AR System C API package contents __________________________________ 3366
18.4.2 Migrating to the current release of BMC Remedy AR System C API _____________________ 3375
18.4.3 Compile and link requirements ________________________________________________ 3378
18.5 Data structures _________________________________________________________________ 3381
18.5.1 Data relationships __________________________________________________________ 3381
18.5.2 C data types ______________________________________________________________ 3382
18.5.3 Lists and structures _________________________________________________________ 3383
18.5.4 High-level object relationships ________________________________________________ 3384
18.5.5 Login and session information ________________________________________________ 3386
18.5.6 Status information __________________________________________________________ 3387
18.5.7 Permissions and structures ___________________________________________________ 3390
18.5.8 Group information and structures ______________________________________________ 3391
18.5.9 Structures for ARGetListEntryWithMultiSchemaFields _______________________________ 3410
18.5.10Filters, escalations, and active links and structures _________________________________ 3425
18.5.11Character menus and data structures ___________________________________________ 3439
18.5.12Images and data structures __________________________________________________ 3440
18.5.13Containers and structures ___________________________________________________ 3440
18.5.14Overlays and structures _____________________________________________________ 3447
18.5.15Server object properties and structures _________________________________________ 3447
18.5.16Importing and exporting and structures _________________________________________ 3451
18.5.17Freeing allocated memory ___________________________________________________ 3453
18.5.18XML formats ______________________________________________________________ 3455
18.6 BMC Remedy AR System C API functions ______________________________________________ 3456

18.6.1 Types of functions _________________________________________________________ 3456

18.6.2 Function descriptions _______________________________________________________ 3462
18.7 Creating and executing BMC Remedy AR System C API programs ___________________________ 3836
18.7.1 Program structure __________________________________________________________ 3837
18.7.2 Performing common tasks ___________________________________________________ 3838
18.7.3 Specifying fields or keywords _________________________________________________ 3841
18.7.4 Error checking ____________________________________________________________ 3842
18.7.5 Executing C API programs in workflow __________________________________________ 3843
18.7.6 Program design tips ________________________________________________________ 3845
18.7.7 Multithreaded C API clients ___________________________________________________ 3845
18.7.8 Impersonating a user _______________________________________________________ 3845
18.7.9 Enabling client-managed transactions __________________________________________ 3846
18.7.10Sending alerts to a filter API plug-in ____________________________________________ 3847
18.8 Debugging API programs _________________________________________________________ 3848
18.8.1 Logging BMC Remedy AR System activity ________________________________________ 3848
18.8.2 Using the driver program ____________________________________________________ 3848
18.9 BMC Remedy AR System plug-in API functions _________________________________________ 3854
18.9.1 AR System plug-in API functions _______________________________________________ 3854
18.9.2 AREA plug-in API functions ___________________________________________________ 3859
18.9.3 ARDBC plug-in API functions _________________________________________________ 3864
18.9.4 AR Filter API plug-in functions ________________________________________________ 3882
18.10XML transformation routines ______________________________________________________ 3883
18.10.1Transforming XML and BMC Remedy AR System objects ____________________________ 3883
18.10.2Object API functions _______________________________________________________ 3884
18.10.3Using the object XML functions _______________________________________________ 3886
18.10.4Object API function descriptions ______________________________________________ 3888
18.11Retrieving entries from multiple forms _______________________________________________ 3976
18.11.1About ARGetListEntryWithMultiSchemaFields _____________________________________ 3976
18.11.2Dynamic joins _____________________________________________________________ 3980
18.11.3Recursive queries __________________________________________________________ 3983
18.11.4Value set queries __________________________________________________________ 3989
18.11.5Vendor form joins __________________________________________________________ 3995
18.12BMC Remedy AR System Java API overview ___________________________________________ 3996
18.12.1BMC Remedy AR System Java API installed files ___________________________________ 3996
18.12.2Runtime configuration ______________________________________________________ 3998
18.12.3BMC Remedy AR System Java API programming model _____________________________ 3999
18.12.4Programming with the Java API _______________________________________________ 4000
18.12.5Java API sample code for managing BMC Remedy AR System records __________________ 4001
19 Troubleshooting ____________________________________________________________________ 4007
19.1 Troubleshooting BMC Remedy AR System installation, migration, or upgrade _________________ 4008
19.1.1 Free and available ports _____________________________________________________ 4009
19.1.2 Server issues on DB2 _______________________________________________________ 4009
19.1.3 BMC Remedy Approval Server installation and upgrade issues ________________________ 4009

19.1.4 Locating BMC Remedy AR System files and forms __________________________________ 4010
19.1.5 Troubleshooting BMC Remedy Migrator installation ________________________________ 4016
19.1.6 Installation issues on an Oracle database ________________________________________ 4016
19.1.7 Understanding digital signatures for Windows installers _____________________________ 4016
19.2 Gathering information for support ___________________________________________________ 4017
19.2.1 Collecting AR System server information _________________________________________ 4017
19.2.2 Collecting Mid tier information ________________________________________________ 4017
19.2.3 Collecting BMC Remedy Email Engine information _________________________________ 4018
19.2.4 Collecting BMC Remedy Assignment Engine information ____________________________ 4018
19.2.5 Collecting BMC Remedy Approval Server information _______________________________ 4019
19.2.6 Collecting Data Import Tool information ________________________________________ 4019
19.2.7 Collecting BMC Atrium CMDB information _______________________________________ 4020
19.3 Collecting diagnostics ____________________________________________________________ 4020
19.3.1 Collecting diagnostics in a zip file ______________________________________________ 4020
19.3.2 Displaying version information ________________________________________________ 4021
19.3.3 Checking the database tables _________________________________________________ 4022
19.3.4 Creating flashboards to collect server statistics ___________________________________ 4026
19.3.5 Tracking cache loads _______________________________________________________ 4030
19.4 Working with logs _______________________________________________________________ 4039
19.4.1 BMC Remedy Mid Tier preload logs ____________________________________________ 4039
19.4.2 Using log files _____________________________________________________________ 4040
19.4.3 Enabling logs _____________________________________________________________ 4040
19.4.4 Analyzing logs _____________________________________________________________ 4081
19.4.5 Running the Maintenance Tool ________________________________________________ 4120
19.4.6 Logging and monitoring AR System server _______________________________________ 4121
19.4.7 Additional troubleshooting resources ___________________________________________ 4123
19.4.8 Viewing logs ______________________________________________________________ 4123
19.5 Working with error messages ______________________________________________________ 4130
19.5.1 BMC Remedy Migrator error messages __________________________________________ 4131
19.5.2 BMC Remedy AR System diagnostic messages ____________________________________ 4150
19.5.3 BMC Remedy AR System error messages _________________________________________ 4154
19.6 Troubleshooting BMC Remedy AR System performance issues _____________________________ 4350
19.6.1 Peak use issues ____________________________________________________________ 4351
19.6.2 Hardware issues ___________________________________________________________ 4352
19.6.3 Memory configuration issues _________________________________________________ 4353
19.6.4 Multithreaded server configuration _____________________________________________ 4353
19.6.5 Checking log files for long-running operations ____________________________________ 4355
19.7 Troubleshooting server processes on Windows _________________________________________ 4355
19.8 Troubleshooting BMC Remedy Mid Tier ______________________________________________ 4355
19.8.1 Troubleshooting out-of-memory exceptions in the BMC Remedy Mid Tier _______________ 4355
19.8.2 Resolving attachment issues in BMC Remedy Mid Tier ______________________________ 4357
19.8.3 BMC Remedy Mid Tier troubleshooting tips ______________________________________ 4358
19.9 Troubleshooting BMC Remedy Developer Studio issues __________________________________ 4359

19.9.1 Q: When I use a preference server, why are some preferences still stored locally? _________ 4359
19.9.2 Q: Sometimes, menu commands in the Form, Layout, and Workflow menus are not available
(disabled). How do I make them available? ______________________________________________ 4359
19.9.3 Q: The tabs in my perspective are not where I want them or I can't find them. How I do fix the
perspective? _____________________________________________________________________ 4359
19.9.4 Q: When I try to start BMC Remedy Developer Studio, it reports that my workspace is locked. How
can I unlock my workspace? _________________________________________________________ 4360
19.9.5 Q: Where are all the preferences from the Preferences dialog box of BMC Remedy Administrator?
4360
19.10Troubleshooting BMC Remedy Flashboards ___________________________________________ 4361
19.10.1Troubleshooting BMC Remedy Flashboards displays ________________________________ 4361
19.10.2Using the FBImageServlet to test a flashboard ____________________________________ 4364
19.11Troubleshooting BMC Remedy Email Engine ___________________________________________ 4364
19.11.1Troubleshooting outgoing email _______________________________________________ 4365
19.11.2Temporary directories and files ________________________________________________ 4365
19.11.3Recommendations for avoiding outages _________________________________________ 4366
19.11.4Fixing common problems with the BMC Remedy Email Engine _______________________ 4366
19.11.5Configuring mailboxes ______________________________________________________ 4367
19.11.6Defining a heap size for the BMC Remedy Email Engine _____________________________ 4368
19.11.7Troubleshooting startup issues ________________________________________________ 4369
19.11.8Determining problems with the mail server _______________________________________ 4371
19.11.9Email daemon issues when AR System server stops ________________________________ 4374
19.11.10Making changes to mailbox configuration _______________________________________ 4374
19.11.11Submitting email requests across different time zones _____________________________ 4375
19.11.12Verifying permissions for the Windows accounts __________________________________ 4375
19.11.13Troubleshooting email request processing and notification filters _____________________ 4376
19.11.14Fixing issues with notifications that fail _________________________________________ 4376
19.11.15Temporary directories and files _______________________________________________ 4377
19.12Troubleshooting BMC Remedy Approval Server ________________________________________ 4378
19.12.1BMC Remedy Approval Server configuration file settings ____________________________ 4378
19.12.2Accessibility issues _________________________________________________________ 4379
19.12.3Error 333 and Assignee Group Permission _______________________________________ 4379
19.12.4Runtime issues ____________________________________________________________ 4380
19.12.5Common error messages for BMC Remedy Approval Server and BMC Remedy Assignment Engine
signaling ________________________________________________________________________ 4380
19.12.6BMC Remedy Approval Server files _____________________________________________ 4382
19.13Troubleshooting BMC Remedy Assignment Engine ______________________________________ 4383
19.13.1BMC Remedy Assignment Engine files __________________________________________ 4383
19.14Troubleshooting BMC Remedy Distributed Server Option ________________________________ 4384
19.14.1Errors encountered by Distributed Server Option __________________________________ 4384
19.14.2BMC Remedy Distributed Server Option files _____________________________________ 4385
19.14.3Verifying the Distributed Server Option is in active state _____________________________ 4386
19.14.4Missing distributed operations ________________________________________________ 4387

Missing distributed operations _______________________________________________ 4387
19.14.5Performance issues processing Distributed Server Option operations __________________ 4387
19.15Troubleshooting full text search ____________________________________________________ 4388
19.15.1To enable FTS index logging __________________________________________________ 4388
19.15.2To enable SQL logging ______________________________________________________ 4389
19.15.3Cannot connect to the Java plug-in server _______________________________________ 4389
19.16Troubleshooting plug-in issues _____________________________________________________ 4389
19.16.1General approach for troubleshooting plug-in issues _______________________________ 4390
19.16.2Enabling server-side AR System logs ____________________________________________ 4391
19.16.3Troubleshooting issues with plug-in servers ______________________________________ 4392
19.16.4Troubleshooting issues with ARDBC plug-ins _____________________________________ 4395
19.16.5Troubleshooting issues with AR System Filter API plug-ins ___________________________ 4409
19.16.6Troubleshooting issues with AREA plug-ins ______________________________________ 4435
19.17Troubleshooting encryption security ________________________________________________ 4438
19.17.1Java-based encryption ______________________________________________________ 4438
19.17.2Related topics _____________________________________________________________ 4439
19.18Troubleshooting BMC Remedy SNMP Agent ___________________________________________ 4439
19.19Troubleshooting issues with BMC Atrium CMDB _______________________________________ 4440
19.20Troubleshooting alert activity ______________________________________________________ 4441
19.20.1Using alerts in a server group _________________________________________________ 4441
19.20.2Checking the status of alerts _________________________________________________ 4441
19.20.3Using alert and Web service logs to check alert activity _____________________________ 4442
19.21Searching the Knowledge Base _____________________________________________________ 4442
19.21.1To search the Knowledge Base ________________________________________________ 4442
19.22Troubleshooting issues connecting to the AR System server ______________________________ 4443
19.22.1Related topic _____________________________________________________________ 4443
19.22.2Running arconnect ________________________________________________________ 4443
19.23BMC Remedy AR System Maintenance tool ___________________________________________ 4448
20 Known and corrected issues ___________________________________________________________ 4449
20.1 BMC Remedy AR System known and corrected issues ____________________________________ 4449
20.1.1 Installation and upgrade known and corrected issues _______________________________ 4449
20.1.2 BMC Remedy AR System server known and corrected issues _________________________ 4454
20.1.3 BMC Remedy Approval Server known and corrected issues __________________________ 4461
20.1.4 BMC Remedy Developer Studio known and corrected issues _________________________ 4462
20.1.5 BMC Remedy Email Engine known and corrected issues ____________________________ 4466
20.1.6 BMC Remedy Mid Tier known and corrected issues ________________________________ 4467
20.1.7 BMC Remedy AR System documentation known and corrected issues __________________ 4483
20.1.8 BMC Remedy Assignment Engine known and corrected issues ________________________ 4485
20.1.9 BMC Remedy Flashboards known and corrected issues _____________________________ 4485
20.1.10Accessibility known and corrected issues ________________________________________ 4486
20.1.11BMC Remedy Pre-Checker utility known and corrected issues ________________________ 4486
20.2 BMC Remedy Encryption Security known and corrected issues _____________________________ 4487
20.3 BMC Remedy Migrator known and corrected issues _____________________________________ 4487
21 Support information _________________________________________________________________ 4489

21.1 Contacting Customer Support _____________________________________________________ 4489

21.2 Support status __________________________________________________________________ 4489
22 Additional resources _________________________________________________________________ 4490

This space contains information about the 8.1 release of the BMC Remedy Action Request System (BMC Remedy
AR System), BMC Remedy Encryption Security, and BMC Remedy Migrator products.
Warning
(November 2013) Issue when using BMC Remedy IT Service Management Suite 8.1 on Microsoft
Windows 8.0 with IE 10 or Microsoft Windows 8.1 with IE 11
(September 2013) Issue while logging in to the BMC Remedy IT Service Management application.

1 Featured content
To learn about the latest features in this release, see What's new, particularly:
Service Pack 1: 8.1.01

Patch 2 for version 8.1.00: 8.1.00.002
Patch 1 for version 8.1.00: 8.1.00.001
For information about the issues in this release, see Known and corrected issues.
For new topics about features already present in version 8.1, see Documentation updates.
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 Installing or Upgrading.
The BMC Remedy User and BMC Remedy Alert clients are no longer installed. For details, see the End of
Life statement (Support login required).

2 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.

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

4 About BMC Remedy Encryption Premium

Security
BMC Remedy Encryption Premium Security (BMC Remedy Encryption Premium) enables the AR System server
and its clients to communicate securely over a network by encrypting the messages sent between them.
Encryption makes sure that the communication is secure and that third parties cannot decipher the messages in
transit. Premium Security includes third-party encryption software developed by the OpenSSL Project for use in
the OpenSSL toolkit.
Premium Security 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
AES CBC with a 256-bit key for data encryption and a 2048-bit modulus for the RSA key exchange
BMC Remedy Encryption Premium uses SHA-1 for message authentication, and it also supports the minimum
Federal Information Processing Standard (FIPS) 140-2 encryption requirements.

5 About BMC Remedy Encryption Performance

Security
BMC Remedy Encryption Performance Security (BMC Remedy Encryption Performance) enables the AR System
server and its clients to communicate securely over a network by encrypting the messages sent between them.
This encryption makes sure that the communication is secure and that third parties cannot decipher the
messages in transit. BMC Remedy Encryption Performance includes third-party encryption software developed by
the OpenSSL Project for use in the OpenSSL toolkit.
BMC Remedy Encryption Performance 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.
BMC Remedy Encryption Performance uses SHA-1 for message authentication, and it also supports the minimum
FIPS 140-2 encryption requirements.

6 About BMC Remedy Migrator

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 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 can migrate 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 a file
to a file, and can migrate data from one form to another as well as to a file.

7 What's new
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
February 27, 2013 New videos for overlays

Customizing applications using overlays and custom objects
Granular overlays
August 5, 2013 Patch 1 for version 8.1.00: 8.1.00.001 Patch 1 for BMC Remedy AR System 8.1
September 13, 2013 Patch 2 for version 8.1.00: 8.1.00.002 Patch 2 for BMC Remedy AR System 8.1
January 31, 2014 Service Pack 1 for version 8.1.00 Service pack 1 for BMC Remedy AR System 8.1
7.1 Urgent issues

This section contains information about issues in the BMC Remedy AR System product that require your
immediate attention.

7.1.1 Issue when using BMC Remedy IT Service Management Suite 8.1 on
Microsoft Windows 8.0 with IE 10 or Microsoft Windows 8.1 with IE 11
Due to a Microsoft defect related to Internet Explorer 10 (Microsoft support ticket number 113100110828856) and
Internet Explorer 11, when using BMC Remedy IT Service Management version 8.1 on Microsoft Windows 8.0 or
Microsoft Windows 8.1, you may experience performance problems wherein the Client CPU reaches 100% and
does not respond for an extended period of time.
Note
Until this issue is addressed by Microsoft, BMC Software does not support the Microsoft Windows 8.0
and Internet Explorer 10 or Microsoft Windows 8.1 and Internet Explorer 11 combination with BMC
Remedy IT Service Management version 8.1.
This Internet Explorer 10 and Internet Explorer 11 defect does not occur with BMC Remedy IT Service
Management version 7.6.04. Also, this defect does not occur with Microsoft Windows 7 as the operating
system.
Workaround: BMC recommends that if you are using BMC Remedy IT Service Management version 8.1 on
Microsoft Windows 8.0, use Mozilla Firefox as the browser instead of Internet Explorer 10.
If you cannot use Mozilla Firefox, alternatively, you can disable the Adobe Flash Add-On (Shockwave Flash Object)
of Internet Explorer 10 or Internet Explorer 11 in BMC Remedy Mid-Tier, as the Adobe Flash Add-On exposes this
defect.
Note
If you disable Adobe Flash Add-On, only the Home page performance issue is resolved; the scroll bar
issue is not resolved. Additionally, this will impact the BMC Flashboards plug-in, the BMC Atrium
Console, and any other components that use Adobe Flash Add-On.
7.1.2 Issue while logging in to the BMC Remedy IT Service Management

application
Due to a TCP connection leak with the C API, the BMC Remedy AR System server and any other ancillary binary
that uses the C API (for example, arsignal.exe, driver.exe, arplugin.exe, etc.) causes the number of TCP ports that
are being utilized to grow steadily. Due to this, there are no TCP connection ports available on the system and the
system appears to have stopped responding to all clients. Since there are no service login attempts available, the
login to the BMC Remedy IT Service Management application fails with the following error message:

There are currently no logon servers available to service the logon request.
This issue has been resolved in the BMC Remedy AR System version 8.1.00 patch 2. For more information about
the steps for installing the patch, see Patch 2 for version 8.1.00: 8.1.00.002.
For more information about this issue, see the issue number SW00450386 on BMC Remedy AR System server
known and corrected issues. Additional information is available in the Knowledge article KA403677.
7.2 Documentation updates

This topic contains information about documentation updates for BMC Remedy AR System that are not related to
urgent issues, maintenance releases, service packs, or patches.
7.2.1 Added BIRT report documentation

May 14, 2013: Using a BIRT editor to create or modify web reports explains how to use BIRT reporting tools with
BMC Remedy Action Request System Web reports.
7.2.2 Added videos

Videos were added to the following topics:
February 27, 2013: Customizing applications using overlays and custom objects
February 27, 2013: Granular overlays
April 8, 2013: Installing
April 8, 2013: Installing a server group
7.2.3 Added recommendations for analyzing AR System Log Analyzer

output and troubleshooting issues connecting to the AR System server
February 22, 2013: The following topics were added to the Troubleshooting branch:
Analyzing AR System Log Analyzer output

Troubleshooting issues connecting to the AR System server
7.2.4 Added an example for customizing AR forms

December 5, 2013: Example for changing the look and feel of AR forms explains how to change a BMC Remedy
AR form’s standard look-and-feel to a more modern, personalized, and flat look.

7.3 Service Pack 1: 8.1.01

The following topics describe the updates, limitations and fixes available in Service Pack 1 for version 8.1.00 and
direct you to the instructions for downloading and installing the service pack.
7.3.1 Enhancements
Service Pack 1 provides enhancements in the following BMC Remedy AR System applications and components:
BMC Remedy Pre-Checker Utility
The BMC Remedy AR System application install or upgrade is highly dependent on the environment
configuration, the BMC Remedy AR System server configuration, and customization. When you manually validate
the environment before install, you might see issues when the install or upgrade process fails, after which
reverting the system and restarting the install is a costly and time consuming process.
To avoid this, a new BMC Remedy Pre-Checker Utility has been introduced. This utility is a centralized framework
utility that validates the environment for BMC Remedy AR System install or upgrade. It also validates conflicting
BMC Remedy AR System server configuration and customizations that might cause the installation or upgrade to
fail, and generates a consolidated report.
For more information about this utility, see BMC Remedy Pre-Checker utility.
High availability for FTS by using multiple indexing servers
Before Service Pack 1, BMC Remedy Full Text Search (FTS) required that one server in a server group act as the
FTS server. With version 8.1.00 Service Pack 1, 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.
For more information about the high-availability architecture, see High-availability architecture for FTS.
Terminology changes in FTS

Starting from this release, the following new terms are used for FTS plug-ins:
FTS Writer is now called the FTS Indexer

FTS Reader is now called the FTS Searcher
Obtaining performance statistics
Before Service Pack 1, AR System server enabled you to gather performance statistics on the server. With Service
Pack 1, you can also gather statistics about the longest running SQL and API calls. Finding out which calls are
causing delays can help you troubleshoot performance issues. For more information, see Investigating slow BMC
Remedy AR System API calls.
For more information, see:

Setting server statistics options

ar.cfg or ar.conf options A-B
ARGetServerInfo
Security enhancements
The following topics provide information about the security enhancements and new features in this release:
Security enhancements for the mid tier
You can now log on to BMC Remedy Mid Tier using only HTTP POST requests.
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 arsystem.inclusion_goto_urls property in the
<midTierInstallDirectory>/WEB-INF/classes/config.properties file. For more information, see Adding
inclusion list for Mid Tier.
New parameter for encrypting information

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 the
Workflow-Encryption-Algorithm:x parameter to the ar.cfg or ar.conf file. For more information about this
parameter, see Workflow-Encryption-Algorithm.
Security restrictions on file uploads

You can now restrict BMC Remedy Action Request System (AR System) users from uploading and viewing files
with certain extensions in BMC Remedy Mid Tier and BMC Remedy User Tool. This feature helps prevent users
from uploading malicious attachments and viewing them. For more information, see Setting security restrictions
on file uploads.
Other enhancements
The following topics provide information about the other enhancements in this release:
Copying field information to a new request

New Run Process command
FTS performance enhancement
Enhancements on Approval Central
Wait cursor
Using a jump key in table fields
7.3.2 Known and Corrected issues

For information about the issues that are corrected in this service pack, see:

Known and Corrected issues in Service Pack 1

Known and Corrected issues for BMC Remedy Migrator in Service Pack 1
7.3.3 Downloading the service pack

For download instructions, see Downloading the service pack files from the EPD website.
7.3.4 Installing the service pack

For information about installing the Service Pack 1, see Applying Service Pack 1:8.1.01.
7.3.5 Applying Service Pack 1: 8.1.01

Before you can use the BMC Remedy AR System server, BMC recommends that you apply the latest patches and
service packs. For details about the latest updates and corrected issues, see Service Pack 1: 8.1.01.
Before you begin
You must have downloaded the latest service pack, as described in Downloading the installation files.
If you are upgrading, you must deactivate FTS before you begin the upgrade.
Installing 8.1.00 Service Pack 1 on BMC Remedy AR System

To install all components or features, run the appropriate BMC Remedy AR System installer as described in
Performing a new installation.
Note
For additional information about BMC Remedy AR System 8.1.00 upgrade, see Upgrading.
After you install the service pack, the following changes appear:
The Version attribute in the arerror.log file is set to 8.1.00 SP1 <dateTimeStamp>.
The Server Version field on the AR System Administration Console is set to 8.1.00 SP1 < dateTimeStamp>.
The Version application property on the SHARE:Application_Properties form is set to 8.1.01.
The Patch application property on the SHARE:Application_Properties form is deleted if you installed a
patch earlier.
Note
The BMC Remedy AR System suite installer does not accept a fully qualified host name for the AR
System server name alias. Enter only a valid server alias.

You can update a specific feature or all features with the installer.
If you previously installed any features by using the original BMC Remedy AR System 8.1.00 installer, the
check boxes for these features are automatically selected when you run a service pack installer. If you
leave the check boxes selected, the features are upgraded. If you clear the check boxes, the features are
not upgraded, but they remain on your computer.
If you install any features by using a service pack installer (instead of the release 8.1.00 installer) and then
you use that service pack installer again to install another feature on the same computer, the check boxes
for the previously installed features are selected. These features are not reinstalled, but the installer checks
for missing files and restores them if necessary.
All Approval Server customizations are lost when you upgrade to BMC Remedy AR System version 8.1.00
and later versions.
Note
All features in the BMC Remedy AR System suite installer are designated as updated for Service Pack 1.
This release might not include resolved issues for some features, but the features’ binaries were updated
due to dependencies on other features. The time stamps for such binaries differ from those delivered in
the earlier release.
Installing 8.1.00 Service Pack 1 on BMC Remedy Migrator

Run the appropriate BMC Remedy Migrator installer as described in Installing BMC Migrator.
Installing 8.1.00 Service Pack 1 on BMC Remedy Encryption Security

Run the appropriate BMC Remedy Encryption Performance Security installer as described in Installing BMC
Remedy Encryption Security.
7.3.6 Other enhancements for Service Pack 1

This topic provides information about the following enhancements and new features in this release:
Copying field information to a new request

You can 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. For more information about how to copy field
information to a new request, see Copying field information to a new request.

Note
This feature is not available in Service Pack 1 for the BMC Remedy ITSM Suite and BMC Atrium Core
products. You might receive an error message if you try to use this functionality.
New Run Process command

The SECURITY-FILTER <fieldName> command handles security-related issues before a string input from a user is
used in any HTML element and displayed back to the user. You can use a Set Fields action to call the process and
use any string field value as the input parameter, and then get the result back.
For more information about process commands, see Process commands.
FTS performance enhancement

To improve the performance of the full text search (FTS) indexer, set the value of Max Threads for the FTS indexer
queue between 3 and 5.
Enhancements on Approval Central

The following tables on Approval Central now display 10 records at a time instead of 5:
Pending Approvals table

Approval Search results table
Right to left (RTL) support BMC Remedy Mid Tier now provides right to left (RTL) support. The text direction of
languages such as Arabic and Hebrew flows from RTL instead of the Western left to right (LTR).
Wait cursor
A wait cursor now appears in the browser while you wait for a table to load.
Note
products.
Using a jump key in table fields

Previously in BMC Remedy User, when you highlighted a row in a list table, you could press a character on the
keyboard to jump to the next row whose text in its first column began with that character. For example, if the first
row was highlighted and you pressed J, the row in which the first column displayed “John Smith” would be
highlighted. This function now works in browsers.

Note
products.
Browser cache enhancements

Starting with Service Pack 1, 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 the browser.
For more information, see Updating browser cache.
7.4 Patch 2 for version 8.1.00: 8.1.00.002

This topic contains information about updates and fixes in this patch, and provides instructions for downloading
and installing the patch.
Known and Corrected issues
Notes
You can install this patch on 64-bit computers, not 32-bit.

You must have installed BMC Remedy Action Request (AR) System 8.1.00 before running patch
installer.
Patch 2 is cumulative, containing all the fixes in Patch 1 for all the components.
When the AR System patch is being applied, the patch installer restarts the AR System server as
part of the installation process.
The patch installer does not use Install Anywhere Framework and is not affected by the
IATEMPDIR system variable. If the default %TEMP% directory has insufficient space, increase the
available space or change its location.
Ensure that all the AR System objects, such as forms and workflows, have been released before
you apply patch.
After you apply the patch to the BMC Remedy Mid Tier, flush the mid-tier cache and delete the
content from the following folders:
<Midtier>\cache\
<Midtier>\cachetemp\
<Tomcat>\Work\Catalina\localhost\arsys\
<Tomcat>\temp\
<Midtier>\PluginsCache\
For a list of AR System files that are updated by Patch 2, download and unzip
ARSystem81Patch2FileList.zip. This zip file contains lists for all supported platforms.

7.4.1 Reviewing the patches currently installed on your computer

To review all the current patches installed on your computer, perform the following steps:
1. Open the Maintenance Tool (installed under C:\Program Files\BMC Software\ARSystem\arsystem).

2. Click Browse to Log.
3. Scroll through the Navigation pane to find the <Product>InstalledConfiguration.xml file for the product
patch that you installed. For example:
C:\Program Files\BMC Software\ARSystem\ARSystemInstalledConfiguration.xml
C:\Program Files\BMC
Software\BMCServiceRequestManagement\BMCServiceRequestManagementInstalledConfiguration.xml
4. Double-click the file to open it in the Maintenance Tool.
5. Click the Product Feature Map tab.
6. Under Updates, review the patches installed on your computer (for example, Patch 002).
(Click the image to expand it.)
7.4.2 Installing the patch and reviewing the result

The patch installer determines which modules are already installed on the target computer and then applies the
patches only to those modules. For example, if you run the AR System patch installer on a computer that is
running only the AR System server, then only the fixes relevant to the AR System server are applied.
Note
If you install the patch using the SSI installer, ensure to add the following in the
ARSystemInstalledConfiguration.xml before you begin the patch installation.
<productFeature backupOnUpgrade="false" id="featureDeveloperStudio" independentOfChildren="true"

parent="featureARSystemClients"
rebootRequiredOnInstall="false" rebootRequiredOnUninstall="false" rebootRequiredOnUpgrade="false"

requiredDiskSpaceMode="default"
requiredRAMMode="default" state="INSTALLED" visible="true">
<version majorVersion="1" minorVersion="00" releaseVersion="8"/>
<requiredDiskSpaceMap>
<requiredDiskSpace id="default" size="123 MB"/>
<requiredDiskSpace id="backup" size="0 bytes"/>
<requiredDiskSpace id="temporary" size="0 bytes"/>
</requiredDiskSpaceMap>
<requiredRAMMap>
<requiredRAM id="default" size="512 MB"/>
</requiredRAMMap>
</productFeature>
To install the patch and review the result
Note
You must disable the escalations before you install the patch.The instructions to disable the escalations
are provided in Disabling escalations.
If you are installing the patch on a server group, you must disable escalations only while installing the
patch on the administrator server.
1. Download the patch installer from the BMC Electronic Product Download site, or navigate to the
installation directory on the CD.
2. Unzip the suite installer.
3. Navigate to the Disk 1 folder.
4. Start the installer:
For Windows, run setup.cmd.
For UNIX, log on as root and run setup.sh.
5. In the lower right corner of the Welcome panel, click Next.
6. Review the license agreement, click I agree to the terms of license agreement, and then click Next.
7. On the Patch contents panel, review what is included in the patch, and then click Next.
8. On the BMC Remedy AR System User Inputs panel, review the AR System server values, and then click Next.
Note
On AIX operating systems, you must manually provide the value for the AR System Server TCP
Port.

9. On the Installation Preview panel, review the list of patch fixes that you are installing, and then click Install.
10. When the patch installation is finished and the Installation Summary panel appears, click View Log to
review the SEVERE error messages or warnings in the product installer log.
See whether errors are due to network, host, or other environment-related issues.
The installation log is located in the %TEMP% folder of your computer. For example:
C:\Users\Administrator\AppData\Local\Temp\arsystem_install_log.txt
C:\Users\Administrator\AppData\Local\Temp\bmcservicerequestmanagement_install_log.txt
11. Close the log when you finish.
12. Click Done to exit the patch installer.
13. Use the Maintenance Tool to review the patch information.
Note
Ensure that you re-enable escalations after you finish installing the patch.
To install the patch on a server group

To install the patch on a server group, perform the following steps:
1. Shut down all of the non-administrator servers in the server group.

2. If you have configured a load balancer, disable the administrator server on the load balancer.
3. Remove the administrative server from the server group.
4. Disable escalations, by following the instructions that are provided in Disabling escalations.
5. Install the patch on the administrator server by following the instructions that are provided in the Installing
the patch and reviewing the results.
6. Enable escalations.
7. Add the administrator server back to the server group.
8. Restart the administrator server.
9. If you have configured the load balancer, enable the administrator server on the load balancer.
10. On each of the non-administrator servers, perform the following steps:
a. Start the BMC Remedy AR System service.
b.
10.
b. Install the patch by following the instructions that are provided in Installing the patch and reviewing
the results.
c. Enable the server on the load balancer.
7.4.3 Disabling escalations

To disable escalations, perform the following steps:
1. Open the BMC Remedy AR System Administration Console.

2. Open Server Information.
3. Click the Configuration tab.
4. Select Disable Escalations.
5. Click OK.
7.4.4 Applying the Data Management Hotfix

If you use the Data Management feature of BMC Remedy IT Service Management, you must apply the BMC
Atrium Core hotfix that is shipped with the BMC Remedy AR System 8.1 Patch 002 installer. For more information
on applying the hotfix, see BMC Remedy IT Service Management Suite patch documentation.
7.4.5 Performing a silent installation

1. Use the Maintenance Tool to create an encrypted password.
2. Create a text file called Options.txt and add the following options that correspond to user inputs.
-J BMC_AR_USER=<AR System Admin User>

-J BMC_AR_PASSWORD=<AR System User Password>
-J BMC_AR_PORT=<AR System TCP Port>
-J BMC_AR_SERVER_NAME=<Server Alias>
For example:

-J BMC_AR_USER=Demo
-J BMC_AR_PASSWORD=DES\:51208e44b3bc2f3808839e457d4e2050
-J BMC_AR_PORT=0
-J BMC_AR_SERVER_NAME=vw-sjc-aus-idd04
3. Open a command window and navigate to the Disk 1 folder.

4. Run the installer with the -i silent option:
For Windows:
setup.cmd -i silent -DOPTIONS_FILE= <pathToFile>\Options.txt
For UNIX:
setup.sh -i silent -DOPTIONS_FILE= <pathToFile>/Options.txt
You must use an absolute path to the Options.txt file.

7.4.6 Reconciling your customizations

For information on reconciling your customization, see Comparing objects after you upgraded with overlays
already present. Make sure to perform the mandatory step of reconciling after an upgrade with overlays already
present.
If you use the object modification log, see Object modification log for information about obtaining a list of
modified objects after you apply the hotfixes. Alternatively, if there are objects modified by the patch, a Bill of
Materials file (BillofMaterials.txt) will be available to identify the affected objects.
7.5 Patch 1 for version 8.1.00: 8.1.00.001

This topic contains information about fixes and updates in this patch, and provides instructions for downloading
and installing the patch.
Important
If you upgrade from BMC Remedy Action Request (AR) System version 8.0 and its subsequent patches to
version 8.1, you must install BMC Remedy Action Request (AR) System 8.1.00 Patch 2. The patch installer
does not allow you to update to BMC Remedy AR System 8.1.00 Patch 1. For more information on BMC
Remedy AR System 8.1.00 Patch 2, see Patch 2 for version 8.1.00.
Known and Corrected issues

Notes
You can install this patch on 64-bit computers, not 32-bit.

You must have installed BMC Remedy Action Request (AR) System 8.1.00 before running patch
installer.
When the AR System patch is being applied, the patch installer restarts the AR System server as
part of the installation process.
The 8.1 patch installer does not use the Install Anywhere Framework and is not affected by the
IATEMPDIR system variable. If the default %TEMP% directory has insufficient space, increase the
available space or change its location.
Ensure that all AR System objects have been released before you apply the patch.
After you apply the patch to the BMC Remedy Mid Tier, flush the mid-tier cache and delete the
content from the following folders:
<Midtier>\cache\
<Midtier>\cachetemp\
<Tomcat>\Work\Catalina\localhost\arsys\
<Tomcat>\temp\
<Midtier>\PluginsCache\
For a list of AR System files that are updated by Patch 1, download and unzip
ARSystem81Patch1FileList.zip. This zip file contains lists for all supported platforms.
7.5.1 Reviewing the patches currently installed on your computer

To review all the current patches installed on your computer, perform the following steps:
1. Open the Maintenance Tool (installed under C:\Program Files\BMC Software\ARSystem\arsystem).

2. Click Browse to Log.
3. Scroll through the Navigation pane to find the <Product>InstalledConfiguration.xml file for the product
patch that you installed. For example:
C:\Program Files\BMC Software\ARSystem\ARSystemInstalledConfiguration.xml
C:\Program Files\BMC
Software\BMCServiceRequestManagement\BMCServiceRequestManagementInstalledConfiguration.xml
4. Double-click the file to open it in the Maintenance Tool.
5. Click the Product Feature Map tab.
6. Under Updates, review the patches installed on your computer (for example, Patch 001).

7.5.2 Installing the patch and reviewing the results

The patch installer determines which modules are already installed on the target computer and then applies the
patches only to those modules. For example, if you run the AR System patch installer on a computer that is
running only the AR System server, then only the fixes relevant to the AR System server are applied.
Note
If you install the patch using the SSI installer, ensure to add the following in the
ARSystemInstalledConfiguration.xml before you begin the patch installation.
<productFeature backupOnUpgrade="false" id="featureDeveloperStudio" independentOfChildren="true"

parent="featureARSystemClients"
rebootRequiredOnInstall="false" rebootRequiredOnUninstall="false" rebootRequiredOnUpgrade="false"
requiredDiskSpaceMode="default"
requiredRAMMode="default" state="INSTALLED" visible="true">
<version majorVersion="1" minorVersion="00" releaseVersion="8"/>
<requiredDiskSpaceMap>

<requiredDiskSpace id="default" size="123 MB"/>

<requiredDiskSpace id="backup" size="0 bytes"/>
<requiredDiskSpace id="temporary" size="0 bytes"/>
</requiredDiskSpaceMap>
<requiredRAMMap>
<requiredRAM id="default" size="512 MB"/>
</requiredRAMMap>
</productFeature>
To install the patch and review the results
Note
You must disable the escalations before you install the patch.The instructions to disable the escalations
are provided in Disabling escalations.
If you are installing the patch on a server group, you must disable escalations only while installing the
patch on the administrator server.
1. Download the patch installer from the BMC Electronic Product Download site, or navigate to the
installation directory on the CD.
2. Unzip the suite installer.
4. Start the installer:
For UNIX, log on as root and run setup.sh.
7. On the Patch contents panel, review what is included in the patch, and then click Next.
8. On the BMC Remedy AR System User Inputs panel, review the AR System server values, and then click Next.
Note
On AIX operating systems, you must manually provide the value for the AR System Server TCP
Port.

9. On the Installation Preview panel, review the list of patch fixes that you are installing, and then click Install.
10. When the patch installation is finished and the Installation Summary panel appears, click View Log to
review the SEVERE error messages or warnings in the product installer log.
See whether errors are due to network, host, or other environment-related issues.
The installation log is located in the %TEMP% folder of your computer. For example:
C:\Users\Administrator\AppData\Local\Temp\bmcservicerequestmanagement_install_log.txt
12. Click Done to exit the patch installer.
Note
Ensure that you re-enable escalations after you finish installing the patch.
To install the patch on a server group

To install the patch on a server group, perform the following steps:
1. Shut down all of the non-administrator servers in the server group.

2. Disable the administrator server on the load balancer.
3. Remove the administrative server from the server group.
On the administrator server, perform the steps that are described in Removing a server from a server group
.
4. Disable escalations, by following the instructions that are provided in Disabling escalations.
5. Install the patch on the administrator server by following the instructions that are provided in the Installing
the patch and reviewing the results.
6. Enable escalations.
7. Add the administrator server back to the server group.
8. Restart the administrator server and enable it on the load balancer.
9. On each of the non-administrator servers, perform the following steps:
a.
9.
a. Start the BMC Remedy AR System service.
b. Install the patch by following the instructions that are provided in Installing the patch and reviewing
the results.
c. Enable the server on the load balancer.
7.5.3 Removing a server from a server group

To remove a server from a server group, perform the following steps:

4. Deselect the Server Group Member option that appears at the bottom of the window.
5. Click Apply, and then OK.
6. Restart the server.
7.5.4 Disabling escalations

To disable escalations, perform the following steps:

4. Select Disable Escalations.
5. Click OK.
7.5.5 Performing a silent installation

1. Use the Maintenance Tool to create an encrypted password.
2. Create a text file called Options.txt and add the following options that correspond to user inputs.
-J BMC_AR_USER=<AR System Admin User>

-J BMC_AR_PASSWORD=<AR System User Password>

2.
-J BMC_AR_PORT=<AR System TCP Port>

-J BMC_AR_SERVER_NAME=<Server Alias>
For example:
-J BMC_AR_USER=Demo
-J BMC_AR_PASSWORD=DES\:51208e44b3bc2f3808839e457d4e2050
-J BMC_AR_PORT=0
-J BMC_AR_SERVER_NAME=vw-sjc-aus-idd04
3. Open a command window and navigate to the Disk 1 folder.

For Windows:
setup.cmd -i silent -DOPTIONS_FILE= <pathToFile>\Options.txt
For UNIX:
setup.sh -i silent -DOPTIONS_FILE= <pathToFile>/Options.txt

7.5.6 Reconciling your customizations

For information on reconciling your customization, see Comparing objects after you upgraded with overlays
already present. Make sure to perform the mandatory step of reconciling after an upgrade with overlays already
present.
If you use the object modification log, see Object modification log for information about obtaining a list of
modified objects after you apply the hotfixes. Alternatively, if there are objects modified by the patch, a Bill of
Materials file (BillofMaterials.txt) will be available to identify the affected objects.
7.6 8.1.00 enhancements

This section provides information about the following enhancements in this release:
See the following What's New video for more information about enhancements in version 8.1.00:
Watch video on YouTube at http://www.youtube.com/watch?v=d5Ksm0Ze0uk

7.6.1 BMC Remedy AR System enhancements in version 8.1.00

This section helps you to understand the new features and changes in BMC Remedy Action Request System (BMC
Remedy AR System) in this release:
Overlays enhancements in version 8.1.00

This topic provides information about the following overlays enhancements in this release.
AR System server overlays enhancements

AR System objects now use granular overlays. Using granular overlays, you can now add to, overwrite, or inherit
different parts of an object in an overlay. You can modify some characteristics of an object while inheriting other
parts. You can also add to aspects of an object while inheriting properties from the origin object. If parts of an
object are inherited or added to, those updates to the origin object are made to the overlay. Using granular
overlays minimizes the need to reconcile overlays after applying upgrades or patches.
Granular overlays can apply inheritance to an entire overlay, including aspects of the object that can or cannot be
added to, providing a transparent overlay that inherits all characteristics from an overlaid object.
For more information, see Granular overlays.
BMC Remedy Developer Studio overlays enhancements

In BMC Remedy Developer Studio, you can now define form properties in the Definitions tab and field properties
in the Properties tab.
Defining form properties in the Definitions tab

In the Base Development mode, you can now define form properties in the Definitions tab in the form editor. In
the Best Practice Customization mode, you can now define granular properties for an object in the Permissions,
Indexes, and Other Definitions panes in the Definitions tab. Dialog boxes on several tabs indicate whether the
object is an overlay.
All fields in a form are now visible in the Outline tab when you select the Definitions tab. Selecting a field in the
Outline tab displays the properties of the field in the Properties tab.
For more information, see Setting form properties.
Defining field properties in the Properties tab

In the Best Practice Customization mode, you can now define the Overlay Type for permissions and other
granular overlay field property settings in lists at the top of the Properties tab. You can also set permissions for a
custom field on the Properties tab.
For more information, see Properties tab for fields in Best Practice Customization Mode .

Installation enhancements in version 8.1.00

The following topics provide information about the enhancements in the installation program.
Simplified BMC Remedy AR System version 8.1.00 installation program

The BMC Remedy Action Request (AR) System version 8.1.00 installation program has been simplified. When you
run the suite installation program, you are asked to select the type of installation that you want to perform.
AR System Server — Installs the BMC Remedy AR System server, Approval Server, Assignment Engine, Email
Engine, and Flashboards. Also installs the AREA LDAP, ARDBC, Web Services, SNMP, and FTS plugins.
AR System Mid-Tier — Installs the BMC Remedy Mid Tier (and Crystal Web Application if BOXI installation is
available).
AR System Clients — (Microsoft Windows only) Installs BMC Remedy Developer Studio (and the
Localization Toolkit), BMC Remedy Data Import, and BMC Atrium Integrator Spoon (This option is not
available for Linux or UNIX.)
For more information, see Performing a new installation.
Changes to the upgrade scenarios

If you select the Upgrade option, the components that were not installed in the previous version, are installed
after BMC Remedy AR System upgrade. For example, while upgrading from BMC Remedy AR System version
7.6.04 to version 8.1.00, the installer installs Approval Server, Assignment Engine, Email Engine, and Flashboards.
Also, the components that were not installed in the earlier version like AREA LDAP, ARDBC, Web Services, SNMP,
and FTS plugins are also installed.
For more information about upgrading, see Upgrading Tips.
Separate configuration and installation of the Email Engine, FTS, and the SNMP Agent
The number of installation screens is reduced by strictly separating installation from the Email Engine, full-text
search (FTS), and the SNMP Agent configuration. For this, the following new forms are introduced for FTS and the
SNMP Agent:
AR System Administration FTS Configuration form (see FTS Configuration form in the AR System
Administration Console)
AR System Administration SNMP Configuration form (see SNMP Configuration form in the AR System
Administration Console)
Note
There are no changes to the AR System Email Mailbox Configuration form (see AR System Email
Mailbox Configuration form).

You can access these new forms through the BMC Remedy AR System Administration console interface. Under
the System category, click FTS Configuration to access the AR System Administration FTS Configuration form and
SNMP configuration to access the AR System Administration SNMP Configuration form. For more information
about the BMC Remedy AR System Administration console interface, see Navigating the BMC Remedy AR System
Administration console interface.
Note
Make sure that you configure Email Engine, FTS, and SNMP Agent after installation. If you select the
Upgrade option, then you must configure FTS.
Changes in the installation program related to server groups

When you install a server that is a part of the server group, the Server Group option is not displayed because the
installation program automatically detects whether this server is a part of the server group, and the installation
continues.
For more information, see Installing a server group and Installing the next AR System server in the server group.
Changes in the installation program related to port numbers

The installation program automatically selects the port numbers during installation. For the range of the default
port numbers assigned to different components, see Understanding port numbers.
BMC Remedy AR System server enhancements in version 8.1.00

This topic provides information about the following BMC Remedy AR System server enhancements.
Support for Internet Protocol version 6

BMC Remedy Action Request (AR) 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.
For more information, see Support for IPv6.
BMC Remedy Mid Tier enhancements in version 8.1.00

This topic provides information about BMC Remedy Mid Tier enhancements and new features.
Scheduling or publishing reports with a new or modified search qualification

When you schedule a report, you can now modify the embedded report qualification by setting the Qualification
to Use field in the AR System Report Schedule UI dialog box.
For more information, see Publishing reports.

Support for BusinessObjects Enterprise XI 4.0

The BMC Remedy Mid Tier now supports BusinessObjects Enterprise XI (BOXI) versions 3.1 and 4.0.
For more information, see Optional components that you can install.
RTF enhancements in version 8.1.00

This topic summarizes the rich text field (RTF) enhancements in this release.
Bookmark functionality in RTF fields

Using RTF fields, you can create bookmarks to link a specific text in an RTF field or link to a different RTF field on
the same form. You can also link to external websites or create a workflow to generate a dynamic URL that is then
applied to an RTF field. For more information, see the following topics:
Creating or updating bookmarks

Inserting and removing URL links in the RTF fields
Generating a URL in an RTF field using a workflow
RTF field support in BMC Remedy Email Engine

BMC Remedy Email Engine now supports applying rich text formatting (RTF) in email messages. Also, you can
now see attached images inline with the text. For more information, see Sending outgoing email in HTML.
Other enhancements in version 8.1.00

This topic provides information about the following enhancements and new features in this release:
Db-Case-Insensitive option in the ar.conf (ar.cfg) file

The Db-Case-Insensitive option in the ar.conf (ar.cfg) file was improved. For more information, see ar.cfg or
ar.conf options C-D.
Enhancements to workflow logging

Workflow logging is now enhanced to display easy-to-understand and user-friendly log statements in the log
window. Log information now includes:
Start and end statements for active links and events

Indentation of log statements
Meaningful descriptions for all active link functions
The log window also contains a Clear button to clear the logs. For more information, see Log information for
workflows.The page Enhancements in version 8.1 does not exist.
For more information, see Installing SSO with the AR System server and mid tier.

New parameters to restrict number of entries in a report

New parameters are added to the config.properties file to limit the number of entries in the report. For more
information, see Modifying the config.properties file for limiting report entries.
New or updated forms in version 8.1.00

The following forms are new or have been updated in BMC Remedy AR System. If you have customized any of
these forms, BMC recommends that you perform a backup before installing version 8.1.00. For the list of
system-defined forms that are loaded during BMC Remedy AR System installation, see BMC Remedy AR System
installed forms.
Updated installation forms
File name Form name Changes
ARJobSchedular.def
AR System Job Item New fields added
AR System Publish Report Updated filter
AR System Job New filter added
AR System Pending Job Queue Updated permissions for forms
AR System Job Error Queue Updated object properties
AR System Report Job Processor
AR System Job Type Mapping
ARSkins.def AR System Skins Updated object properties
ARSystemReporting.def AR System Report Console

Updated active link
Deleted active links
ARUdm.def
UDM:Config Permission added
UDM:Execution New fields added
UDM:ExecutionInstance Updated active links
UDM:ExecutionStatus New active links added
UDM:PermissionInfo Change in the display-instance property of the
UDM:RepositoryObject fields
UDM:ScheduleProcessor
UDM:StepStatus
UDM:Variable
UDM:RAppPassword
UDM:JobLog
UDM:LoggingChannelLog
UDM:StepPerformanceLog
UDM:JobEntryLog
UDM:StepLog
UDM:TransformationLog
Group.def Group
Updated active links
Updated Character Menu

RSSFeed.def
AR System Feed Cache New forms introduced in this release
AR System Feed Definition New fields added
Change in the display-instance property of the
fields
New active links added
Updated Character Menus
Serveradmin.def
AR System Administration (application) Added new form to the application
AR System Administration: Console New fields added
AR System Administration: License Review Updated permissions for the form
AR System Administration: Server Change in the display-instance property of the
Information fields
Updated permissions for the field
New active links added
Updated containers
SNMPPluginConfiguration.def AR System Administration :SNMP Config New .def file
Updated System forms
ARRegistry.def AR System Web Services Registry New filter added
SHARE_Application_Config_Registration.def SHARE:Application_Configuration_Registration New .def added
SHARE_Application_Interface.def SHARE:Application_Interface New field added
Documentation enhancements in version 8.1.00

This topic lists enhancements to the BMC Remedy Action Request System documentation in this release.
Centralized location for describing changes to the config.properties file

The BMC Remedy Action Request System documentation now contains a topic that describes changes to the
config.properties file for the components. For details about modifying the config.properties file to manually
change the default behavior of the mid tier, see Modifying the config.properties file.
Other documentation updates

The BMC Remedy Action Request System documentation is updated to describe how to enable logs for Java
plug-ins and troubleshoot plug-in related issues, and to provide information about cookies generated by the mid
tier and performance benchmark and tuning.

7.6.2 BMC Remedy Migrator enhancements in version 8.1.00

This topic provides information about the following enhancements and new features in BMC Remedy Migrator:
Ability to migrate granular overlay objects from one server to another

BMC Remedy Migrator and the Migrator CLI support the migration of granular overlay objects from one server to
another. You can migrate a granular overlay object from Server to a Migrator File, and from a Migrator File to
Server. You can also load granular overlay objects from a definition file and XML file.
For more information, see Migrating overlays when corresponding overlaid objects do not exist at destination .
7.7 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.
7.7.1 BMC Remedy AR System online documentation

Document Online section
Release Notes What's new

BMC Remedy AR System enhancements in version 8.1.00
Known and corrected issues

BMC Remedy Action Request System known and corrected issues in version 8.1.00
C API Reference Developing an API program
Concepts Guide Key concepts
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
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
Upgrading
Integration Guide Integrating
Developing an application
Making applications licensable for integration system vendors
Publishing the BMC Remedy AR System functionality as a web service
Introduction to Application Development Developing an application

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 Developing an application

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
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
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
BMC Remedy Mid Tier Guide Configuring after installing

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 BMC Remedy Flashboards
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 This document is obsolete.
Developer Studio Quick Reference This document is obsolete.
7.7.2 BMC Remedy Encryption online documentation

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 What's new

Notes BMC Remedy Encryption Security enhancement in version 8.1

BMC Remedy Encryption Security known and corrected issues in version 8.1.00

7.7.3 BMC Remedy Migrator online documentation

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 What's new

BMC Remedy Migrator enhancements in version 8.1.00

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

documentation
Preconfigured Stack Installation Notes Installing the BMC Remedy ITSM Suite Preconfigured Stack
Preconfigured Stack Installation Quick Reference This document is obsolete.
7.7.5 White papers online

BMC Remedy IT Service Management Suite Service Pack 2 Upgrade Planning to upgrade BMC Remedy AR System
Procedures and Guidelines Upgrading
Performance Benchmarking Tutorial Using SilkPerformer with BMC Using SilkPerformer to measure and optimize application performance
Remedy Mid Tier
KITE Scripting for BMC Remedy AR System Mid Tier Measuring mid tier performance with KITE scripting
BMC Remedy Action Request System Enterprise Quick Reference Planning BMC Remedy AR System installation in an enterprise environment
White Paper
Remedy Application Performance Benchmarking Best Practices Performance benchmarking BMC Remedy applications
BMC Remedy AR System Server 7.6 Performance Tuning for Business Performance tuning for BSM
Service Management
BMC Remedy IT Service Management Suite Delta Data Migration Migrating delta data after an upgrade
Server Setup and Implementation
This document is obsolete.

BMC Remedy Action Request System Behavioral Differences Between

BMC Remedy User and Browser Clients
BMC Remedy Action Request System Designing BMC Remedy Making your application accessible (Section 508 compatibility)
applications for Section 508 compliance
BMC Remedy Action Request System Web Application Security Security assessments
Assessment and Vulnerability Mitigation Tests
BMC Remedy IT Service Management Suite Installing and Configuring Installing a server group
Server Groups
Integrating BMC Remedy Action Request System with Single Sign-On Single sign-on authentication systems integration
(SSO) Authentication Systems and Other Client-Side Login Intercept
Technologies
BMC Remedy Action Request System Using the Certificate Database Enabling LDAP plug-ins to establish SSL connections with LDAP servers
Tool
Using a Hardware Load Balancer with BMC Remedy Action Request Configuring a hardware load balancer with BMC Remedy AR System
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

8 FAQ
This topic presents answers to frequently asked questions.
How do I achieve mid tier scaling?
You can use the JSP servlets to make the mid tier scalable. For more information, see BMC Remedy Mid Tier
scalability.
What are the recommendations for mid tier caching?
For mid tier caching recommendations, see About Mid Tier caching.
How do I set up authentication using LDAP?
For information about setting up authentication using LDAP, see Server authentication.
How do I find content in the online documentation that was previously provided in PDF format?
For information about locating content in the online documentation, see Locating white papers, guides, and
technical bulletins.

9 Key concepts
Use this section to get high-level conceptual knowledge that helps you to use the BMC Remedy AR System
applications.
Goal Instructions
Understand the benefits of Business Service Management (BSM) and how you can realize BSM in your organization using Business Service
BMC Software products and services Management
Learn how you can use BMC Remedy AR System to address your business needs Business value
Understand the roles and responsibilities of BMC Remedy AR System users User goals and
features
Get an overview of BMC Remedy AR System licenses and to know the differences between licensing in BMC Remedy AR License overview
System 7.1.00 and later releases and licensing in pre-7.1.00 releases
Learn about access control feature to protect your data from unauthorized access Access control
overview
Learn about BMC Remedy AR System application, its types and components and how to localize your application Application
development
overview
Understand the architecture of BMC Remedy AR System and its related components Architecture
9.1 Business Service Management

Business Service Management (BSM) provides a comprehensive and unified platform that simultaneously
optimizes IT costs, demonstrates transparency, increases business value, controls risk, and assures quality of
service. Delivering an "ERP for IT," BSM simplifies, standardizes, and automates IT processes so that you can

manage business services efficiently across their lifecycle — across distributed, mainframe, virtual, and
cloud-based resources. With BSM, your organization has the trusted information it needs, can prioritize work
based on business critical services, and can orchestrate workflow across your core IT management functions.
BSM has been architected so that you can adopt it incrementally and in a low-risk fashion based on the top
initiatives you are already most likely pursuing, such as Cloud Computing, Data Center Automation, and IT Service
Management.
In this site, we use the following terms to explain how you can realize BSM in your organization using BMC
Software products and services:
BSM Initiatives describe the most common strategic initiatives that organizations are undertaking to
address their IT management challenges.
For each BSM Initiative, a set of value paths have been defined that capture the most common ways to get
started on an initiative with the highest impact and shortest time to value based on BMC customer
experiences.
A value path prescribes the steps, or required capabilities, that an organization will need to realize value
around a key project within each initiative.
Required capabilities map to BMC products or service offerings to address the required capabilities for
each value path.
9.2 Business value

Use the following topics to understand how you can use BMC Remedy Action Request System (BMC Remedy AR
System) to address your business needs.
9.2.1 Building a foundation for ITIL service support

BMC Remedy AR System provides the foundation for BMC Remedy OnDemand and the BMC Remedy ITSM Suite.
BMC Remedy OnDemand and BMC Remedy IT Service Management (BMC Remedy ITSM) address the following
business goals:
Effective collaboration and reporting

IT transparency (visibility of costs and business-value contributions)
Improvements from tool and process standardization
Flexible and agile services
Fast tracking of your ITIL initiatives
Support for multi-tenancy and multi-lingual implementations
Single, central, shared data model
9.2.2 How BMC provides value

BMC provides a one-stop solution that is single suite of products that supports all your ITIL service support needs
— from architecture to integration and implementation to support.

Provided capabilities Value path
Service Asset Lifecycle

IT asset management natively integrated with a full suite of service support applications
Service Desk Optimization

Service desk consolidation that unifies all service desks onto a single, integrated platform
Reduced calls to the service desk by fully automating service requests and integrating with the BMC
Remedy Service Desk workflow engine
Best practice Incident Management processes to manage the entire incident resolution process in order
to restore service as quickly as possible
Best practice Problem Management processes to remove defects from the IT infrastructure, eliminate
recurring incidents, and stabilize the environment
Service Catalog and Request

Tightly integrated Knowledge Base that provides ready access to common solutions, known errors, and Management
workarounds to expedite incident resolution
Self-service for searching FAQs, known solutions, and workarounds to common issues that encourages
user self-sufficiency and reduces call volumes
A service catalog that enables you to view the details and relationships of IT and business services and
add new services to your service model
Comprehensive Change and

Streamlined change and release process and approvals Release Management
9.2.3 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.
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.

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 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.
9.2.4 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.
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.
9.2.5 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 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.
9.2.6 How BMC Remedy Email Engine enables email-driven business

processes
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.
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.
9.2.7 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 may require the purchase of separate license. 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.
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/ ).
9.2.8 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
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.
9.2.9 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.

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.

9.2.10 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.
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.
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.
9.3 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.

9.3.1 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
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
Implementing security policy, standards, guidelines and procedures to ensure ongoing maintenance of
security
9.4 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.
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
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.
9.4.1 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 Every license required a key. Before Only AR System server licenses need keys. Customers can add all nonserver licenses without
keys you could add any license to an AR the need for a key.
System server, you had to contact
BMC to get a key.
Server All AR System server and user floating No license qualifiers are required.
groups licenses used by server groups needed
a license qualifier.
All licenses used by a server group Each server must have its own AR Server license and license key, but it shares all other
had to be applied to every server in licenses with the other servers in the group.
the group.
Dedicated Dedicated server licenses were Dedicated server licenses are not used. When you upgrade to 7.1.00 or later from a
server provided for common components pre-7.1.00 release, dedicated server licenses are upgraded to full AR System server licenses at
licenses such as the BMC Atrium Definitive no cost. In addition, licenses for any applications associated with the dedicated server are
Software Library or CMDB. automatically added to your system.
9.4.2 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 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.
9.4.3 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.
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.
9.5 Access control overview

This section describes user and group access, role-based access, multitiered access, and 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:
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 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.
9.5.1 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
Type Description Predefined groups Custom groups

of
access
control
group
Explicit A group to which you must assign users. Any regular and computed groups that you create.Regular
Administrator groups are groups to which you assign a specific list of users.
Sub Computed groups are groups to which users are assigned
Administrator based on their memberships in groups included in an
Customize 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 Any dynamic groups that you create.Dynamic groups use the
implicitly) belongs by virtue of the contents of Public contents of special fields to determine group membership.
certain fields in a request. You cannot assign Submitter
users to implicit groups. All users are members of Assignee
Public. You use the other types of implicit groups Assignee
to control access to requests (row-level database Group
access).
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
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

9.5.2 Role-based access overview

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 a variety of servers. You assign users to groups and 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.
Note
For simplification, user access is usually described in terms of group permissions. In deployable
applications, which use role permissions, user access is ultimately determined by which groups are
mapped to which roles.
For more information, see Creating and mapping roles.
9.5.3 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
Access control levels

The access control model comprises the following levels:
Access Description
level
BMC 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
Remedy a valid user name, a password, and, as an option, an authentication string. BMC Remedy AR System servers check the user name,
AR password, and authentication string each time a client requests a transaction, such as when opening a form or changing a field. If your
System 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
server 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 In addition to controlling access to form and field data, you can control access to active links, which trigger a variety of workflow actions.
link For example, you might allow support staff to trigger several active links appropriate to their work but not allow other users to trigger

Access Description
level
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 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
link 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 guide does not appear.
Request 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.
9.5.4 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.
9.6 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 was 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.
9.6.1 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 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.
9.6.2 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


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


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


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 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

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

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
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 Changes the appearance of fields. For example, a Change Field action can perform one or more of these +
Field 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.

Action Description Active Filter Escalation

link
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.
Close Closes the current window. +

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 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 Opens a window of any type in the client. The action can open a New window and load some default data. +
Window 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 is, it "pushes" the + + +
Fields 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 Runs a separate process (program) on the server for filters and escalations or on the Windows client or + + +
Process 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 Sets fields on a form to specified values. For example, a filter can automatically set the Status field to + + +
Fields 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.
Execution options for active links and filters
Execution option Description Active Filter

link
Button/Menu Field 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 pane. +
Hover on Field Executes when a user hovers the mouse pointer over a field, field data, or a field label. To display tooltips, use +
Hover on Data a Hover execution option to trigger a Message action.
Hover on Label
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
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

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:

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.
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:
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
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:

Field type Description
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 Augments BMC Remedy AR System with HTML-based content such as web pages, flashboards, and other graphics that can interact
visualization with the field's parent form through workflow
Application 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
list 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 Enables users to navigate to the correct screen in an application quickly and easily
and vertical
navigation
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.
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 Description
type
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 Retrieves lists of fields and forms from an AR System server. These menus are useful for creating special configuration interfaces. They
dictionary are generally not used to help users perform their work.
9.6.3 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
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.
9.6.4 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
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
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

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.

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

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.

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

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

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 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.
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.
9.7 Architecture
Use this section to understand the architecture of BMC Remedy AR System and its related components.

9.7.1 BMC Remedy AR System 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 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)
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.
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.
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.
BMC Remedy AR System client server architecture

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 BMC Remedy AR System.
BMC Remedy AR System architecture

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 Checking system requirements and supported configurations)
BMC Remedy AR System multitier architecture

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

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 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

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.

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
A browser Administrator tasks:
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
BMC Remedy Developer Studio Developer tasks:
Create and update application, forms, and workflow.
BMC Remedy Mid Tier Configuration Administrator tasks:

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 Administrator tasks:
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.
Import/export command line interface Administrator tasks:

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

Client Tasks
Automate tasks.
BMC Remedy Data Import 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.
9.7.2 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

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 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

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

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

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.
BMC Remedy AR System includes a specialized private queue marked Debug for use with the BMC Remedy AR
System workflow debugger. To configure and use a debug queue with the BMC Remedy AR System workflow
debugger, see Configuring the server for debugging workflow.
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

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.
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.
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
For the most accurate information about supported platforms and software, see Checking system
requirements and supported configurations.
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.
9.7.3 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. 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.
9.7.4 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

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.
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 Checking system requirements and supported configurations. 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.
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 enables a browser to become a fully functional BMC Remedy AR System client.
The main components of the mid tier infrastructure are:
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 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 Checking system
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.

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.
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.
For information about configuring this feature within a BMC Remedy IT Service Management Suite hub and spoke
system, see Registering hub and spoke servers.
9.7.5 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
Configuring BMC Remedy Migrator
9.7.6 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

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

2.
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.
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.
8. The Set Fields filter action is finished.
Consuming an external web service with BMC Remedy AR System
9.7.7 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
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:
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

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.
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.
9.7.8 BMC Remedy Email Engine architecture

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

Module Description and purpose
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.
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.

10 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 BSM environment
certified environments in which you should install BMC Remedy Action Request System. recommendations
Learn about the deployment architecture and performance benchmarks and tuning for BMC Remedy AR Deployment architecture
System.
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 Language information
languages.
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

10.1 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 Checking system
requirements and supported configurations 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:
10.1.1 Features you can install

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

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.
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.
BMC Remedy Email Engine

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.
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.
BMC Remedy Approval Server

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

BMC Remedy Data Import allows you to import data from a source file into a BMC Remedy AR System form.
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.
10.1.2 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.
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.
10.2 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.
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.
10.2.1 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.
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.
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
10.2.2 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?
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 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 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
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.
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.
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 a separate computer in a location where both AR servers have fast network access.
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.
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 AR Server 2, so that is the only server with read-write access to the FTS collection
directory. 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 a separate computer in a location where all AR System servers
have fast network access.

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 should be the same as the short DNS name of the load balancer (which is a name that
resolves to the load balancer IP address). 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.
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:
IP-Name: 92.163.169.2
Other Info Needed:

Server-Name (resolves to the load balancer name): RemedyServerGroup
Domain-Name: test.svgroup.com

10.2.3 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 Mid tier Email Engine Assignment Approval Server BMC Atrium CMDB
Server Engine
Installing Upgrading tips Before installing Preparing to Preparing the AR System

the Mid Tier install the Email server to install BMC Atrium
Engine Core and other BMC
applications
Security Security Security Securing Configuring the Security Security considerations for
considerations considerations for incoming and Assignment considerations BMC Remedy AR System
for BMC BMC Remedy AR outgoing email Engine for BMC
Remedy AR System Remedy AR
System System
Access control Access control
User Specifying
authentication internal and
external
authentication
Scalability and high AR System

availability server
multithread
architecture
Load Balancing Using a load BMC Remedy Mid Load balancing

balancer with Tier with Email
server groups recommendations Engine
Distributed Distributed
deployment operations
introduction
Where to integrate Integration Integration Integrating the Integrating Integrating with CMDB
BMC Remedy AR technologies capabilities Assignment Approval Server
System Engine into an with an
application application
Web servers and Preparing your

JSP/servlet engines web server
Proxy servers Proxy server and

load balancer
settings

Single sign-on Single sign-on

(SSO) authentication
systems
integration
Log files and Collecting BMC Remedy Mid BMC Remedy Assignment BMC Remedy BMC Atrium CMDB log files
monitoring diagnostics Tier logging AR System Email engine logs Approval Server
Engine logging logging
levels
Performance Performance Performance Configuring Tuning Tuning the BMC Atrium

tuning Tuning tuning Email Engine for performance for CMDB performance
maximum Approval Server
performance
Standards BMC Remedy BMC Remedy AR

AR System System standards
standards
Internationalization Language Language

and localization information information
Accessibility (508) Section 508 rules

for application
designers
Common problems Troubleshooting issues with

and tips BMC Atrium CMDB
Licensing Licensing Working with

Assignment sample users
Engine
Import and Reconciling data

reconciliation
Links to federated Configuring federated data

systems in BMC Atrium CMDB
Making changes to Process overview for

classes or creating or modifying
attributes classes
Collecting Gathering Collecting BMC Collecting BMC Collecting BMC Collecting BMC Collecting BMC Atrium
information for information for Remedy Mid Tier Remedy Email Remedy Remedy CMDB information
support support information Engine Assignment Approval Server
information Engine information
information
10.3 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
Checking system requirements and supported configurations.
10.3.1 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
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 Function
pack
or
patch
BMC Atrium 8.0 Provides a configuration management database (BMC Atrium CMDB) coupled with common user,
Core: programmatic, and reporting interfaces to accelerate attainment of BSM.

Product name Version Service Function

pack
or
patch
BMC BMC Atrium CMDB stores information about the configuration items (CIs) in your IT environment and
Atrium the relationships between them. Data consumers such as the BMC Remedy Asset Management
CMDB product read data from the production dataset.
BMC The BMC Atrium Integration Engine (AIE) product enables you to transfer data between an external
Atrium datastore and BMC Atrium CMDB or the BMC Remedy Action Request System product.
Integrator The Product Catalog provides a normalized reference of software, hardware, and other types of
Product products and their characteristics that enhance the accuracy of BMC Discovery products by uniquely
Catalog identifying a product regardless of installed name or location.
Service
Catalog
Atrium
Web
Services
BMC Remedy 8.0 Enables the building of powerful business workflow applications which can automatically track anything that
Action Request is important to the processes in your enterprise. Companies use AR System to track such diverse items as
System stock trades, benefits data, inventory assets, spare parts, and order fulfillment. A common use of AR System
is to automate the internal help desk.
BMC Atrium 7.6.02 1 SP 4 Delivers workflow-based process templates, with which customers can rapidly adapt and deploy functional
Orchestrator design to ensure consistent and appropriate, policy-based response across the enterprise.
Platform
BMC Atrium 20.12.03

Orchestrator
Content
BMC Atrium
Solution or Product name Version Service Function
suite pack
or
patch
BMC BMC Analytics 7.6.05.002 Hotfix Provides out-of-the-box interactive reporting and analysis that enables technical and
Dashboards for Business non-technical users to quickly examine data for trends and details associated with how
and Analytics Service IT is supporting business services and goals.
Suite Management
BMC Atrium BMC Atrium 8.3.2.2 Provides an automated method for discovering, cataloging, and maintaining a
Discovery and Discovery and company's configuration data.
Dependency Dependency
Mapping Mapping
BMC BMC 7.7 7.6.03 Provides highly interactive, timely access to key service support metrics to help IT
Dashboards Dashboards for 7.6.03 Hotfix management optimize decisions and accelerate the alignment of IT with business goals.
and Analytics Business Service 9
Suite Management
8.0


suite pack
or
patch
BMC Remedy BMC Service Enables a service provider, such as an IT organization, a customer support group, or an
IT Service Level external service provider, to formally document the needs of its customers or lines of
Management Management business by using service level agreements, and to provide the correct level of service to
meet those needs.
BMC Remedy BMC IT Business 8.0 Provides IT leaders visibility into costs, activities, assets, resources, and suppliers to
IT Service Management effectively manage the IT business and ensure business alignment.
Management
BMC Cloud Lifecycle Management

suite pack or
patch
BMC Cloud BMC Cloud 3.0 SP1 + Provides a complete solution for establishing a cloud environment, including a Service
Lifecycle Lifecycle hotfix Catalog that defines service offerings, a self-service console for procuring resources, and
Management Management cloud management capabilities.
BMC Cloud BMC Atrium 3.0 patch 2 Content for BMC Cloud Lifecycle Management.
Lifecycle Orchestrator
Management Content
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.
Service Operations - Application Performance Management

suite pack
or
patch
BMC BMC Transaction Management 4.1 Enables you to manage the performance and reliability of your
ProactiveNet Application Response Time, worldwide applications to measure site health based on end-user
Performance Infrastructure Edition or Service Level experience metrics, such as availability, accuracy, and performance.
Management Edition

Service Operations - Data Center Automation

Solution or Product Version Service Function
suite name pack
or
patch
BMC BMC 8.2.01 Automates the discrete tasks needed to deploy web applications and dramatically simplifies the
BladeLogic Application process, making it easier and less expensive for organizations to leverage web application server
Automation Release Add-on: technology.
Suite Automation - 8.2.01
Enterprise
Edition
BMC
Application
Release
Automation -
Standard
Edition
BMC BMC 8.2.01 2 Enables administrators to manage software changes, manage content changes, configure
BladeLogic BladeLogic endpoints, and collect inventory information.
Automation Client
Suite Automation
NA BMC 8.2.02 Integrates discovered configuration data with the BMC Remedy IT Service Management suite of
BladeLogic products. This integration enables you to use BMC Remedy Asset Management, BMC Remedy
Client Change Management, BMC Remedy Incident Management, and BMC Remedy Problem
Automation Management to access accurate, real-time information about IT infrastructure components
Discovery across your enterprise.
Integration
for CMDB
BMC BMC 8.2.00 SP 1 Provides the essential capabilities for automated database provisioning and maintenance,
Bladelogic Database thereby removing bottlenecks in the change and release processes and freeing Database
Automation Automation Administrators (DBAs) to make more valuable use of their time. As part of the BMC BladeLogic
Suite 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 BMC 8.2 SP 1 Used with the BMC Database Automation solution to provide extensive reporting capabilities
Bladelogic Decision based on the database devices that you manage.
Automation Support --
Suite Database
Automation
BMC BMC 8.2 SP 1 A web-based reporting and analytics tool, used together with the BMC BladeLogic Network
BladeLogic BladeLogic Automation solution to provide extensive reporting capabilities based on the network devices
Automation Decision you manage.
Suite Support for
Network
Automation
BMC 8.2 SP 1
BladeLogic
Decision

Solution or Product Version Service Function

suite name pack
or
patch
BMC Support for A web-based reporting application that provides extensive report capabilities related to your data
BladeLogic Server center servers that are managed by BMC BladeLogic. BMC Service Automation Reporting and
Automation Automation Analytics uses rich data warehouse schema and dimensional modeling principles to access and
Suite report on historical data captured by BMC BladeLogic.
BMC BMC 8.2 SP 1 Enables integration between BMC BladeLogic and Atrium components.
BladeLogic BladeLogic
Automation Integration
Suite 8.2.01 with Atrium
BMC BMC 8.2.02 Manages change, configuration and compliance of network assets.
BladeLogic BladeLogic
Automation Network
Suite 8.2.01 Automation
BMC BMC 8.2 SP 1 Acts as a platform for the management, control and enforcement of configuration changes in
BladeLogic BladeLogic the data center.
Automation Server
Suite 8.2.01 Automation
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

suite Pack
or
Patch
BMC BMC Capacity 9.0 Automatically analyze, forecast, and optimize performance and capacity across all
ProactiveNet Management - resources (IT and business) and environments — physical, virtual, and cloud.
Performance Capacity
Management Optimization
BMC BMC Portal, 2.9.10* Provides a common web-based interface for managing and monitoring your IT
ProactiveNet including infrastructure while monitoring business services.
Performance BMC Performance
Management Manager Portal 2.9
BMC PATROL Provides monitoring for the BMC ProactiveNet Performance Management suite.
ProactiveNet
Performance Agent, KM:
Management 8.6 (7.5.62)
BMC PATROL
Consoles and
Infrastructure
7.8.12
BMC PATROL
for Servers
9.11.00


suite Pack
or
Patch
BMC BMC ProactiveNet 9.0 A real-time analytics solution that detects performance abnormalities in the IT
ProactiveNet Core environment, delivers early warning of degrading performance, and reduces time from
Performance BMC ProactiveNet issue detection to resolution. This early warning is delivered by Intelligent Events that
Management Performance result from analyzing and correlating data across the monitored IT infrastructure,
Management speeding the ability to detect abnormal trends before end users and mission critical
Reporting 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 worldwide applications to
ProactiveNet Management measure site health based on end-user experience metrics, such as availability, accuracy,
Performance Application and performance.
Management Response Time,
either Infrastructure
Edition or Service
Level Edition
BMC Integration for BMC 9.0 Patch Provides the integration from certain Service Assurance products to BMC Remedy IT
ProactiveNet Remedy Service 1 Service Management.
Performance Desk
Management
Service Support
suite Pack
or
Patch
BMC Remedy BMC Remedy IT Service 8.0 The BMC Remedy Asset Management application lets IT professionals track and
IT Service Management: manage enterprise CIs - and their changing relationships - throughout the entire
Management CI lifecycle.
Suite BMC Remedy Asset
Management BMC Remedy Change Management provides IT organizations with the ability to
BMC Remedy manage changes by enabling them to assess impact, risk, and resource
Change requirements, and then create plans and automate approval functions for
Management implementing changes.
BMC Remedy
Service Desk, BMC Remedy Service Desk allows IT professionals to manage incidents, problem
including: investigations, known errors, and solution database entries.
BMC
Remedy
Incident
Management
BMC
Remedy
Problem
Management
BMC Remedy BMC Remedy Knowledge 8.0

IT Service Management


suite Pack
or
Patch
Management Allows users to author and search for solutions in a knowledge base. It includes a
Suite comprehensive editor with extensive editing tools and a robust search engine that
allows users to search for solutions using natural language or Boolean searches.
BMC Remedy BMC Service Level 8.0 Provides a way to review, enforce, and report on the level of service provided to
IT Service Management ensure that adequate levels of service are delivered in alignment with business
Management needs at an acceptable cost.
Suite
BMC Remedy BMC Service Request 8.0 Allows IT to define offered services, publish those services in a service catalog,
IT Service Management and automate the fulfillment of those services for their users.
Management
Suite
10.3.2 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.
10.3.3 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
10.3.4 Related topics

System requirements
10.4 Deployment architecture

This section contains the following information:
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 Remedy AR System clients
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 Level Management version 8.1
BMC Service Request Management version 8.1
10.4.1 Email deployment use cases

This section provides use cases for deploying inbound and outbound email in the BMC Remedy OnDemand
2013.01 environment.
All of these use cases have been tested for low, medium, and high email volume rates. The email volume rates are
defined as follows:
Rate Description
Low 10 emails every 5 minutes (peaks up to 30)
Medium 100 emails every 5 minutes (peaks up to 150)
High 300 emails every 5 minutes (peaks up to 500)
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:
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.
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
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:
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.
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
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
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
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 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
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

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 60 seconds For information about configuring BMC Remedy Email Engine mailboxes,
minutes see Configuring BMC Remedy Email Engine mailboxes.

Setting Value Related information
InComing Advanced Default configurations For information about configuring BMC Remedy Email Engine mailboxes,
Email configuration tab see Configuring BMC Remedy Email Engine mailboxes.
Outgoing Email Protocol SMTP For information about configuring BMC Remedy Email Engine mailboxes,
see Configuring BMC Remedy Email Engine mailboxes.
Outgoing Polling interval 60 seconds For information about configuring BMC Remedy Email Engine mailboxes,
minutes see Configuring BMC Remedy Email Engine mailboxes.
Outgoing Advanced Default configurations For information about configuring BMC Remedy Email Engine mailboxes,
Email configuration tab see Configuring BMC Remedy Email Engine mailboxes.
Outgoing email daemon MailboxPollingUnitslsMinutes = false For information about configuring the EmailDaemon.properties file, see
properties OutgoingMessagesQueueSize = 400 EmailDaemon.properties file.
Incoming email daemon IncomingConnectionRecycleSize = 100 For information about configuring the EmailDaemon.properties file, see
properties IncomingMessagesQueueSize = 100 EmailDaemon.properties file.
MailboxPollingUnitlsMinutes = false
NumberOfSenderThreads 4 For information about configuring the EmailDaemon.properties file, see

Minimum and maximum Minimum Java heap size = 256 MB (to be For more information about configuring heap size, see Defining a heap size
Java heap size set in registry) for the BMC Remedy Email Engine.
Maximum Java heap size = 1024 MB (to
be set in registry)
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
Stopping and starting the Email Engine
Tuning the Email Engine performance
Load balancing with Email Engine
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 load Run Attachment Time taken to Average number of Average Average CPU, BMC Remedy
email duration process all emails emails read from number of AR System and email
volume Exchange server incidents memory utilized
created
Total Inbound 10 No Based on incident 40 22 N/A

emails = emails = minutes creation date = 27
2400 600 minutes
Outbound Based on incident

emails = reported date = 15
1800 minutes
Total Inbound 10 Yes Based on incident 50 23 N/A

2400 600 Size of one minutes
attachment is 26
Outbound KB Based on incident
1800 15.23 MB for minutes
600 inbound
emails

2400 600 Multiple minutes
attachments
Outbound (PDF,TXT and Based on incident
emails = XML) reported date = 15
1800 minutes
15.23 MB for
600 inbound
emails
Total Inbound 12 Yes Based on incident 30 19 Average processor

emails = emails = hours creation date = 38 utilization: 55.190
172800 43200 Size of one hours
attachment is
Outbound 26KB Based on incident
129600 1096 MB for hours
43200 inbound
emails

emails = emails = hours creation date = utilization: 53.344
172800 43200 Size of one 33.30 hours

created
attachment is 26
43200 inbound
emails
Volume testing results for inbound and outbound emails in a server group environment
created
Total Inbound 10 No Based on incident 46 28 N/A

2400 600 minutes
Outbound Based on incident

1800 minutes

2400 600 Size of one minutes
attachment is 26
1800 15.23 MB for minutes
600 inbound
emails

2400 600 Multiple minutes
attachments
Outbound (PDF, TXT and Based on incident
emails = XML) reported date = 14
1800 minutes
15.23 MB for
600 inbound
emails

emails = emails = hours creation date = 33 utilization: 0.670 (BMC
172800 43200 Size of one hours Remedy AR System box)
attachment is 26
Outbound KB Based on incident Average processor
emails = reported date = 24 utilization: 34.083 (Email)
129600 hours

created
1096 MB for
43200 inbound
emails

emails = emails = hours creation date = 28 utilization: 1.493 (BMC
172800 43200 Size of one hours Remedy AR System box)
attachment is 26
Outbound KB Based on incident Average processor
emails = reported date = 24 Utilization: 54.211 (Email)
43200 inbound
emails
10.4.2 Performance benchmarks and tuning

The following topics provide information about how to fine-tune BMC Remedy AR System:
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:
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

Consider the factors in this section at the start of every single-user benchmark.
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
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
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
Browser is cached from the First Session access

Mid-tier Tasks
logon
session
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:
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
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:
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

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
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.
Select typical business transactions
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.
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.
Prepopulate transaction data

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.
Parameterize user input
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.
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.
Control random user input
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.
Determine transaction contents
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 scripts thoroughly
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. 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
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:
Determine users with assigned tickets

Determine users with proper permissions
Modify user passwords
Determine search criteria
Back up the test production database

Determine users with assigned tickets
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
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.
Incident.
step 3.
3. Query for Incident Submitter permissions, excluding Incident Master, Incident User, and Infrastructure
Change permission groups.
Incident.
step 4.
4. Query for Incident Viewer permissions, excluding Incident Master, Incident User, Incident Submitter, and
Infrastructure Change permission groups.
Incident.
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.
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
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:
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
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.
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
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
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.
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 8 5
Update change 2 2
Search change 2 5
Create change 2 2
View service request 10 2
Update incident 10 6
Create service request 12 3
Browse service categories 2 5
Create incident 9 6
Search for incidents 15 6
Lookup service context 1 9

Transaction name Percentage of users Transaction pacing

(transactions/user/hour)
Update work order 9 6
Search service request 15 2
Knowledge search and view 3 3
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.
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
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.
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

Transaction Phase Transaction steps Repeat? Timed?
Not applicable Not applicable Open the Change form in Search mode No, refresh sometimes Yes
Not applicable Not applicable Randomly enter a Change entry ID and click Search Yes Yes
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.
Setting up the test environment

This topic explains how to set up your test environment:
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.
Start with a basic configuration
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.
Use one system per tier
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
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)
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

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
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
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
Make one change at a time

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
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.
Show results based on goals
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
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
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.
Setting up the test environment

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 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.
Scoping project schedules

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
Goal Tasks
Getting started Set goals
Test scenarios
Use one application per scenario
Select typical business transactions
Script actual use cases exactly as executed by users
Write autonomous scripts for each scenario
Prepopulate transaction data
Parameterize user input
Control random user input
Determine transaction contents
Include wait times
Test scripts thoroughly
Volume data
For production data:
Determine users who have assigned tickets
Back up the database
For synthetic data:

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
Start with a basic configuration
Use one system per tier
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

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
Analyze results after each test run

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
Make one change at a time
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
Show results based on goals
Use graphs and charts to clarify results
Summarize actual throughput
Add appendix of environment specifications and software and hardware configurations

Scoping project schedules
Estimate generous time for your benchmarking project
Performance tuning for BSM

The Business Service Management (BSM) product suite can dramatically simplify an organization’s 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:
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.
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
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
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:

2.
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:
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

For more information about collecting response time data, see Benchmarking for a single user.
System performance and capacity

This topic contains the following information:
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
Monitoring CPU consumption

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.
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
application’s 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.
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.
Monitoring memory consumption

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 configuration’s physical memory is in use during application
execution is important.
A modern OS always provides a virtual memory space that far exceeds the system’s physical memory. If an
application consumes nearly all the system’s 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.
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 system’s 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:

The web component for the BMC Remedy AR System platform is the BMC Remedy Mid Tier (the mid tier). The
mid tier’s 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.
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 browser’s 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:

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.
Fine tuning the network for HTTP protocol

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
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 browser’s 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 browser’s 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.
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

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:

blank connectionTimeout="60000"
blank maxHttpHeaderSize="8192" maxKeepAliveRequests="5000"
blank maxThreads="500" port="80" protocol="HTTP/1.1"
blank redirectPort="8443"/>

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

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

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.
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.
Fine tuning the web stack

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:
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.
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:
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
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 JVM’s.
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.
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.
The snapshot appears with timestamp in the navigation tree under Snapshots.
11.
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

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 Sun’s 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-jsp-140102.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
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 application’s 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
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 vendor’s 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
This changes the young and the old generation collectors from the default to the low-pause GC. If you have
other GC’s already set, remove those arguments.
The following figures show a low-pause GC versus a throughput GC for the same 2 CPU’s 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
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.
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 system’s 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:
-Ms2048m -Mx2048m

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.
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
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 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
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
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 20-minute
monitoring interval.
Normal heap usage under load with low-pause GC

Normal heap usage under load with throughput GC
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.
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 system’s runtime
behavior depends on many external variables.
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.
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.
<Connector URIEncoding="UTF-8" acceptCount="100" connectionTimeout="60000"

blankmaxHttpHeaderSize="8192" maxKeepAliveRequests="5000" maxThreads="600"
blankport="80" protocol="HTTP/1.1" redirectPort="8443"/>
Fine tuning the mid tier web application

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.
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:
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 object’s
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.

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.
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
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 tier’s 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 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:
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 browser’s 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.
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
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
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.
Connection pool settings
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 tier’s 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 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:
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
Browser hardware requirements and settings

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

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

Mid tier case studies

The following case studies illustrate performance improvements achieved by fine tuning the mid tier:
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
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.
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.
Tuning the AR System server

This section contains the following information:
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.
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

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.
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:
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.
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.
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:
SELECT
T313.C1,C750010114,C750010112,C750010109,C750010103,C750010113,C750010118,C750010101,
C750010102,C750010108,C750010106,C750010107,C750010110,C750010111, C750010115,C750010119,
C750010120 FROM aradmin.T2800
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)

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=134756579
Configuring AR System server queue threads

Ideally, when requests come into the AR System server, there is little or no wait time before a worker thread starts
to process the request. If all available threads are processing other requests, the new request and all future
requests must wait until a thread becomes available.
Performance can be severely impacted depending on how long the new request must wait for a thread to
become available.
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:
// :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 201216: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
If the workload is heavy, use thread 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 component’s workload does not directly interfere with the regular workload running
on fast and list threads by having separate pools
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.
Thread tuning for workload components
Component Suggested Where to configure the Private How to configure the internal thread count
Private-RPC-Socket Queue to use
setting
Full-Text 390602 4 6 Not applicable In the *\pluginsvr\fts*

Search Engine pluginsvr_config.xml file, enter the following setting:
<numCoreThreads>10
</numCoreThreads>

setting
Email Engine 390681 2 2 Emaildaemon.properties The number of threads connecting to the AR System server is the
com.bmc.arsys.emaildaemon. number of mailboxes.
<serverName>.RPC=390681
Flashboards 390619 1 1 Set the ARServerRpcNumber Flashboards is single-threaded.

parameter in
ARSystemInstallDirectory
/flashboards/server.conf
CAI 390626 5 5 Open the CAI Plug-in Registry In the CAI Pool Configuration section, for pool 0, make sure the number
through Application Console > of the threads is 3. The CAI plug-in for BMC Remedy IT Service
Customer Configuration > Management uses pool 0. Another application uses pool 1000. The total
Foundation > Advanced Options of all pool threads is listed in the Total Threads field.
> PlugIn Registry.
In the CAI Plug-in Registry dialog

box, either create a new entry if
one does not exist for Private
Queue 390626 or modify the
existing entry.
Overview 390685 4 6 Configure the APPQUERY In the \pluginsvr\fts

Console (conquery) plug-in with the \pluginsvr_config.xml file, enter the following setting:
Plugin-Loopback-RPC-Socket <numCoreThreads>30
user-defined property and the </numCoreThreads>
RPC value pointing in the
ARSystemInstallDirectory The core threads are shared with the other plugins in this plugin server.
\ARSystem
\pluginsvr\pluginsvr_config.xml
file.
Atrium Any valid private To set an AIE default RPC-socket, From the Data Exchange page for each Exchange, choose the Advanced
Integration socket edit the aie.cfg file in the tab and provide a value for the Number of Threads. The default value is
Engine AtriumInstallDirectory 3. The maximum value is 49.
\aie\service64\conf folder, and
set the PrivateRPCPort
parameter.
To specify a private socket per

exchange, go to the Data
Exchange page for each
Exchange, and click the
Connection Settings tab, clear
Use default destination AR server,
and specify the RPC Program
Number.
Normalization 390699 BMC Atrium Core Console > BMC Atrium Core Console > Normalization > Configuration Editor
Engine Normalization > Configuration >System Configuration >Threads and Connections
<1 x #CPUs> Editor > System Configuration >
CMDB RPC Queue
<1 x #CPUs>

setting
Normalization 390621 BMC Atrium Core Console >

Engine AR Normalization > Configuration
RPC Queue <1 x #CPUs> Editor > System Configuration >
RPC Queue
<1 x #CPUs>
Business Rule 390625 1 2 BR-RPC-Socket: 390625 Single-threaded

Engine
Approval 390680 3 10 Approval-RPC-Socket: 390680 For versions prior to 8.0, Approval server is single-threaded. Set 390680
Server 1 2.
For 8.0 and later, Approval Server in multi-threaded and runs as a Java
plug-in. Use the Approval Administration Console > Server Settings >
Basic > Thread Count to set the number of threads (Thread Count) that
the Approval Server will use. This is the ASJ-Thread-Count option in
ar.cfg (ar.conf). Set Private-RPC-Socket: 390680 to match this. 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, you might set Private-RPC-Socket to a higher number.
Reconciliation 390698 RE-RPC-Socket, which is

Engine typically set through the UI at
<1 x #CPUs> BMC Atrium Core Console >
Reconciliation > Server
<1 x #CPUs> Configuration Editor > RPC
Socket.
AREA-LDAP Plugin-AREA-Threads
ARDBC-LDAP 390626 5 5 Plugin-Loopback-RPC-Socket: Plugin-ARDBC-Threads

390626
DSO Any valid RPC For a local server, go to AR Developer Studio > Distributed Pools > Create new pool. Each pool is a
socket System Administration Console > single thread.
General > Server Information >
Connection Settings > DSO Local
RPC Program Number.
For a remote server, go to AR

System Administration Console >
General > Server Information >
Connection Settings > DSO
Server Setting Table.
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
BMC Atrium CMDB normalization and reconciliation processing is 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.
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 Recommended

parameter value
Private-RPC-Socket Set this parameter for fast and list threads values only. Fast thread
(Fast:390620) values equal 3
times the
Private-RPC-Socket number of
(List:390635) 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 blocks increases 100
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.

AR System server configuration Description Recommended

parameter value
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 1000 (this is
server retrieves at one time from the database and stores in memory to process during filter the default)
or filter guide actions. The server then retrieves, stores, and processes the next chunk until
all requests are processed.
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 F (disallow)
values are T (allows unqualified searches) or F (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 0
development mode, user operations might be delayed when changes are made to forms (development
and workflow. Valid values are 1 (development cache mode is on) or 0 (development cache mode off; this
mode is off and the server is in production cache mode). The default value is 0. 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 default value is 0 (the Set to a value
server communicates with all API versions). appropriate for
your
Generally, your system should support two earlier versions. If the client’s API version is less production
than the specified value, the server refuses to talk with the client, and the client receives a environment.
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 600 (10
cache-related data. The default is 300 (5 minutes) if the entry does not exist in the AR minutes)
System server configuration file.

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.
This section provides the following information for tuning database servers:
Tuning an Oracle server

This section provides the following information for the Oracle database:
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
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 recommended values 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 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 Oracle’s 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 10 g 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.
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.
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.
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 1 10.6 System I/O
Log file sync 14,965 10 1 10.4 Commit

Event Waits Time (sec) Average wait (msec) % total call time Wait class
Control file sequential read 21,781 10 0 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
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.
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 */OK

* Tue Dec 07 2010 08:13:54.2535 */SELECT C456 FROM T1253 WHERE C1 = '000000000004902' FOR UPDATE
* Tue Dec 07 2010 08:13:54.2536 */Set LOB into the above row...
* Tue Dec 07 2010 08:13:54.2550 */OK
* Tue Dec 07 2010 08:13:55.0727 */UPDATE T1253 SET C459 = EMPTY_CLOB() WHERE C1 = '000000000004902'
* Tue Dec 07 2010 08:13:55.0759 */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
tim=295710596738
tim=295710596787WAIT #0: nam='SQL*Net message to client' ela= 5 driver id=1650815232 #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

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:
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
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
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?
Monitoring CPU consumption
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.
Monitoring memory consumption
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.
Fine tuning the network for HTTP protocol
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)
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.
Fine tuning the web stack
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
Young generation Copying Collector (default) Parallel Copying Collector Copying Collector Parallel Scavenge
-XX:+UseParNewGC (default) Collector
-XX:UseParallelGC
Old generation Mark-Compact Collector Concurrent Collector Mark-Compact Collector Mark-Compact Collector
(default) -XX:+UseConcMarkSweepGC (default) (default)
Permanent GC not configurable but can be turned off via JVM arg -Xnoclassgc
generation
Activate the 64-bit JVM hybrid mode:

-XX:+UseCompressedOops
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):
connectionTimeout="60000"maxHttpHeaderSize="8192" maxKeepAliveRequests="5000"
maxThreads="600" port="80" protocol="HTTP/1.1" redirectPort="8443"/>

Fine tuning the mid tier web application
To fine tune the mid tier web application, set the values as described in the following table.
Mid tier parameter or service Recommended value
Enable Cache Persistence (mid tier cache For a production environment, this parameter is always set to on.
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 Set both parameters to the same value to reflect how often you want the browser to check with the
arsystem.resource_expiry_interval 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_category=INTERNAL
arsystem.log_level arsystem.log_level=Severe
These settings can also be applied by using the Mid Tier Configuration Tool.
Connection pool settings 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.
Browser hardware requirements and settings
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.

Tuning the AR System server
Allocate AR System server resources.

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

Parameter Recommended value
Private-RPC-Socket (List:390635) 5 times the number of CPUs
Next-ID-Block-Size 100
Server-Side-Table-Chunk-Size 1000
Allow-Unqual-Queries 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)
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.

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
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)
Atrium load: 7,500 CI+ Relationship (90% update to existing CI’s, 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.

CPU utilization
The following table shows CPU utilization measured by using perfmon.

Memory utilization
The following table shows memory utilization measured by using perfmon.
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. Some points that you should remember are:
Set limits on the number of workflow filters executing on an API call — This ensures that recursive
execution does not bring the server down.

Enforce a minimum client version — to use the latest security updates and features.
Set the re-cache delay — to prevent the server from reloading its cache too often. The server rebuilds its
cache every time object definitions change. The default re-cache interval is 5 seconds. Increasing this
value, allows the server to process multiple changes in batches, thereby improving server performance and
response time. However, it also increases the delay in availability of new changes to other threads.
The following topics provide information about performance tuning:
Tuning and managing system performance

This topic outlines the tools and methods available to administrators and developers for monitoring and
enhancing BMC Remedy AR System performance.
You can tune the system through configuration parameters in the mid tier. Use the following tips to tune the
system for optimal performance:
If you are using version 7.5.00 Patch 004, do not turn off connection pooling in the mid tier configuration (
arsystem.use_connectionpooling) unless you are working with a load balancer.
On a production system, verify that the following properties are set in the mid tier config.properties file:
arsystem.cache_update_interval=86400
arsystem.formhtmljs_expiry_interval=86400
arsystem.log_level=Severe
These values are recommended for improving mid tier performance in a functionally stable
production setup.
The number of users and applications, selection of hardware and software vendors, and actual hardware
determine performance, so consider these parameters when you begin designing a system.
The type of web server and JSP/servlet engine you use affect performance. For best performance, choose
a combination of web server and JSP/servlet engine that your company understands and that is listed on
BMC's compatibility matrix. If your company does not have a preferred combination of web server and
JSP/servlet engine, BMC recommends using Tomcat, which is bundled with the mid tier and can be
installed as a stand-alone HTTP web server and JSP/servlet engine. Or, it can be installed as a JSP/servlet
engine and plugged into IIS or Apache web servers. Tomcat is easy to configure and tune, and BMC fully
supports it.
Ensure that your browser uses HTTP 1.1 so that the mid tier can take advantage of data compression. (This
does not work in Internet Explorer if you configure a proxy server through Tools > Internet Options >
Connections > LAN Settings.)
On a production system, clear the Perform Check check box on the Cache Settings page of the BMC
Remedy Mid Tier Configuration Tool, so that the cache check time setting is ignored. When the check box
is selected, the mid tier does not re-cache.
Depending on your web server, consider how you set the connection-pooling limits and web server thread
limit.
To improve performance, consider how Microsoft SQL server behaves.

If you enable the Persistent Cache option for the mid tier, you might have to increase the Tomcat
shutdown time and thread stack sizes.
Limit the combinations of groups to which a user can potentially belong. This will decrease the amount of
items in your cache and its size.
A majority of the time, the mid tier is indirectly tested through performance tuning of your application.
Unless you make modifications to the application, you do not have to tune the application. Instead, review
your configuration to see how you can improve throughput.
To fine-tune your Java parameters, review your mid-tier cache settings. Mid-tier cache caches these kinds
of objects:
Form definitions
Field graph (field definitions on a form)
HTML and Javascript
When you configure your system, do not prefetch every form. Include the most commonly used forms
(preferably forms that users use). When your system initially starts, it is slower because these forms must be
fetched, but subsequent users who reference the form do not have a delay because the form is already
cached. Every form has multiple copies of the form cached depending on the groups for each field. So, if
you have many groups and if field permissions are granulated, many different copies of the form are
cached. This adds to your memory footprint. Also, an accessibility user receives different HTML, and this
adds to the cache.
If you are using 7.5.00 Patch 004 and want the mid tier to preload all your forms automatically, select the
Pre-load check box and set its value to Yes in the Mid Tier Configuration Tool.
Note
The Pre-load option does not load all the forms in the AR System server; it loads only those forms
that have some active links associated to it or those forms that need to load some active links.
If preload is enabled, you do not need to configure a prefetch list with the mid tier, and you do not need
the precache file. However, if you are using patches earlier than patch 004, use the precache file. The
prefetchConfig.xml file is used for backward compatibility and if preload is not enough.
The Java minimum memory setting should be at least 512 MB. To determine max heap settings, use a
performance monitoring tool (such as perfmon or OptimizeIt on Windows, or JConsole on UNIX) to see a
trend over time. Usually, if an out-of-heap error occurs, the system hangs, and you do not receive a
notification. The recommended Java heap sizes for enterprise systems are 1 GB (minimum) and 1.5 GB
(maximum). Your cache settings have an effect on memory. See the two previous points. If you cache every
form, you might run out of memory.
Heap size and caching are related. After you start your system, watch the JVM process to make sure that it
is not constantly swapping memory.
If Thread stack size (in the Tomcat configuration tool) or the -Xss JVM parameter (for the Servlet Engine
startup) are set too high, you might run out of memory.
To identify mid-tier performance problems:

On the Log Settings page of the Mid Tier Configuration Tool, select the Performance and Servlet
check boxes for Log Categories.
Set Log Level to Fine.
Set Log Format to Simple Text.
Reproduce the slow performance.
For some problems, you might need to set Log Format to Detailed. In version 7.6.04, the detailed output
includes thread numbers so that you can track the logging by user. BMC Support can analyze these logs to
determine slow-running API calls or workflow execution.
Finding performance problems in the mid tier might require a combination of performance tools and
logging information from other products. Consult with your Support representative.
When multiple users perform unqualified searches or when the search result contains a large amount of
data, the mid tier requires a large amount of memory. This might result in out-of-memory errors. To avoid
this issue, chunked transfer encoding is implemented. It enables the mid tier to break the search result into
small chunks and stream them to the browser. This significantly reduces the mid tier memory usage during
search. To enable the streaming of large search results, you can configure the property
arsystem.min_entries_for_streaming in config.properties. By default, the value is set to 1000.
For example, arsystem.min_entries_for_streaming = 1000. When the number of records in the
search result is equal to or greater than the set value (1000), the mid tier uses streams search results using
the chunked transfer encoding.
For recent whitepapers, see Locating white papers, guides, and technical bulletins.
Establish performance goals

This section outlines the tools and methods available to administrators and developers for monitoring and
enhancing BMC Remedy AR System performance. Performance refers to operating efficiency, or response time.
Many factors affect performance, including hardware components, network capacity, database efficiency, and
application design. Managing performance, called performance tuning, involves establishing performance goals,
gathering baseline data, monitoring system behavior, and troubleshooting specific issues.
It is important to establish and document performance goals before you begin making adjustments. The
documented goals serve as guidelines against which you can measure system performance to determine where
you might need to make adjustments.
If performance goals reflect ideal conditions, system performance might not match the goals, but goals are a
valuable tool for evaluating performance. You might want to gather baseline data first, and establish goals that
reflect your system capacity.
Additionally, when you must troubleshoot a performance issue, you can set smaller goals focused on that issue.
See Troubleshoot AR System performance issues.
Memory limitations that can affect performance

This section provides information about memory limitations for 32-bit versus 64-bit AR System server process on
various operating systems.

Default memory limits for 32-bit processes

The following table lists the approximate memory limits for a 32-bit AR System server process on a single
operating system. Various factors — such as the amount of free physical memory and swap space and the
number of applications running on the same system as the server — might change the limit.
Default memory limits for a 32-bit process
Operating Maximum RAM Comments

system per process
AIX 2.5 gigabytes (GB)
HP-UX 1.75 GB To increase this limit to about 2.5 GB, use chattr to include the third data quadrant.
Linux 3 GB
Solaris 4 GB
Windows 1.8 GB According to Microsoft documentation, using the /3GB switch can increase this limit to just under 3 GB. Before
(32-bit) using this switch, consult your system administrator.
Note
See Reducing memory using Display Property Caching.
Reducing memory use using Display Property Caching

You can use the Display Property Caching feature to resolve 32-bit AR System server memory constraints, and to
reduce server startup time by configuring how the server caches display properties.
On the Configuration tab of the Server Information form, 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 Caching display properties and Setting administrative options.
Note
The Cache only server display properties setting may impact performance when display properties are
requested, but the impact is not significant.

Using 64-bit operating system for UNIX and Linux

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 take advantage of the 64-bit address space on 64-bit operating systems. This
provides enhanced server reliability in enterprise environments.
If you use large applications such as those in the BMC Remedy ITSM Suite, be aware of the memory impact of
operations that result in caching. Consider upgrading to the latest version of BMC Remedy AR System.
If memory limits are causing your AR System server to stop responding on a UNIX or Linux platform, consider
upgrading to latest version of BMC Remedy AR System so that it can take advantage of more memory.
Note
On a UNIX operating system, after memory is allocated to a process, the memory is not released by the
operating system. Although the 32-bit AR System server process releases memory back to the operating
system when it completes an operation, the UNIX operating system does not release the memory for
reuse. The amount of memory consumed by the process increases, but it does not decrease after the
process is finished using the memory. This is a limitation of the UNIX operating system's memory
managers.
Not all operating system memory managers behave this way. For example, on Windows, unused memory
is released back to users.
Using 64-bit operating system for Windows

BMC Remedy AR System 7.6.x and later versions include a 64-bit server for Windows, which can only be run on
64-bit Windows.
If you run the AR System server on Windows, a 64-bit operating system and server are recommended to allow use
of more memory. Proper change management processes and disciplines (such as making administrative changes
during scheduled maintenance and outage periods rather than during business hours) should still be practiced.
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 native 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 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.
The following topics provide detailed information about the various debugging tools for BMC Remedy AR System:
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.
To record server statistics for baseline data
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 options and their descriptions, see the ARGetServerStatistics function.
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
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:

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

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 Remedy Developer
Studio.
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.

Thread configuration performance guidelines

The optimal number of threads for each queue depends on a number of variables that can change quickly and
often. The primary factors you should consider when setting thread counts are:
API logs
Number and speed of CPUs
Amount of available RAM
Mix of fast and list operations
Network bandwidth
A brief overview of these considerations is provided in the following sections.
Thread configuration and API logs

API logging helps determine the optimal number of fast and list servers for your system. Examine the API log for
operations involving different users that occur without any lapse in time between operations. If the end time for
one user is the same as the start time for the next user, the second user operation was queued at the server,
waiting for the first operation to complete. If more than 10 percent of the API calls are being queued for a
particular server queue type, consider adding another thread of that queue type.
It is recommended that changes in thread configuration be made conservatively. Increase or decrease the
number of any queue by two threads at a time. Make an evaluation after each change, especially when adding
threads, to see if there is performance improvement. Because configuring too many threads itself can be a source
of performance issues, do not introduce additional performance obstacles when adding threads.
Be sure to run baseline tests before you add queues, to establish overall performance standards with the current
thread configuration. Run these same tests for comparison after adding or decreasing threads. If performance
improves, you have objective evidence that the thread configuration changes addressed your performance issues.
Without baseline testing, it will be difficult to know whether there is any improvement or whether the change has
had a negative impact on overall performance.
Number and speed of CPUs
The number of CPUs in the computer (or virtual machine in a partitioned system) on which the BMC Remedy AR
System server is running has a significant effect on the optimal thread settings. Consider the number of CPUs as a
guideline for determining the minimum thread count for each queue. An optimal minimum thread count is
typically 1 to 2 times the number of server CPUs. The more CPUs that are available to the BMC Remedy AR
System server, the fewer number of minimum threads are needed.
Amount of available RAM
The main consideration for memory is to make sure that there is enough to support all threads. Just as the
number of CPUs helps define the minimum thread settings, the quantity of server memory helps determine the
maximum thread settings.
Each additional thread will result in increased memory requirements. See the compatibility matrix for the

minimum memory required for operating the BMC Remedy AR System server. Running the BMC Remedy AR
System server on a server with the minimum memory required will result in minimum performance, even when
no additional threads are configured.
Mix of fast and list operations
Predicting the mix of operations on a production server can be difficult. API logging can help you determine if a
server tends to handle more fast or list operations. Consider testing your system under load to determine
appropriate settings.
Network bandwidth
Network bandwidth and optimal thread counts do not have a direct effect on each other. However, be sure that
you have sufficient bandwidth to support the expected level of server activity. Remember to account for traffic to
and from the database if the database resides on a different computer. The amount of traffic between the server
and database is usually about the same as the traffic between the server and clients. Therefore, if your database is
kept on a separate server, it is likely that it will approximately double the network bandwidth requirements.
Load management performance guidelines

The overall system load on your computers affects performance. In general, the more applications you have
running, the slower your system runs.
Other applications running in parallel with BMC Remedy AR System contend for the same resources. These
applications can demand hardware resources on the server or client. They also might access the same database
as BMC Remedy AR System, resulting in slower performance. Major system and network activities during peak
work hours might compete with BMC Remedy AR System for resources, so be aware of how other applications
are being used. Consider moving applications to another server, or dedicating a server to BMC Remedy AR
System and the DBMS if inadequate system resources are contributing to system performance issues.
User actions performance guidelines

The following user actions can affect the performance of your system:
Running other applications on their computers, which compete for resources

Running large reports during peak work hours or running unqualified or poorly constructed searches,
which compete for system resources
Users should design reports to return only the data needed.
Setting up automatic polling for results lists
Users should eliminate automatic polling or lengthen the polling interval.
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
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.
Tuning database performance

The following guidelines can help you set up a database that runs efficiently with BMC Remedy AR System:
Tune your database by using the methods suggested by your database vendor. You might modify your
database parameters, kernel parameters, and the physical storage device.
If BMC Remedy AR System is sharing a database server with other applications, BMC Remedy AR System
might run slowly. It is recommended that you dedicate a database server for BMC Remedy AR System.
If you run remote database servers, you increase the traffic over your network, resulting in slower system
performance. In addition, remote databases consume other operating system resources on the local
computers, such as memory. Make sure that your network does not decrease performance if you run a
remote database.

Allocate enough memory to the database where you run BMC Remedy AR System. If your database does
not have enough memory or data cache, your system will perform poorly. Allocate as much memory as
you can spare. See Maximizing memory allocation for database tuning.
If you spread BMC Remedy AR System database over multiple devices, you can improve database
performance, especially if you have a large BMC Remedy AR System database. For more information, see
Database performance tuning with SQL statements.
Index fields where searches are performed. Proper indexing is one of the most significant performance
improvements you can implement. See Create effective indexes.
For information about optimizing performance on specific databases, see Using relational databases with BMC
Remedy AR System. Work with your database administrator to determine database performance solutions.
Maximizing memory allocation for database tuning

Maximizing the amount of memory given to the DBMS allows more data to reside in memory, reducing the total
number of physical disk accesses. Reading data from memory is much faster than reading data from the disk, so
performance improves when the amount of memory allocated to the DBMS is maximized.
When a page of data is read from disk, it is placed in memory where a logical read is performed. Assuming that
the page remains in memory, the next time that data is accessed, it is read from memory rather than disk.
A logical read from memory is hundreds of times faster than a physical read from disk. The access times of disk
drives are in milliseconds, whereas the access times of memory chips are in nanoseconds. Achieving a high ratio
of logical reads to physical reads results in better performance. This is called the buffer cache hit ratio. The buffer
cache hit ratio should be maintained at 85 percent or higher for optimum performance.
To configure DBMS memory
1. Determine the total amount of memory available on the computer.

2. Calculate the amount of memory required by the operating system and any other applications running on
that computer.
3. Confirm with your database administration support staff or database vendor that the amount of memory
left is adequate for running a database for your size implementation.
4. Configure all remaining memory to the DBMS. Do not exceed the total disk space used by the database
files and devices. Consider anticipated growth.
Note
Calculate the amount of memory required by the operating system and any other applications
running on that computer before maximizing the amount of memory given to the DBMS.
Allocating too much memory to the DBMS might not leave enough for the operating system and
other applications. This can cause overall performance to suffer. Allocating inadequate memory to

the DBMs will result in poor database performance and will have a direct impact on overall system
performance. For optimum performance, work closely with your system administration and
database administration support staff to make sure that you have adequate memory resources.
Server side table field chunk size

For server-side table fields, the number of entries included in a table field chunk can affect performance. This
value is entered in the Configuration tab of the BMC Remedy AR System Administration: Server Information form.
It determines the number of entries (or size of the chunk) that the server will retrieve at one time from the
database and store memory to process during filter or filter guide actions. The server then retrieves, stores, and
processes the next chunk until all the rows have been processed.
Entering a value of zero (0) will cause 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, which keeps server memory usage
down, but results in slower processing because the server will need to access the database many times, especially
for large tables. Entering a high value will cause 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. The default value of 1000
entries is recommended because it is small enough to keep the server from allocating a large amount of memory
when processing large tables.
Tuning database performance with SQL statements

When you create forms and indexes, your database allocates space for the structures. Generally, BMC Remedy AR
System handles everything automatically. However, to control some of the options yourself, BMC Remedy AR
System enables you to attach a clause to the SQL statements that create forms and indexes.
This is an advanced feature that most BMC Remedy AR System administrators do not need. If you are an
experienced database administrator, you can use Database Administrator (DBA) extensions to manage database
space and improve overall system performance. For example, you can improve the speed of BMC Remedy AR
System response by specifying that separate devices store indexes and form tables.
To extend the SQL statement when forms and indexes are created, you must first create a configuration file. On
UNIX, create the ardb.conf file in your configuration directory. On Windows, create the ardb.cfg file in the conf
directory of your BMC Remedy AR System installation. For more information about the ardb file, see ardb.cfg or
ardb.conf.
Warning

BMC Remedy AR System does not verify that the SQL clauses specified in your ardb configuration file are
correct or safe. BMC Remedy AR System merely attaches the SQL clause to the statement used when a
form or index is created. Because you can append any SQL clause to the CREATE statement for a form or
index, use this feature with care.
When you create a form or index, BMC Remedy AR System references the ardb configuration file to append
clauses to the SQL statement. If it finds no matching information, BMC Remedy AR System creates the form or
index as it would normally. If it finds matching information, it appends the specified clause to the SQL statement
that creates the form or index.
When you change the name of a form in BMC Remedy Developer Studio, the ardb configuration file is edited
automatically to match the new name.
The following topics provide detailed information about how to tune the database performance by using SQL
statements:
CREATE statement syntax

When you create a form or index, BMC Remedy AR System references the ardb configuration file for clauses to
append. If it finds matching information, it appends the specified clause to the SQL statement that creates the
form or index.
BMC Remedy AR System appends the ardb configuration file clause to the CREATE TABLE statement as follows:
CREATE TABLE <tableName (columnDefinitions) ardbClause>
BMC Remedy AR System appends the ardb configuration file clause to the CREATE INDEX statement as follows:
CREATE INDEX <indexName> ON <tableName (columns) ardbClause>
Sample clauses for the ardb configuration file

Oracle example of the ardb configuration file
For an Oracle database, the clauses for the indexes instruct the database to leave 70 percent of each index free
for updates and insertions. In the following example, the tables for the HD-Answer form build on seg2:
Form:HD-Answer
Clause:TABLESPACE seg2
Index {
Id:2
Id:7
Clause:PCTFREE 70
}
Index {

Id:4
Clause:PCTFREE 70
}
DB2 example of the ardb configuration file

For a DB2 database, the clauses for the indexes instruct the database to leave 10 percent of each index free for
updates and insertions. In the following example, assuming that you have already created longts long tablespace,
only the long columns in the tables for the HD-Answer form build in longts:
Form:HD-Answer
Clause:IN userspace1 LONG IN longts
Index {
Id:1
Clause:PCTFREE 10
}
Sybase and Microsoft SQL Server example of the ardb configuration file
For a Sybase or Microsoft SQL Server database, the clauses for the indexes instruct both indexes to ignore
duplicate keys. To store the HD-Answer form on seg2, format the ardb configuration file as follows:
Form:HD-Answer
Clause:on seg2
Index {
Id:2
Id:7
Clause:with ignore_dup_key
}
Index {
Id:4
Clause:with ignore_dup_key
}
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.
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

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

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

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.
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. In the Backup Polling Interval field, enter a polling interval from 15 seconds to 7200 seconds (2 hours).
The corresponding entry in the BMC Remedy AR System server configuration file is DSO-Polling-Interval.
The interval takes effect immediately. You do not need to restart the BMC Remedy AR System server.
Tuning the Email Engine performance

The following topics provide information about how to tune the email engine performance:
Recommendation for using the SMTP timeout properties

If you use the email engine properties SMTPTimeout and SMTPTimeoutPeriod, you might encounter issues with
outgoing email messages.
After a timed out connection is restored, messages marked as Error (in the Send Message field) are not sent
consistently--some messages are sent successfully, while others are not. This seems to be a JavaMail issue (
SW00364840) for which we do not yet have a workaround.
To avoid facing this issue, you might want to refrain from using these properties until a solution is made available.
If you use the SMTPTimeout and SMTPTimeoutPeriod properties, BMC recommends the following configurations
to avoid encountering the issue:
Number of messages Value of SMTPTimeoutPeriod
40000 30 seconds
70000 60 seconds
100000 90 seconds
These settings can work properly with the maximum permissible number (20) of Sender threads. However, BMC
recommends using a value that is optimum for your configuration.
Configuring Email Engine for maximum performance

To get the maximum output with Email Engine, you should configure Email Engine as mentioned in the following
sections:

Comparative performance data for Email Engine 7.5.00, 7.6.03 (32-bit and 64-bit JVM), and 7.6.04 (32-bit
and 64-bit JVM)
The following parameters are used for Email Engine:
Outgoing Protocol: SMTP

Delete Outgoing Notifications = No
Mailbox Polling Interval = 10 seconds
Email Engine started with java Heap Size 1024m
The following are the other configuration details:
Incoming mailbox is configured, but Email Engine is not processing any incoming message.
All other Email Configuration and values of parameters in the EmailDaemon.properties file are default.
AR System server is having default configuration and processing only Email Engine requests.
Email Engine is installed remotely and AR System server is installed on a remote database.
Exchange server is handling only Email Engine requests. (There is no other load on the exchange server).
This setup is identical for both, 7.5.00, 7.6.03 (32-bit and 64-bit) and 7.6.04 (32-bit and 64-bit).
Hardware Configuration
Email Engine AR Server Database MS Exchange
Server 2007
System Windows Server 2008 R2 Enterprise Windows Server 2008 R2 Enterprise Windows Server 2008 R2 Enterprise Windows 2003
Server SP2
RAM 4 GB RAM 4 GB RAM 4 GB RAM 2 GB
CPU Intel(R) Xeon(R) E7430 2.13 Ghz 2.39 Intel(R) Xeon(R) E7430 2.13 Ghz 2.39 Intel(R) Xeon(R) E7430 2.13 Ghz 2.39 Intel CPU 3.40
Ghz (2 processor) Ghz (2 processor) Ghz (2 processor) GHz
Performance Data for Email Engine

Parameters Email Engine AR Server Email Engine AR Server Email Engine AR Server AR Server AR Server
7.5 7.5 7.6.03 (32-bit 7.6.03 (32-bit 7.6.03 (64-bit 7.6.03 (64-bit 7.6.04 (32-bit 7.6.04 (64-bit
Java) Java) Java) Java) Java) Java)
CPU Usage 33.81 19.16 13.34 4.39 17.57 10.88 4.39 10.88
Memory 2688.11 Not 2789 Not Captured 2806 Not Captured Not Captured Not Captured
Usage Captured
Handles 375 1202 386 1275 393 1268 1275 1268
Private 76528218.35 98548940.4 30204140 106866176 318464819 111933667 106866176 111933667

memory
Working Set 67887344.94 72324680 120396563 84094805 143367782 81932743 84094805 81932743
Total CPU 28.55 15.61 12.86 5 15.63 22500 5 22500
Message/Hour 18000 NA 26500 NA 5 NA NA NA

Note
All the above mentioned data is approximate.
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 See Configuring the approval server to work with flowcharts.
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 Manage the entries on approval forms regularly, such as once a month.
AP:Signature (Approval forms)
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);
BMC Atrium Core - Installing section
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.
10.5 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.
10.5.1 Checking system requirements and supported configurations

Consult the BMC Solution and Product Availability and Compatibility Utility for the following 8.1 product
compatibility and system configuration information:
AR System server hardware platforms and operating system support

AR System server database support
Java support
Mid tier web / application server, servlet engine, and browser support
BMC Developer Studio operating system and browser support
Virtual environment support
Screen reader support
Language offerings
BMC product compatibility
Changes in support from the previous release

The system requirements for BMC Remedy AR System also apply to BMC Remedy Approval Server, BMC Remedy
Email Engine, BMC Remedy Distributed Server Option (DSO), BMC Remedy Encryption Performance Security and
BMC Remedy Encryption Premium Security.
To access the compatibility matrixes
1. Navigate to http://www.bmc.com/support/product-availability-compatibility.
2. Click BMC Solution and Product Availability and Compatibility Utility .
3. In the Product Name field, enter or select the product name.
You can enter a partial name of a product and the utility autocompletes the name for you. For example,
Remedy.
4. In the Product Version field, enter the version number.

5. Review the compatibility information listed in the tabs at the bottom of the page.
Note
To access the product compatibility information on the Customer Support website, you must
have a Support login.

Known issues and incompatibilities

For known issues or potential incompatibilities between BMC products and products from other vendors, review
the compatibility matrixes.
Related topics
Hardware requirements
Software requirements
Deployment architecture
Known issues and workarounds
10.5.2 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 ITSM BMC Analytics for BSM BMC Dashboards for BSM Number of managed devices
(concurrent users) (concurrent users) (concurrent users)
Proof of concept (POC) 50 5 2 1,000 or fewer
Small 800 50 5 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

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 Service Request Management
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 2 2 5
System server servers: servers: servers:
2 CPU 4 CPU 4 CPU

Core Core Core
8 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
BMC Remedy AR System Web Services None: Services combined with AR 1 server: 1 server: 2
System server servers:
2 CPU 4 CPU
Core Core 4 CPU
8 GB 8 GB Core
RAM RAM 8 GB
60 GB 60 GB RAM
disk disk 60 GB
disk
SAP BusinessObjects Web Intelligence Reports Server (for BMC Analytics for None: Services combined with SAP 1 server: 1 server: 1 server:
BSM) CMS server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
BMC Remedy AR System server (user) 1 server: 2 2 5

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

BMC Service Level Management 12 GB RAM 2 CPU 4 CPU 4 CPU

BMC Service Request Management 250 GB disk Core Core Core
BMC Knowledge Management 8 GB 8 GB 8 GB
RAM RAM RAM
User-loaded servers 60 GB 60 GB 60 GB
disk disk disk
BMC Remedy AR System server (back end) 1 server: 2 2 2

RAM RAM RAM
Non-user-loaded servers for back-end AR System processes, integrations, 60 GB 60 GB 60 GB
reconciliation, notification disk disk disk
BMC Atrium Single Sign On None: Services combined with AR 1 server: 1 server: 1 server:
System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 4 GB 8 GB
RAM RAM RAM
100 GB 100 GB 100 GB
disk disk disk
BMC Dashboards for BSM Server (with DIL) None: Services combined with AR 1 server: 1 server: 1 server:
System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
100 GB 100 GB 200 GB
disk disk disk
SAP BusinessObjects CMS Server (for BMC Analytics for BSM) 1 server: 1 server: 1 server: 1 server:
2 CPU Core 2 CPU 4 CPU 4 CPU

4 GB RAM Core Core Core
60 GB disk 4 GB 8 GB 12 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
BMC Atrium Orchestrator Configuration Distribution Peer (CDP) and 1 server with (No HA): 2 2 2
HA-CDP servers: servers: servers:
4 CPU Core
8 GB RAM 2 CPU 4 CPU 4 CPU
100 GB disk Core Core Core
4 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk

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
Master BMC Remedy AR System Database 1 server: 1 cluster: 1 cluster: 1 cluster:

100 GB disk 8 GB RAM 16 GB 32 GB
200 GB RAM RAM
disk 200 GB 200 GB
disk disk
Replicated BMC Remedy AR System Database for None: Services combined with AR System database 1 server: 1 server: 1 server:
Reporting
8 CPU 16 CPU 32 CPU
Core Core Core
8 GB RAM 16 GB 32 GB
200 GB RAM RAM
disk 200 GB 200 GB
disk disk
BMC Atrium Orchestrator Database None: Services combined with BMC Atrium 1 cluster: 1 cluster: 1 cluster:
Orchestrator CDP
2 CPU 4 CPU 8 CPU
Core Core Core
8 GB RAM 8 GB RAM 16 GB RAM
200 GB 200 GB 200 GB
disk disk
10.5.3 Software requirements

For BMC Remedy 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 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 Web Java Mail

AR System app Runtime server
server* Environment
(JRE)
Email Engine Yes Yes Yes
Flashboards Yes Yes Yes
Mid tier Yes Yes Yes
Clients 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 Checking system requirements and supported
configurations.

10.5.4 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 Checking system requirements and supported configurations.
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 32-bit JVM if using
the MAPI protocol.
You can specify these exceptions in the installer if required for your installation.
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.
10.5.5 Unicode requirements

This following topics help you plan for a Unicode implementation on BMC Remedy AR System:
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).
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.
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
BMC Remedy Assignment Engine
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.

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.
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 UTF-16 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.
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

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.
Unicode support for AR System database types

Each database type supported by BMC Remedy AR System supports Unicode at one of the levels listed in the
following table.
Unicode support for AR System database types
Unicode Database Comments

support type
level
Database Sybase, For these database types, you must configure the database instance before you install the new AR System database.
instance Oracle
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 Microsoft Uses Unicode data types nchar, nvarchar, and ntext.
column SQL
type Server
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.
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
Migrating an Oracle database to Unicode

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.
Migrating a Microsoft SQL Server database to Unicode

To migrate a Microsoft SQL Server database, follow these general steps. For detailed information, see your
Microsoft SQL Server documentation.
1.
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.
Migrating a DB2 database to Unicode

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.
Migrating a Sybase database 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.
10.5.6 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.
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.
10.5.7 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.

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.
10.6 Security
The following topics contain information and instructions on BMC Remedy Action Request System security
planning:
10.6.1 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

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.
You can use a secure socket layer (SSL) to encrypt the traffic between the HTTP web server and the browser
client. Enabling SSL can impact performance due to the extra overhead required to encrypt and decrypt on both
ends.
Note
You can now log on to BMC Remedy Mid Tier using only HTTP POST requests. Available only in Service
Pack 1 for version 8.1.00 and later versions.
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
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.
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.
Security assessments
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
BMC Remedy Encryption Security options
Security policy impact on client-server communication
BMC Remedy Encryption Security compatibility
Upgrading encryption security
Configuring BMC Remedy 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.

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.
10.6.2 General security guidelines

This topic presents security guidelines to consider when using BMC Remedy Action Request System (BMC
Remedy AR System).
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 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 140-2 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.
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).
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
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.
Available only in Service Pack 1 for version 8.1.00 and later versions.
Related topic
Cookies used by BMC Remedy Mid Tier
10.6.3 BMC Remedy Encryption Security options

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.
10.6.4 Security policy impact on client-server communication

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 Security 8.1 client with encryption 8.1 client 5.1.2 -7.1.00 client with 5.1.2 -7.1.00 Pre-5.1.2
version policy without encryption client without client
encryption encryption
8.1 Optional (Default) Encrypted if client Unencrypted (Default) Encrypted if client Unencrypted Unencrypted
encryp-tion level matches server encryp-tion level matches server
configuration OR Unencrypted 1 configuration OR Unencrypted 1
Required (Default) Encrypted if client None (Default) Encrypted if client None None
(FIPS not encryp-tion level matches server encryp-tion level matches server
enabled 2) configuration OR None configuration OR None
Required (Default) Encrypted if client None None None None

(FIPS encryp-tion level matches server
enabled 2) configuration OR None
Disabled Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted

5.1.2-7.1.00 Optional (Default) Encrypted if client Unencrypted (Default) Encrypted if client Unencrypted Unencrypted
configuration OR Unencrypted 1 configuration OR Unencrypted 1
Required (Default) Encrypted if client None (Default) Encrypted if client None None
configuration OR None configuration OR None
Disabled Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted
Pre-5.1.2 NA Unencrypted Unencrypted Unencrypted Unencrypted Unencrypted
1 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 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.
10.6.5 BMC Remedy Encryption Security compatibility

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 Checking system requirements and
supported configurations.
10.6.6 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)
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.
10.6.7 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.

10.6.8 Single sign-on authentication systems integration

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
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 Sign on process automation is manifest via entry of a user name and password. Scripts are stored on a special authentication
automation 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 Many vendors sell complementary centralized security administration tools that use agents on the target systems to enable
Security central setup and termination of accounts. These tools allow role-based administration of user accounts, often storing account
Administration and privilege information in a centralized directory. In some cases these administration tools are completely separate, in others
they are more tightly integrated.
Token-based When the user is identified, the service creates a non-forgeable, non-reusable token to identify the user to authorized resources.
authentication
Certificate-based Certificate-based authentication is centralized, role-based administration of user privileges across several resources.The SSO
authentication 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
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 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.
library 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.

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

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:
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. 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:
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
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
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:
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.
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 m_bARUsingPreferenceServer;
int 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 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;
};
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;
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
* 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:
Multiple authentication methods

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
Value Required Description
User name Y Identifies the user
Password N Validates the user
Authentication string N 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 The AR System server authenticates users based on information provided via the User form. BMC does not recommend using an
User form 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 The LDAP AREA Packaged Plug-in authenticates AR System users against external LDAP directory services.
AREA
Packaged
Plug-in 1
Custom Create a custom plug-in with the authentication logic built in, to integrate AR System with external authentication services.
AREA
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
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.
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.
Note

This feature is limited, especially when using OS authentication. Users cannot be assigned groups or
licenses.
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:
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
5. Use the Authentication Chaining Mode list to choose from the options described in the following table.
Authentication-Chaining-Mode values

5.
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 0
settings of other configuration options).
Use AR System internal authentication first, then use external authentication via the AREA plug-in. 1
Use external authentication via the AREA plug-in first, then use AR System internal authentication. 2
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.
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
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 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.

10.6.9 Security assessments

This topic highlights the IBM Rational AppScan automated assessment process for web application security that
BMC implements for the BMC Remedy AR System. It also provides a list of security protections that BMC provides
to mitigate against vulnerabilities outlined in the Open Web Application Security Project (OWASP) Top Ten list.
Note
The IT environment and network infrastructure in which your 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 AR System architecture is multi-tiered; it consists of a Presentation layer, a Logic layer, and a Data layer as
shown here.
AR System security architecture diagram

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 Checking system requirements and supported configurations).
Logic layer
The Logic layer includes instances of a mid tier, a JavaServer Pages (JSP) engine, a web server, and the 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 AR System server, handles web service
requests, and runs server-side processes that present AR System functionality to the client from the AR System
server. The server executes workflow and business logic that define all AR System applications. Because all 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 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.
AppScan test results

BMC uses IBM Rational AppScan, a Web 2.0 security assessment tool, as an integrated part of the software
development life cycle (SDLC). By performing a wide range of early detection testing, BMC identifies and fixes or
mitigates vulnerabilities before they become security risks.
AppScan provides issue severity levels and detailed descriptions as well as advisories and issue solution
recommendations for potential security risks related to AR System components. BMC uses this data to investigate
and proactively resolve security issues. See the Security section for information about securing your system.
A sample AppScan results page is shown here.
Sample AppScan test result window
This table lists the AppScan version 7.8 test results. No high-severity vulnerabilities were detected in the current
version of the AR System mid tier.
AppScan test result details
AR System Servlet Test Result
AdminServlet No vulnerabilities were detected.
ApplicationServlet False vulnerabilities were detected. To issue an identical error message for every false login attempt, set the
Display-General-Auth-Message flag in the ar.cfg file. Setting this flag ensures that the same message is
returned to the mid tier client, enabling the client to display it to the user.
ApplictionSevletWithLoginParameter No vulnerabilities were detected.
arsys No vulnerabilities were detected.
AttachServlet

False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
session id, jsession id, is created by Tomcat and changed after user authentication. A new session is
created for the authenticated user.
BackChannelServlet No vulnerabilities were detected.
BMCBorderServlet No vulnerabilities were detected.
BOViewerServlet No vulnerabilities were detected.
download No vulnerabilities were detected.
EngineServlet No vulnerabilities were detected.
FBImageServlet False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
created for the authenticated user. Also, to issue an identical error message for every false login attempt, set
the Display-General-Auth-Message flag in the ar.cfg file. Setting this flag ensures that the same message
is returned to the mid tier client, enabling the client to display it to the user.
FlashboardPlugin False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
forms No vulnerabilities were detected.
HomeServlet No vulnerabilities were detected.
Imagepool No vulnerabilities were detected.
ImageServlet No vulnerabilities were detected.
LicenseReleaseServlet No vulnerabilities were detected.
LoginServletWithParameter No vulnerabilities were detected.
LoginServlet No vulnerabilities were detected.
LogoutServlet No vulnerabilities were detected.
NotFoundServlet No vulnerabilities were detected.
OverrideServlet False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
PluginEventServlet No vulnerabilities were detected.
preview No vulnerabilities were detected.
ProtectedWSDLServlet No vulnerabilities were detected.
PublicApplicationServlet No vulnerabilities were detected.
PublicWSDLServlet No vulnerabilities were detected.
RedirToFedSrvServlet No vulnerabilities were detected.
ReportPlugin

False vulnerabilities were detected. To issue an identical error message for every false login attempt, set the
ReportPluginWithReportName False vulnerabilities were detected. To issue an identical error message for every false login attempt, set the
ReportSetupServlet No vulnerabilities were detected.
ResourceServlet No vulnerabilities were detected.
SetupServlet No vulnerabilities were detected.
SharedLogin No vulnerabilities were detected.
SharedResourceServelet No vulnerabilities were detected.
UTF8Encoder No vulnerabilities were detected.
ViewerFilter No vulnerabilities were detected.
ViewFormServletPOST False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
ViewFormServletQuery False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
ViewFormServletSubmit No vulnerabilities were detected.
ViewFormServletSubmitWith False vulnerabilities were detected. AR System does not accept externally created session identifiers. The
Parameter session id, jsession id, is created by Tomcat and changed after user authentication. A new session is
WebcontentBirt False vulnerabilities were detected. To issue an identical error message for every false login attempt, set the
WebSvcEncryptor No vulnerabilities were detected.
OWASP Top Ten: AR System protections

Using AppScan, BMC specifically tests for vulnerabilities identified in the Open Web Application Security Project
(OWASP) Top Ten list. Security risks identified by OWASP and AR System protections are listed and described in
the following table.
AR System protections against the OWASP Top Ten
Sample risk OWASP description AR System protections
Injection Attackers trick a process into calling external processes of their choice by
injecting control-plane data into the data plane. Command injection has
two forms:

An attacker changes the command that the program executes, To prevent command injection, AR System disables
explicitly redefining the command. server-side scripting.
An attacker changes the environment in which the command To prevent JavaScript and SQL injection, AR
executes, implicitly redefining the command. System:
Encloses all dates in quotes and escapes all

quotes.
Uses filters for escape characters.
Provides strong-types and user-supplied
fields.
Checks for type constraints.
To prevent blind SQL injection, AR System

properly filters escape characters.
Secures variables with strong types and
validation.
Sets security privileges on the database to
least required.
Cross-Site Attackers can make a single request to a vulnerable server that causes the All user-supplied HTML special characters are
Scripting (XSS) server to create two responses. The second response might be encoded into character entities, thereby preventing
misinterpreted as a response to a different request, possibly one made by them from being interpreted as HTML.
another user sharing the same TCP connection with the server.
Broken Attackers can bypass authentication mechanisms if credentials do not All requests contain credentials. The mid tier does
Authentication accompany every request. not use cookies. It uses a cache ID in the URL and
and Session controls the user role (such as the Admin role.)
Management AR System uses web server session management to
store AR System authentication into the HTTPS
session.
Insecure Direct Attackers force the return of sensitive information instead of non-sensitive All object references are subject to permissions
Object information that would be returned normally. enforced by the AR System server.
References
Cross-Site Using this technique, attackers make victims perform actions that they did The AR System disables web server scripting in the
Request Forgery not intend to, such as logging out, purchasing items, or other functions mid tier.
(CSRF) provided by the vulnerable website. The victim's browser is tricked into In addition, logic that runs processes on the AR
issuing a command to a vulnerable web application. System server is restricted by the AR System
The vulnerability is caused by browsers automatically including user permissions model, and processes that may be run
authentication data such as a session ID, IP address, or Microsoft Windows are restricted to specific directories on the server.
domain credentials with each request.
Security This attack involves exploiting insecure configurations. AR System configuration guidelines ensure secure
Misconfiguration operation. For example, AR System restricts user
access to directories required for user operations,
and AR System validates all user input.
Insecure The most common flaw in this area is simply not encrypting data that All sensitive data is encrypted within AR System.
Cryptographic deserves encryption. All communication between the web browser and
Storage When encryption is employed, unsafe key generation, non-rotating keys, the web server can be encrypted using HTTPS.
and weak algorithm usage is common. The use of weak or unsalted All communication between the web server and the
hashes to protect passwords is also common. External attackers have AR System server can be encrypted using API
difficulty detecting such flaws due to limited access. encryption.

Failure to Attackers may access pages beyond the login page without authorization. All access to all AR System pages require
Restrict URL authorization from the AR System server.
Access
Insufficient Attackers may intercept unprotected network traffic if only SSL or TLS is AR System uses transport layer security and digital
Transport Layer used during authentication. signatures to perform end-to-end validation after a
Protection connection is made to an endpoint.
FIPS-compliant Performance and Premium
Encryption add-on components are provided for
additional cryptographic protection among AR
System components.
Unvalidated Applications frequently redirect users to other pages, or use internal All AR System parameters are validated and
Redirects and forwards in a similar manner. Sometimes the target page is specified in an authenticated against user credentials.
Forwards unvalidated parameter, allowing attackers to choose the destination page.
10.7 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:
10.7.1 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
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

Estonian and Croatian

French and Polish
Simplified Chinese and Traditional Chinese
10.7.2 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
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.
10.7.3 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.

10.7.4 BMC Remedy Email Engine internationalization support

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.
10.8 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:
10.8.1 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
10.8.2 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.

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 Checking system
requirements and supported configurations 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
10.9 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 128-bit 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:

10.9.1 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.
10.9.2 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.
10.9.3 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
10.9.4 Supported database clients for IPv6

BMC Remedy AR System supports the following minimum database clients for IPv6:
Oracle 11g R2
IBM DB2 9.7
10.9.5 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.
10.9.6 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.

11 Installing
Use the following topics to guide you through installing BMC Remedy AR System or the BMC Remedy ITSM Suite.
Goal Instructions
Prepare your environment to install BMC Remedy AR System and the BMC Remedy IT Service Management Suite. Preparing for
installation
Run a new installation of BMC Remedy AR System. Performing a new

For information about the solution-based installer that installs the BMC Remedy AR System server and its components installation
and ITSM applications on one server, see Installing the BMC Remedy ITSM Suite Preconfigured Stack (This takes you to
the BMC Remedy ITSM wiki space.)
Install two or more servers in a server group. Installing a server group
Perform other AR System installations, including: Performing other

installations
Using the silent installer
Configuring your web server and installing BMC Remedy Mid Tier with a .war file
Remotely installing or upgrading Email Engine
Remotely installing or upgrading Flashboards
Installing SSO with the AR System server and mid tier
Installing a stand-alone BMC Atrium Integrator engine for BMC Remedy AR System
Installing multiple instances of BMC Remedy AR System on one computer
Perform post-installation procedures to finalize your installation. Post-installation

procedures
Uninstall BMC Remedy AR System features and clients, such as the mid tier and encryption. Uninstalling BMC
Remedy AR System
features and clients
See the following video for an overview about installing BMC Remedy AR System.
Watch video on YouTube at http://www.youtube.com/watch?v=aHVZsBZUzSw

11.1 Preparing for installation

Review or perform the following sections before you start installing.
11.1.1 Installation process overview

This topic describes the general installation process required to install BMC Remedy AR System.
Important
Before beginning your installation, review the Planning topics.
Prepare to install
Step Task
1 Review the BMC Remedy AR System and BMC Atrium compatibility matrix for the latest, most complete information about platforms currently
supported by BMC Remedy and BMC Atrium products.
Note
To access this information, you must log in with your BMC support login and password.
2 Review the requirements for your computer platform:

a. Review the hardware requirements for your computer platform.
b. Review the software requirements for your computer platform.
c. Review the 32-bit and 64-bit requirements for your computer.
3 Prepare your database before you start the installation.
4 Obtain licenses for BMC AR System Server and other BMC products.
5 Complete the MS Excel planning spreadsheet.
6 Download the installation files.
7 Prepare your environment to install.
8 Prepare your components and applications.
Run the BMC Remedy AR System installer

Step Task
9 Run the AR System installation to install the AR System server and other features.
10 Back up the BMC Remedy AR System database. This enables you to restore BMC Remedy AR System to its pre-installation state if you
encounter problems.
Note
The product workflow is installed in overwrite mode.
11 Run the AR System installation to install BMC Remedy Mid Tier.
12 Run the AR System installation to install the AR System Clients.
13 Perform the AR System post-installation procedures.
11.1.2 Reviewing the compatibility matrix


Java support
Language offerings
3.

Remedy.

Note

Where to go from here

Reviewing the requirements
11.1.3 Reviewing the requirements

This section includes information about the hardware and software requirements for installing BMC Remedy AR
System. It also includes information about 32-bit and 64-bit requirements.
This information is critical when you are installing other BMC applications (for example, BMC Atrium Core and
BMC IT Service Management).

Downloading the installation files

AR System hardware requirements

Medium 2000 100 10 10,000 or fewer
Large 5000 250 50 30,000 or fewer

Note

2 CPU 4 CPU 4 CPU

Core Core Core
8 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
2 CPU 4 CPU
Core Core 4 CPU
8 GB 8 GB Core
RAM RAM 8 GB
60 GB 60 GB RAM
disk disk 60 GB
disk
BSM) CMS server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk

RAM RAM RAM
disk disk disk


RAM RAM RAM

System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 4 GB 8 GB
RAM RAM RAM
100 GB 100 GB 100 GB
disk disk disk
System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
100 GB 100 GB 200 GB
disk disk disk

RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
4 CPU Core
4 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
AR System software requirements

IBM DB2
Oracle
Sybase
Note


server* Environment
(JRE)
Clients Yes Yes
Developer Studio
Note
configurations.
32-bit and 64-bit requirements for your OS

releases.
Note

Important

Note
Plug-ins
Java requirement

the MAPI protocol.
Note
64-bit computer.
11.1.4 Downloading the installation files

This topic explains how to obtain the files that you need for installation from the BMC Electronic Product
Distribution (EPD) site. To understand which files you are entitled to download based on the licenses that you
purchased, see License overview. This topic contains the following sections:
Downloading the files
Note
When viewing a product suite's latest version in EPD, you see only the components (including licensed
add-ons) that are covered under the licenses associated with your Support ID or EPD profile.
The installation program includes the latest service packs and patches. If you just installed the product for the first
time, you do not need to apply service packs or patches before you begin using the product. When new service
packs and patches are released, you will perform an upgrade of the product to apply the latest changes. You can
find information about service packs and patches under What's new.
1. Create a directory in which to place the downloaded files.
Note
On Microsoft Windows computers, ensure that the directory is only one level into the directory
structure. The EPD package creates a directory in the temporary directory when you extract the
files, and the directory that contains the installation image should not be in a directory deeper
than two levels into the directory structure.
2.
2. Go to http://www.bmc.com/available/epd.html.
3. At the logon prompt, enter your user ID and password, and click Submit.
4. On the Export Compliance and Access Terms page, provide the required information, agree to the terms of
the agreements, and click Continue.
5. If you are accessing this site for the first time, create an EPD profile to specify the languages and platforms
that you want to see, per the EPD site help; otherwise, skip to step 6.
6. Verify that the correct profile is displayed for your download purpose, and perform one of the following
actions:
If you are downloading files for a product installation, select the Licensed Products tab.
If you are downloading files for a service pack or patch, select the Product Patches tab.
7. Locate the BMC Remedy IT Service Management Suite.
8. Locate the version you are installing, such as BMC Remedy IT Service Management Suite 8.1, and expand its
entries.
9. Select the check boxes next to the installation files, documentation, and (if available) associated
prerequisites and technical bulletins, that you need to download. For example: BMC Remedy AR System
Server to show the available versions.
10. Click Download (FTP) or Download Manager:
Download (FTP) places the selected items in an FTP directory, and the credentials and FTP
instructions are sent to you in an email message.
Download Manager enables you to download multiple files consecutively and to resume an
interrupted download if the connection drops.
This method requires a one-time installation of the Akamai NetSession client program on the target
computer and is usually the faster and more reliable way to transfer files. A checksum operation is
used to verify file integrity automatically.
Enabling search in the offline documentation

The Offline Documentation - productName version zip file contains an archived version of the online
documentation. For the latest and most comprehensive content, see the BMC Online Technical Documentation
Portal.
To enable search in the offline documentation

Deploy the offline documentation on a web server by using one of the following methods:
If this is the first BMC offline documentation archive that you are installing on the web server, extract the
zip file to the web application deployment folder of your web container (servlet container).
For example, with an Apache Tomcat web server, extract the zip file to
<TomcatInstallationDirectory>\webapps.
If at least one BMC offline documentation archive is already installed on the web server, perform the
following steps:
1. Extract the zip file to your hard drive.
2. Open the extracted localhelp folder.
3.
3. Copy only the productName version folder and the productName version.map.txt file to the
localhelp folder of your web container (servlet container).
For example, if you are deploying BMC Asset Management 8.1 documentation to an Apache Tomcat
web server, copy the asset81 folder and the BMC Asset Management 8.1.map.txt file to
<TomcatInstallationDirectory>\webapps\localhelp. Do not include the other folders and file.
To view the offline documentation in a browser

Type the following URL:
http://<servletName>:<portNumber>/localhelp/<extractedDocumentationFolder>/Home.html
For example: http://SanJoseTomcat:8080/localhelp/ars81/Home.html

Preparing your database
11.1.5 Preparing your database

Before you install the BMC Remedy AR System server, prepare your database correctly, as described in the
following topics:
To avoid a decline in the BMC Remedy AR System server performance, BMC recommends the following:
Do not use a firewall between the AR System server and database tiers. This can impact performance
significantly.
When possible, set up a high-speed backbone between the AR System server and the database server.
If using Ethernet, install the BMC Remedy AR System server and the database server on a separate switched
network that is isolated from other network traffic.
Avoid putting a wide-area network between the AR System server and the database server.
Make sure that each network device between the AR System server and the database server is
communicating at the maximum bandwidth.
If you are planning to install CMDB or ITSM applications in addition to BMC Remedy AR System, the
following minimum space is required:
2 GB for the data file
1 GB for log and temp files
When installing more than one ITSM application, add 2 GB to the data file and 100 MB to the log file
size for each additional application. BMC recommends at least 2 GB of disk space for the database.
Depending on the number of records your system handles and the specific type of database you are
using, however, you might need more than this. If you do not have 2 GB or more before beginning
the installation, you might run out of free space during installation. As the transaction log fills up, the
BMC Remedy AR System suspends operation. When the transaction log is completely full, the BMC
Remedy AR System writes a message to the BMC Remedy AR System error log and the installation
terminates.

Note
In BMC Remedy AR System 8.1, the installer displays a warning message indicating
the required space for additional installation of CMDB or ITSM applications.
If the transaction log fills during the installation and the installation fails, clear the
transaction log, and then increase the size of the transaction log before reinstalling
the product.
Note
A common issue is that a router's Auto Negotiate option can incorrectly set the router to 10 MB Half
Duplex. NICs, routers, and other network devices then agree on the fastest speed to communicate
together, but that speed is usually too slow. To remove this variable, if all the network devices can
communicate at 1 GB Full Duplex, set them as such, and disable the Auto Negotiate option on the router.
For technical assistance on installing your database, contact the database vendor.

Obtaining BMC Remedy license keys
Preparing to install on a Unicode database

This topic contains the following material:
Before you begin

To prepare your host computer for a Unicode BMC Remedy AR System installation or upgrade
To upgrade BMC Remedy AR System 6.3 and later servers with a Unicode database to BMC Remedy AR
System 7.0.01 and later
Before you begin

If you are installing BMC Remedy AR System for the first time and you want to use Unicode, make sure your
database is configured to use Unicode.
Warning
Each database client library has special mechanisms for specifying the codeset in which database clients
attempt to communicate with the AR System server. If these mechanisms specify a codeset that is not
consistent with the codeset that the AR System server and upgrade programs expect, errors and data
corruption can occur. The following procedure can help you avoid this problem.

Note
If you are installing the Russian version of the BMC Remedy ITSM applications, ensure that you are using
a non-unicode database. The Russian version does not support unicode. The installed Russian version
cannot coexist with other installed language versions with the exception of the English version.
To prepare your host computer for a Unicode BMC Remedy AR System installation or upgrade
1. (UNIX only) Set the LANG environment variable for the locale you will be using.
Make sure you have installed UTF-8 locales in which you plan to run BMC Remedy AR System
programs.
Make sure you use the correct spelling and capitalization for your particular system (for example, on
Solaris, you might enter en_US.UTF-8 ). To find the locales that correspond to the language you
want to use, use the locale -a command. See your UNIX system documentation for information
about locale settings.
To set the locale of the installation, the server installation script uses the locale of the shell it is run
from. For example, to install a server on Solaris that runs in the en_US.UTF-8 (U.S. English,
Unicode/UTF-8 character encoding) locale, set your shell's locale by setting the environment
variables LANG and LC_ALL to en_US.UTF-8 before installing BMC Remedy AR System.
During installation, the BMC Remedy AR System installer sets up the arsystem script with the correct
values for LANG variable. The arsystem script launches armonitor, which launches the programs
mentioned in the armonitor.conf file; each of these programs inherits the environment variables
established in the arsystem script.
2. (Oracle only) If you are installing an Oracle Unicode BMC Remedy AR System on a Microsoft Windows
operating system, set the value of the NLS_LANG registry setting.
Depending on your system's configuration, the setting's key looks similar to the following:
HKEY_LOCAL_MACHINE\SOFTWARE\ORACLE\KEY_oracle_home_name\NLS_LANG
Oracle defines the NLS_LANG value as LANGUAGE_TERRITORY.CHARACTERSET, for example,

AMERICAN_AMERICA.AL32UTF8.
The CHARACTERSET value AL32UTF8 tells the Oracle client library to send and receive character data as
UTF-8. (Do not use the CHARACTERSET value UTF8, which is obsolete.)
This setting affects all Oracle database clients that use the Oracle installation named by
oracle_home_name.
a. Verify that the NLS_LANG environment variable is set correctly.
b. Set the NLS_LENGTH_SEMANTICS=BYTE initialization parameter on the Oracle database instance.
Although the BMC Remedy AR System server enables you to request that character fields be
measured in characters, the server still communicates with the database in bytes.
For more information, see Oracle Metalink Note 144808.1, "Examples and limits of BYTE and CHAR
semantics usage."

Warning
BMC Remedy AR System does not support the CHAR setting. If your database administrator
(DBA) changes NLS_LENGTH_SEMANTICS value from BYTE to CHAR when reconfiguring
NLS_INSTANCE_PARAMETERS, the data in the AR System server will be corrupted. The
NLS_LENGTH_SEMANTICS parameter must be set to BYTE in
NLS_INSTANCE_PARAMETERS when the Oracle database server is started.
3. (IBM DB2 only) Set the DB2CODEPAGE setting.

The DB2CODEPAGE environment variable setting determines the client codeset. If the environment
variable is not set, the DB2 client library derives a DB2CODEPAGE value from the current locale. On UNIX
systems, this value is valid if the server or upgrade program has been started in a UTF-8 locale. On
Windows systems, you must explicitly set the environment variable to start the server correctly.
Use the following syntax to set the DB2CODEPAGE environment variable.
UNIX /bin/sh file: DB2CODEPAGE=1208; export DB2CODEPAGE
UNIX /bin/csh file: setenv DB2CODEPAGE 1208
Windows batch file (if starting the server manually): set DB2CODEPAGE=1208
You can use the Windows Control Panel to set the environment variable globally or set it for a
specific user.
Note
Sybase determines its client character set from the locale set by the LANG environment variable.
Microsoft SQL Server is a Unicode database, so you do not need to perform any steps to set it up.
To upgrade BMC Remedy AR System 6.3 and later servers with a Unicode database to BMC
Remedy AR System 7.0.01 and later
1. Back up the database components, objects, forms, and data.

2. On Windows systems, run the installer in the same locale that you ran the original BMC Remedy AR System
server.
For example, if the original server ran in a Japanese locale, run the upgrade installer in the same Japanese
locale.
3. On UNIX systems, run the installer in the Unicode version of the locale in which you ran the original AR
System server.
For example, if the server ran in the ja_JP.eucJP locale, run the installer in the ja_JP.UTF-8 locale. Locale
names vary across UNIX variants and versions.


Preparing your Microsoft SQL Server database before you install the AR System
server
This section describes the steps you should perform with your Microsoft SQL Server database when you install
BMC Remedy AR System or any application in the BMC Remedy IT Service Management Suite.
Tips to remember
To prepare your Microsoft SQL Server database
To optimize Microsoft SQL Server 2005 (or later) after you finish installing or upgrading the AR System
server
Windows Authentication mode and Microsoft SQL Server
To pre-create a Microsoft SQL Server database
Tips to remember
Purge the transaction log frequently to prevent it from filling up during installation.
Back up the SQL Server log files, and then change the SQL Server Transaction Logging mode from FULL to
SIMPLE.
If the database is not configured to extend automatically, make sure that you have set the following:
Set the BMC Remedy AR System data file size to 1 GB or greater; BMC Software recommends at least
2 GB. If you are planning to install CMDB or ITSM applications in addition to BMC Remedy AR
System, add 2048 MB to the data file for each additional application.
Set the log file size to 1 GB or greater. If you plan to install CMDB or ITSM applications in addition to
BMC Remedy AR System, add 2048 MB to the data file for each additional application.
Note
BMC recommends that you set the value of the Next-ID-Block-Size: Server option in the
ar.cfg or ar.conf file to 100.
1. Install the Microsoft SQL Server database.

You can install the SQL Server database on the same computer where BMC Remedy AR System is installed,
or on a remote server that is networked to the computer where you plan to install BMC Remedy AR
System.
2. Install SQL Server clients (that is, the drivers).
For remote installations, install the SQL Server clients on the same computer as the BMC Remedy AR
System server.
3. Create an instance of the database.
4. Set your SQL Server connections to allow TCP/IP:
a. Open the SQL Server Configuration Manager.
b.
4.
b. Click Network Configuration for your SQL Server instance.

c. Make sure that TCP/IP Protocol is enabled.
d. View the TCP/IP Properties dialog box for your database instance, and make sure that the IP
Addresses tab has a TCP Port number specified. (The default port is 1433.)
e. Restart all SQL Server services to effect this change.
5. Determine data file and log file sizes for your SQL Server database.
Note
During the installation, you are required to declare table sizes. This enables you to pre-size the
data files to improve application performance.
6. Make sure that your database can accept network communication with the parameters entered in the
installation.
The network communication will use ODBC and be able to recognize your ODBC data source.
To optimize Microsoft SQL Server 2005 (or later) after you finish installing or upgrading the AR
System server
Important
Perform these tasks immediately after you complete the AR System server installation or upgrade and
before you install any other BMC applications (for example, BMC Atrium Core).
If you are using Microsoft SQL Server 2005, make sure you have installed the most current Service Pack.
1. Stop the AR System server to ensure that all connections to the AR System database are closed.
2. (For a server group or a shared database) Stop all the AR System instances.
3. Set the following SQL Server forced parameterization and SNAPSHOT isolation parameters:
ALTER DATABASE ARSystem SET PARAMETERIZATION FORCED
ALTER DATABASE ARSystem SET READ_COMMITTED_SNAPSHOT ON
For example:
alter database ARSystem set recovery simple;

alter database ARSystem set single_user with Rollback immediate;
alter database ARSystem set READ_COMMITTED_SNAPSHOT ON;
alter database ARSystem set multi_user;
alter database ARSystem set PARAMETERIZATION FORCED;
4. Verify the values by issuing the following command:

SELECT is_read_committed_snapshot_on FROM sys.databases where name = 'ARSystem'


Microsoft SQL Server installation can support two authentication modes:
Windows authentication mode

Mixed authentication mode
To find the supported authentication mode in your SQL Server environment, connect to the SQL Server instance
from Management Studio > Server Properties > Security.
If only Windows authentication mode is supported, choose Windows authentication when you install the BMC
If mixed authentication mode is supported, choose Windows authentication or SQL Server authentication when
you install the BMC Remedy AR System server.

If you do not have DBA privileges, your database administrator must create an empty database so that you are not
asked for database information during the installation.
Note
Create the folder (for example, c:\data, before you pre-create the database. Otherwise, the database
creation fails.
1. In a Query Window, run the following command:
use tempdb
2. Create a database, for example:
CREATE DATABASE "ARSystem" ON (NAME = "ARSystem_data", FILENAME = 'c:\data\ARSys.mdf', SIZ
CREATE LOGIN "ARAdmin"WITH PASSWORD = 'AR#Admin#', DEFAULT_DATABASE = ARSystem
3. Use the created database, for example:
use ARSystem
4. Create a user name and login, for example:
CREATE USER "ARAdmin" FOR LOGIN "ARAdmin"
5. Make the user the db_owner, for example:
sp_addrolemember 'db_owner', 'ARAdmin'

Related topics
Using Microsoft SQL Server with BMC Remedy AR System

Preparing your Oracle database before you install the AR System server
This section describes the steps you should perform with your Oracle database before you install BMC Remedy
AR System or any application in the BMC Remedy IT Service Management Suite.
To prepare your Oracle database

Setting up a previously created tablespace
To use a previously created tablespace in BMC Remedy AR System
Typically, Oracle database administrators create instances, directories, and groups, and they install the Oracle
database and Oracle client before proceeding with the BMC Remedy AR System installation.
BMC highly recommends that you review Performance tuning for BSM for other recommendations
about tuning your Oracle database in preparation for performing this upgrade. This section includes
recommendations for:
Small, medium, or large Oracle databases

Cursor sharing
CLOB storage
Case-insensitivity
Diagnostics
1. Install at least one instance of the Oracle database. (Only your database administrator can create database
instances.)
You can install it on the same computer where the BMC Remedy AR System is installed, or on a remote
server that is networked to the computer where you plan to install BMC Remedy AR System.
2. Install Oracle clients on the AR System server.
When you are using a remote Oracle database, make sure that you install the Oracle client type as
Administrator on the AR System server. Additionally, make sure that the installation includes Oracle utilities
such as import tools (imp).
3. (UNIX only) Make sure that the administrator who is installing BMC Remedy AR System is a part of the
database group.
4.
4. Enable the TCP/IP Protocol for the database.

5. Confirm connection to your Oracle database.
Contact your database administrator for more information.
6. For remote installations, install and configure the Oracle client on the same system where you will install
7. Set the BMC Remedy AR System data file size to at least 2 GB.
Note
For each additional product, add at least 2 GB to the data file size.
8. Confirm that these database parameters are set.

9. Set the tablespace CanGrow parameter to YES.
10. To prevent BMC Remedy AR System from reaching the size limit of the database, set your tablespaces to
auto-extend by executing the following SQL statement as the system user:
ALTER DATABASE DATAFILE '<OracleHome>/DATABASE/ARSYS' AUTOEXTEND ON NEXT 100M MAXSIZE UNLI
11. Set the table space and temporary table space to at least the following minimum settings:
Parameter Suggested value
arsys 2000
artmpf 500
These tablespace names may be different depending on your environment.

12. To avoid time-out errors during installation, set the System Global Area (SGA) minimum size to at least 1 GB
(small database), 3 GB (medium database), or 6 GB (large database).
For Oracle 10g or 11g, BMC Software recommends setting the maximum SGA size and enabling the
database to automatically manage the internal memory structures of the SGA.
For example, to change the SGA size to 1 GB, use the alter system set sga_target=1G scope=both
command.
13. Verify or set the following environment variables.
Environment Description
variable
NLS_LANG Specifies globalization settings. For information about NLS_LANG and its usage, see the following notes from Oracle:
(Windows) 144808.1, 227330.1, 260192.1. If you are using the Oracle Instant Client, see step 14.
LANG (UNIX) Specifies globalization settings.
ORACLE_HOME Points to the directory where the Oracle client is installed. Use this value: $<ORACLEHOMEDirectoryPath>
Note
The installer accepts the ORACLE_HOME path as a user input on UNIX.

variable
If you are using the Oracle Instant Client, see step 14.
PATH (For Windows) Points to the bin directory of the Oracle client. For example, C:\oracle\product\10.2.0\client_1\bin. The
bin directory contains the path to the Oracle binary files. Add the following value to the PATH:$ORACLE_HOME/bin
Note
If you are using multiple versions of Oracle, make sure that the entry for the version you want to use appears
before the others.
14. When using the Oracle Instant Client, complete the following steps:
a. When installing the Oracle Instant Client, choose Administrator as the installation type. (For more
information, see your Oracle database documentation.)
b. Set the system path to the folder where the Oracle Instant Client is located on the local computer.
c. Set the ORACLE_HOME system variable to point to the folder where the Oracle Instant Client is
located on the local computer.
d. Set the TNS_ADMIN system variable to point to the folder where the correct tnsnames.ora file is
located.
Note
By default, the Oracle Net Services configuration files are located in the
OracleHome\network\admin directory. To change the default location, you can set the
TNS_ADMIN environment variable to the appropriate value (for example,
OracleBase\OracleHome\test\admin). The AR System suite installer accepts the value of the
Database Client Home Path field only for UNIX installations. If the installer does not find the
tnsnames.ora file in dbClientHomePath\network\admin or in the directory specified in
TNS_ADMIN, it prompts you to enter the path in the AR System Server Database
Information panel. If you provide a valid path, the installer sets the TNS_ADMIN
environment variable in the arsystem.sh script. The installer accepts your input and sets the
value for TNS_ADMIN only if you have Read permissions on the tnsnames.ora file.
e. Set the NLS_LANG system variable value for non-unicode or unicode.

f. Create the following soft links that point to libclntsh.so.11.1:
libclntsh.so
libclntsh.so.10.1
g. Create the directory structure as follows: ORACLE_HOME/bin and ORACLE_HOME/lib.
15. Configure the tnsnames.ora file to make sure that the service name is the same as the entry name for the
server on which you are installing BMC Remedy AR System. For example:

15.
COMPUTER1 =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = computer1.xyzcompany.com)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = COMPUTER1)
)
)
During the installation, you are asked for the database instance name, and it should match the entry in the
tnsnames.ora file (for example, MACHINEA).
For more information about tnsnames.ora, see your Oracle documentation.
16. Find the Connection Identifier in the tnsnames.ora file (located in $ORACLE_HOME/network/admin folder).
If multiple listeners are configured, locate the correct tnsnames.ora file in the correct $TNS_ADMIN value
path.
Following is an example entry in tnsnames.ora:
MyConnectionIdentifier =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = hostname)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = ORCL.MYWORLD)
)
)
17. Make sure that the Oracle listener is running and is configured correctly for the database.
18. After you finish installing the AR System server:
Add the following line to the ar.cfg file (Windows) or ar.conf file (UNIX) if cursor_sharing is set to
FORCE:
Oracle-Cursor-Sharing: FORCE
Add the following line to the Oracle initialization file:
CURSOR_SHARING: FORCE
For more information, see the Oracle's Cursor Sharing for BMC Remedy Products white paper on the
Customer Support website at: http://www.bmc.com/support.
19. Oracle has a limitation with cursor sharing and case insensitivity. With the Db-Case-Insensitive and
Db-Functional-Index parameters,
Oracle does not properly use the indexes if cursor sharing is set to FORCE. Therefore, even though FORCE
is recommended with normal case sensitivity, if you want to use case insensitivity, use EXACT. For more

19.
information, see the descriptions for Db-Case-Insensitive and Db-Functional-Index in ar.cfg or ar.conf
options: C-D.

For a BMC Remedy AR System server, you can use a tablespace that you previously created in Oracle.
Note
If you are using a RAC or ASM Oracle database, you must create tablespaces before installing BMC
Remedy AR System. For more information about creating tablespaces in RAC or ASM databases, refer to
your Oracle documentation.
1. In a SQL*Plus window, create the tablespace and temporary tablespace. For example:
create tablespace ARSYSTEM

datafile 'C:\DB-DATA\SSIORA12\DATA\ARSYS.dbf ' size 7000M reuse;
create temporary tablespace ARSTMPSPC tempfile 'C:\DB-DATA\SSIORA12\DATA\ARTEMP.dbf' size
2. Create a user. For example:
create user aradmin identified by AR#Admin#

default tablespace ARSYSTEM
temporary tablespace ARSTMPSPC
quota unlimited on ARSYSTEM;
3. Create a role for the user you created in step 2 ab ove. For example:
create role ARole_arsys not identified;
4. Set the privileges for the role. For example:
grant alter session, create cluster, create database link, create sequence, create session
5. Grant the role to the user. For example:
grant ARole_arsys to aradmin;

go
Related topics


ar.cfg or ar.conf options C-D for information on adding the Db-Case-Insensitive option to perform
case-insensitive queries on Run If qualifications for active links, filters, and escalations.
Preparing your IBM DB2 database before you install the AR System server
This section describes the steps you should perform with your DB2 database before you install BMC Remedy AR
System or any application in the BMC Remedy IT Service Management Suite.
Before you begin

To prepare your DB2 database
For local installations
For remote installations
Creation of a 32 KB tablespace
Pre-creating a database
AR System database components created for DB2 databases
Information added to AR System database configuration file (ardb.cfg or ardb.conf)
Minimum DB2 database transaction log size (for upgrades only)
Upgrading DB2 (for Service Level Management)
Some forms have entries that exceed the default BMC Remedy AR System size limit for each record. The
following steps help optimize the way DB2 determines which forms it places in larger containers. Perform these
steps to provide a balanced performance standard across all the forms.
Before you begin
If the BMC Remedy AR System server and the IBM DB2 database are running on the same environment on a
single server (not a remote DB2 database), and you are installing BMC Remedy AR System on a DB2
database, change the Local Security Policy settings before you install the BMC Remedy AR System server.
Go to Start > Administrative Tools > Local Security Policy > Local Policies > User Rights Assignment > Act as
part of the operating policy and add the user (administrator) who is running the BMC Remedy AR System
process. Then, select Local Policies > User Rights Assignment > Log on as a service policy, and add the user
(administrator) who is running the BMC Remedy AR System process .
Verify that the following DB2 values have been set during the installation of BMC Atrium CMDB:
APP_CTL_HEAP_SZ 40480 (DB2 version 9.4 or earlier)
APPL_MEMORY AUTOMATIC (DB2 version 9.5 or later)
INSTANCE_MEMORY AUTOMATIC (DB2 version 9.5 or later)
UTIL_HEAP_SZ 95000
STMTHEAP 60000
LOGFILSIZ 4000

To perform the following steps, make sure you are logged in as the DB2 instance owner. For example:
su - db2 instance
If the database is not configured to extend automatically, set the BMC Remedy AR System data file size to
at least 2 GB for one BMC Remedy application, or to at least 8 GB if you are also installing all BMC Remedy
ITSM applications.
Note
As of version 8.1 of the BMC Remedy IT Service Management Suite, your DB2 database server must be at
version 9.7 or later to upgrade the BMC Remedy ITSM Suite. If you are unable to upgrade your DB2
database server, refer to the instructions provided in the BMC Remedy ITSM documentation.
1. Install the DB2 database server.

You can install the DB2 database server on the same computer where the AR System server is installed or
on a remote server that is networked to the computer where you plan to install BMC Remedy AR System.
2. Install DB2 clients.
For remote installations, install the DB2 clients on the same computer as the AR System server.
3. (Solaris only) Install the DB2 libdb2.so library.
The AR System server is dynamically linked to the DB2 library on Solaris. If this library was not installed with
the DB2 client, install the library on the same computer where you plan to install the AR System server.
Note
For information on the supported DB2 client library versions, see the compatibility matrix (
Checking system requirements and supported configurations).
4. Create and name a DB2 instance.

For local database servers, create a DB2 instance on the local computer.
For remote database servers, create a DB2 instance on the remote computer.
Note
For naming restrictions, check your database vendor documentation.
5. Set the port configuration:

5.
db2 update dbm cfg using SVCENAME 60007
6. Restart the DB2 instance:
db2stop
db2start
7. Verify the port configuration:
db2 get dbm cfg | grep SVCENAME
Be sure to use the correct DB2 port during the installation.

8. Make sure the TCP/IP Protocol for the database is enabled, and set a TCP/IP port for the database instance.
9. (UNIX only) Verify or set the LANG environment variable.
installation. (For the list of parameters, see your planning spreadsheet.)
11. If you are using DB2 9.7, grant permissions to the DBADM role:
grant DBADM, BINDADD ,CONNECT, CREATETAB, CREATE_EXTERNAL_ROUTINE,

CREATE_NOT_FENCED_ROUTINE, IMPLICIT_SCHEMA, QUIESCE_CONNECT, LOAD
on database to user <userName>
Make sure the DBADM user exists as a local Windows account, and make sure that the passwords of the
local Windows account and the DB2 account are identical.
12. Make sure that the database's local catalog name matches the database's name on the database server.
If the names do not match, the installer will not display the Upgrade/Overwrite dialog box, and a warning
will appear: Warning! You have entered an existing database login.
13. For a Unicode DB2 installation, make sure that the DB2CODEPAGE variable is set to 1208.
On Microsoft Windows, for example, enter the following command from the DB2 command window:
db2set DB2CODEPAGE=1208
Note
The DB2CODEPAGE setting is part of the database client libraries. Make sure that this setting is
correct on the computer where the BMC Remedy AR System is running, which might be different
from the computer where the database is located.
For more information about the syntax and usage of DB2 commands, see the IBM DB2 documentation.
1. Create an operating system user account (for example, bmcuser1) on the same computer where you
installed the DB2 database and where you will install the AR System server.

1.
Note
The new operating system user account must have the Log on as Service rights.
2. For BMC Remedy AR System root installations or BMC Remedy AR System installations performed by a user
who is not a database instance administrator, make the user a member of the following groups, which are
created during the DB2 database installation:
db2iadm1
db2fadm1
db2asgrp
3. Give the user privileges to the following folders:
/etc/arsystem (Write permission)
/tmp (Write permission)
/opt/bmc/ (Write permission)
User-defined installation directory (Write permission)
/usr/sbin/slibclean (Execute permission on AIX platforms)
/tmp or /var/tmp or /usr/tmp (Write permission, depending on the operating system)
If the IATEMPDIR variable is set during the installation, make sure that the user has permission to the
appropriate file.
a. If you are migrating the DB2 database or instance to a different computer or environment, provide
privileges for the BMC Remedy AR System database user to the tablespace.
For example:
GRANT USE OF TABLESPACE <Tablespace> TO USER

<DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
The installer provides tablespace privileges during installation and expects that the
Syscat.tbspaceauth table has specific privileges for the grantee of the BMC Remedy AR System
database user.
b. Log in as the user (for example, bmcuser1 ), and start the installation.
Make sure that the user provided during installation is the owner of the pre-created 32K tablespace.
You can verify the owner of the tablespace using the following SQL query.
select TBSPACE, OWNER from SYSCAT.tablespaces where datatype='A' and

tbspace!='SYSCATSPACE' and PAGESIZE=32768
During the installation, enter the same user name (for example, bmcuser1) in the AR Database Login
field in the AR Database panel.
1. On the remote computer, complete the following steps:
a.
1.
a. Create an operating system user account with the same user name that was u sed in step a (f or
example, bmcuser1) on the same computer where you will install the AR System server.
Important
This DB2 user must have database creation privileges. Database access privileges are not
sufficient.
b. For BMC Remedy AR System root installations or BMC Remedy AR System installations performed by
a user who is not a database instance administrator, make the user a member of the following
groups, which were created during the DB2 database installation:
db2iadm1
db2fadm1
db2asgrp
c. If you are migrating the DB2 database or instance to a different computer or environment, provide
For example:
GRANT USE OF TABLESPACE <Tablespace> TO USER <DB2DatabaseUserLoginProvidedDuringARSys
database user.
d. Catalog the database from the DB2 client using a command-line processor.
The catalog command syntax is:
db2 catalog tcpip node <instanceNameAlias> remote <hostName> server <tcpPort>
For example:
db2 catalog tcpip node arsdbname remote servername.abc.com server 50000
For more information, see your DB2 documentation.

e. Confirm that the remote DB2 connections are correct.
After the remote connection is configured, create a DB2 database on the remote database server
and from the client computer DB2 prompt. Then, enter:
db2 connect to <databaseName>
<databaseName> is the name of the underlying database (for example, arsystem).

f. Log in as the user (for example, bmcuser1) on the remote computer, and start the installation.
During the installation, enter the same user name (for example, bmcuser1 in the AR Database Login

On a DB2 database, a 32 KB tablespace is created as a System Managed Storage (SMS) on new and overwrite
installations of the BMC Remedy AR System server.
The 32 KB tablespace is added during a BMC Remedy AR System installation as follows:
During a new installation, a 32 KB tablespace is created in the background with the name given for the
regular tablespace but concatenated with _32kb.
For example, if the tablespace name is ARSystem for the BMC Remedy AR System server, an additional
tablespace with a 32 KB page size is created and named ARSystem_32KB.
During an overwrite installation, the underlying database is dropped and a new database and tablespace
are created as they are for a new installation.
During an upgrade from version 7.1.00 to 8.1, the installer checks for the Form: AP:Rule Definition form
entry and, on the underlying database, validates the availability of the 32 KB tablespace that is listed in the
clause. If the 32 KB tablespace is present, the upgrade continues successfully. If it is not present, the
installer creates a 32 KB tablespace similar to the one described for a new installation and continues the
installation.
Note
When you create a DMS tablespace, 1 SMS tablespace and 1 SMS temporary tablespace with 32K
pagesize are automatically created as they are required by the installer.
If you select to install the Approval Server, the installer adds the Approval Server Form: AP:Rule Definition form
entry and its clause with the newly created 32 KB tablespace to the ardb.cfg (ardb.conf) file. (The existence of this
file is validated, and if it is not present when you install the Approval Server, the file is created. The Form: AP:Rule
Definition form entry is also validated to make sure that the clause contains the correct 32 KB page size
tablespace name.)
Note
You must pre-create the database with the same Database Login ID that is used as a value for the BMC
Remedy AR System Server DB Login ID installation parameter during the database installation. (For
example, ARAdmin).
To pre-create a DB2 database:
1.
1. Create a database.
Create a Unicode database:
DB2 CREATE DATABASE ARSYSTEM USING CODESET UTF-8 TERRITORY US
Create a non-Unicode database:
DB2 CREATE DATABASE ARSYSTEM
2. Connect to the created database, for example:
CONNECT TO ARSYSTEM
3. Drop the default tablespace.
drop tablespaces userspace1
4. Create two bufferpools: one with a 16K pagesize and another with a 32K pagesize.
Bufferpool names are user-defined (for example: arbp1, arbp2).
create bufferpool arbp1 size 1000 pagesize 16k

5. Create one of the following tablespaces:

Create Database Managed Storage (DMS) tablespaces using the 16K pagesize bufferpool created in
step 4.
For example:
CREATE TEMPORARY TABLESPACE ARTMP_PT01 pagesize 16k MANAGED BY DATABASE USING (FILE '
CREATE REGULAR TABLESPACE ARSystem pagesize 16k MANAGED BY DATABASE USING (FILE '/dat
Create System Managed Storage (SMS) tablespaces using the 16K pagesize bufferpool created in
step 4.
For example:
CREATE TEMPORARY TABLESPACE ARTMP_PT01 pagesize 16k MANAGED BY SYSTEM USING ('artmp')
CREATE REGULAR TABLESPACE ARSystem pagesize 16k MANAGED BY SYSTEM USING ('ardata') ex
[dropped table recovery off]
The container (artmp or ardata) can be an absolute or relative directory name.

6. Create SMS tablespaces using the 32K pagesize bufferpool created in step 4.
For example:

6.
CREATE TEMPORARY TABLESPACE ARTMP_PT01_32KB pagesize 32k MANAGED BY SYSTEM USING ('artmp_3
CREATE REGULAR TABLESPACE ARSystem_32KB pagesize 32k MANAGED BY SYSTEM USING ('ARSys_32KB'
Note
pagesize need to be created as they are required by the installer.
Optional parameters are enclosed in square brackets, for example:

[ dropped table recovery off]
Note
The Dropped Table Recovery Off option can improve performance but it means that you cannot
recover a table if it is accidentally dropped.
7. Grant the created tablespaces permissions for the database user.

For example:
GRANT USE OF TABLESPACE

ARSystem TO USER <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
with grant option
ARSystem_32KB TO USER <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
WITH GRANT OPTION
8. (For UNIX) Start the DB2 instance as the

<DB2DatabaseUserLoginProvidedDuringARSystemInstallation>.
If you are using the default database user and password:
db2 connect to ARSystem user aradmin using AR#Admin#
If you are using a different database user and password:
db2 connect to ARSystem user <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
Alternatively, you can also use the su command to change the owner of the DB2 instance.
For example:
su - <DB2DatabaseUserLoginProvidedDuringARSystemInstallation> and then starting the D
9.
9. If the following values for the following commands are not already set during the installation of BMC
Atrium CMDB, run the following commands:
DB2=> UPDATE DB CFG for databaseName using APP_CTL_HEAP_SZ 40480 (version 9.4 or earlier)
DB2=> UPDATE DB CFG for databaseName using APPL_MEMORY AUTOMATIC (version 9.5 or later)
DB2=> UPDATE DB CFG using INSTANCE_MEMORY AUTOMATIC (version 9.5 or later)

DB2=> UPDATE DB CFG for databaseName using UTIL_HEAP_SZ 95000
DB2=> UPDATE DB CFG for databaseName using STMTHEAP 60000
DB2=> UPDATE DB CFG for databaseName using LOGFILSIZ 4000
Note
The default database name is ARSYSTEM.
10. If the database is on a remote computer, grant the tablespace permission to the ARAdmin user by running
the following command:
DB2=> grant use of tablespace tablespaceName to user aradminUser with grant option;
11. When you finish, perform the following steps:

a. Enable the database you created.
b. Set the transactional logs.
BMC recommends the following settings:
Log file size (4KB) (LOGFILSIZ) 20000
Number of primary log files (LOGPRIMARY) 8
Number of secondary log files (LOGSECOND) 10
Log retain for recovery enabled (LOGRETAIN) OFF
User exit for logging enabled (USEREXIT) OFF
c. Check that the options are consistent with HADR mode.

For IBM DB2 databases, the installer creates the following BMC Remedy AR System database components:
Database components created for DB2
BMC Remedy AR Database tables that the BMC Remedy AR System installer creates on the DB2 server. The tables store all the data related to
System Database the BMC Remedy AR System database.

Tablespaces Logical layer between the database and the database objects that are stored in the database. The installer creates the
following tablespaces:
User (USER-DEFINED-TABLESPACE, for example, ARSystem) — Stores user-defined tables. The user tablespace is
where the BMC Remedy AR System tables will reside.
Temporary (USER-DEFINED-TEMP-TABLESPACE, for example, ARTMPSPC) — Stores temporary tables that are used
for short-term activities, such as sorting and displaying search results.
Catalog (SYSCATSPACE) — Stores system metatables.
SMS tablespaces In system-managed tablespaces:
The DB2 system manages the container space when the user specifies the container location.
The system increases the tablespace size dynamically when the number of records increases.
Data is stored in a directory container.
DMS tablespaces In database-managed spaces:
The database administrator (DBA) manages the container size.

Data is stored in a file container.
Space is allocated when the tablespace is created. You can also increase the size manually, as needed.
If the DMS space is not sufficient when you want to upgrade the BMC Remedy AR System server, double the pages of
the syscatspace.
Note
BMC recommends that you use SMS instead of DMS.
Containers Store physical data and tables corresponding to BMC Remedy AR System. There are three types of containers: file, directory,
and disk.
The AR System installer adds the following lines to the BMC Remedy AR System database configuration file
(ardb.cfg or ardb.conf):
Form: NTE:SYS-NT Process Control

Clause: IN tablespaceName
Form: NTE:SYS-NTUnProcessedRecords
Form: SRM:Request
Form: NTE:SYS-Individual NT Control
Form: NTE:SYS-Group NT Control
In the preceding clause, tablespacename is the name of the table space created in step 3.

The BMC Remedy ITSM installer adds the following lines to the BMC Remedy AR System database
configuration file if you are installing BMC Asset Management.
Form: AST:PurchaseRequisition-Detail-Signature
Clause: IN tablespacename
configuration file if you are installing BMC Change Management.
Form: CHG:Infrastructure Change

configuration file if you are installing BMC Service Desk: Incident Management.
Form: HPD:Help Desk

Form: HPD:Search-Assignment Logs
Form: HPD:Search-Worklog
Form: HPD:IncidentInterface_Create
In the preceding clause, tablespacename is the name of the tablespace you created earlier.

When you upgrade a BMC Remedy AR System 8.1 server that uses a DB2 database in an environment supporting
BMC Remedy ITSM applications, BMC recommends a minimum database transaction log file size of 1.3 GB.
Before starting the upgrade, adjust the following DB2 Universal Database configuration parameters to ensure that
logfilesize >= 1.3 GB:
LOGFILSIZ
LOGPRIMARY
LOGSECOND
For example:
Log file size (4KB) (LOGFILSIZ) = 20000
Number of primary log files (LOGPRIMARY) = 8
Number of secondary log files (LOGSECOND) = 10

Log retain for recovery enabled (LOGRETAIN) = OFF
User exit for logging enabled (USEREXIT) = OFF
Warning
This example is from a test environment and represents a minimum transaction log file size. To
determine the log file requirements for your environment, consult your database administrator before
beginning the upgrade.
For more information about determining your transaction log file size, go to
http://publib.boulder.ibm.com/tividd/td/tec/SC32-1233-00/en_US/HTML/ecoimst65.htm.

If you are using any version of BMC Service Level Management prior to version 7.6.04 and you want to upgrade to
version 8.1, then you must upgrade your BMC SLM DB2 database by running the DB2 database script.
Note
If you are performing a new installation of BMC Service Level Management 8.1, you do not need to
complete these steps.
1. Do one of the following tasks:

a. During the installation, if the ardb.cfg (ardb.conf) file is not detected, you receive an error message
that you must first create the ardb.conf file.
b. During the installation, if the ardb.cfg (ardb.conf) file exists but there is no SLM:ServiceTarget form
entry with clause of 32KB tablespace, you receive an error message that you must execute the
rundb2upgrade.sh script.
2. Run either of the following:
a. (AIX) Run ./rundb2upgrade.sh.
b. (Windows) Run rundb2upgrade.bat.
3. At the User Name prompt, type the AR administrator user name.
4. At the Password prompt, type the AR administrator user password.
5. At the AR Server Port prompt, type the AR port number.
6. Do either of the following tasks:
a. (AIX) At the AR Database Name prompt, type the AR table space name (case sensitive).
b. (Windows) at the DB2 Table Space name prompt, type the AR 32KB table space name.
7. At the AR Installation Directory prompt, type the AR installation path.
Note

7.
For Windows, the AR installation path must be in 8.3 format.
8. At the SLM Installation Directory prompt, type the SLM installation path.
9. At the Export Target Directory prompt, type the path for the exported data.
10. After running the script, re-install BMC Service Level Management 8.1.
Note
The script file is in the utility directory of DISK 1.
Related topics
Completing the planning spreadsheet

ar.cfg or ar.conf

Preparing your Sybase database before you install the AR System server
This section describes the steps you should perform with your Sybase database before you install BMC Remedy
To prepare your Sybase database

To pre-create a Sybase database
Forms with more than 254 fields
These steps are usually performed by a user who has database administrator privileges.
Note
If you try to install the BMC Remedy AR System server on top of 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'.

1. Install the Sybase database.

You can install the Sybase database on the same computer where the BMC Remedy AR System is installed,
System.
Note
A warning message with the names and paths of the dummy devices is displayed during the
installation procedure (after the Database File Input Panel is displayed). You must manually delete
these dummy devices after the installation procedure is complete.
2. Install Sybase clients.

For remote installations, install the Sybase clients on the same computer as the BMC Remedy AR System
server.
3. From the directory where the 64-bit Sybase client is installed, source the database.
../SYBASE.sh
4. Make sure that the TCP/IP Protocol for the database is enabled.
5. Verify or set the DSQUERY and SYBASE environment variables as follows:
DSQUERY=SybaseServer; export DSQUERY
SYBASE=SybaseInstallDirectory; export SYBASE
These examples use the syntax for Bourne shell.
7. If you are upgrading from BMC Remedy AR System 7.1.00 to 8.1, set the Select into database option for
the database that you are upgrading.
installation.
Tip
Refer to the planning spreadsheet for AR System installation parameters.
9. Change the minimum page size to 8 KB. For information about increasing the page size, see your Sybase
documentation.
10. Increase the default tempdb size to 600 MB.
11. If you created a device in addition to a master device, designate the database device as a default database
device. This is required because BMC Remedy AR System is always created on the default device.
12. If the database is configured to extend automatically, specify the following values:
a.
12.
a. Set the BMC Remedy AR System data file size = 3 GB or larger.
Note
If the database is not configured to extend automatically, set the BMC Remedy AR System
data file size to at least 2 GB for one BMC Remedy ITSM application, or to at least 8 GB if
you are also installing all BMC Remedy ITSM applications.
b. Set the log file size to 2 GB or larger.

c. Change the Sybase configuration file to the following recommended minimal values, and restart the
Sybase server:
\[Meta-Data Caches\]
number of open objects = 1310072
number of open indexes = 512000
number of open partitions = 6000
\[Physical Memory\]
max memory = 128000
\[SQL Server Administration\]
procedure cache size = 7000
\[Lock Manager\]
lock scheme=datarows
\[User Connections\]
number of user connections=50
13. Set the following Sybase database configuration parameters:

Max Memory = 128000
Number of Locks = 15000
Number of Open Partitions = 15000
The BMC Remedy AR System 8.1 suite installer optimizes SQL calls for installation on Sybase.
Therefore, a larger number of LOCKS must be configured for the database.
14. To prevent the transaction log from filling up during installation, set the trunc log on chkpt database
option on the following databases:
BMC Remedy AR System database
tempdb
Use the following commands: sp_dboption databaseName, 'trunc log on chkpt', true
go
Note
Disable the trunc log on chkpt option for all databases after the successful installation
and before any production activity.

15. If you are using Sybase 15, make sure that the number of open partitions parameter is set
appropriately.
For more information, see your Sybase documentation.
16. If you plan to install the BMC Atrium CMDB Product Catalog or any ITSM application, make the following
changes:
Set the Number of Open Objects to 30000.
Set the Number of Open Indexes to 15000.
Increase the size of tempdb. (You might have to create another device to increase the size of
tempdb.)
For more information about the LOCKS setting, see your Sybase documentation.
1. Create a device.
For example:
use master
go
disk init name='ARSystem_data', physname='/data1/ardata/ ARSys', size='1024M'

go
disk init name=' ARSystem_log', physname='/data1/ardata/ARSysLog', size='500M'

go
2. Create the database.

For example:
create database ARSystem on ARSystem_data=1024 log on ARSystem_log=500 with override
go
use master
go
3. Create the login with a password.

For example:

3.
sp_addlogin 'ARAdmin', 'AR#Admin#'

go
4. Create the db_owner group.

For example:
sp_addgroup db_owner
go
grant all to db_owner

go
5. Create the user pointing to the created login and group.

For example:
sp_adduser 'ARAdmin', 'ARAdmin', db_owner

go
use master
go
6. Modify the login to make its default database, the earlier created database.
For example:
sp_modifylogin ARAdmin, defdb, ' ARSystem'

go
use ARSystem
go
7. Change the owner of the database to be the created user.

For example:
sp_changedbowner 'ARAdmin'
go
use master
go
8. Add the select into option to the created database.

For example:
sp_dboption 'ARSystem','select into',true

go
9.
9. Use the created database.
use ARSystem
go

By default, Sybase does not work with forms that have more than 254 fields. This topic describes how to respond
to error messages that might result from forms with more than 254 fields.
Because some forms have more than 254 fields at installation time, or can be expanded to have more than 254
fields during an integration with another application, you might receive an error message similar to the following
example when installing the application on Sybase:
552 Failure during SQL operation to the database Number of variable length columns
exceeds limit of 254 forallpage locked tables. ALTER TABLE for 'T566' failed
If this happens during an integration, you might also receive a message similar to the following example:
303 Form does not exist on server SIT:Site Group
This occurs when the integration process adds fields to a form (using the ALTER TABLE command) that increase
the number of fields to more than 254. When this happens, Sybase rolls back the change and drops the original
table.
This generates further installation errors because additional dependencies fail to import.
Workaround
Form:NTE:SYS-Group NT Control
Clause: lock datarowsForm:NTE:SYS-NTUnProcessedRecords
Clause: lock datarowsForm:NTE:SYS-NT Process Control
Clause: lock datarowsForm:CHG:Infrastructure Change
Clause: lock datarowsForm:SRM:Request
Clause: lock datarowsForm:SRM:RequestApDetailsSignature
Clause: lock datarowsForm:SRM:RequestInterface
Clause: lock datarowsForm:HPD:Help Desk
Clause: lock datarows
Related topics
error message 552


11.1.6 Obtaining BMC Remedy license keys

You must obtain a BMC Remedy license key to install the AR System server. This topic includes the following
sections:
A license key is a value that enables you to activate a license. In BMC Remedy AR System 8.1, only AR System
server licenses require keys. Each key is tied to a particular host; a unique entry for each server is therefore
required within the Add or Remove Licenses form. To request a temporary or permanent key, you must access
the BMC Support Central Site at http://www.bmc.com/support.
Key type Information required
Temporary
Support contract ID
Email address
AR System server version
AR System server host ID
Permanent
Support contract ID
Purchase order number
Email address
Site Name default to Support Contract ID
To access the self-service license generator, you must be active on support and have an active user login account
on the BMC Support site.
Note
If you do not know our user ID and password, contact http://www.bmc.com/support-contacts
If you purchased your AR System server license through a BMC sales representative or over the web, you can
download the product from the BMC Electronic Product Distribution (EPD) site. Access the EPD site from the
BMC Customer Support website at http://www.bmc.com/support.
To request a license key
1. Log on to BMC Support Central at http://www.bmc.com/support.

2. Click Licensing and Passwords.
3. Click Request a New License.
You can also click Request a Trail/Temporary License if needed. These licenses are valid only for 30 days.
4. Click I Agree.
5. Enter the required information for the license, for example, the purchase order number.
a.
5.
a. Verify that your available licensed products and features you are attempting to obtain are related
with the Support Contract ID displayed on the form. If the correct Support ID is not displayed,
contact BMC Customer Support to help manager your support IDs.
b. Select the correct AR Server version, for example, *7.1 and Higher *.
c. Enter the host ID of the AR System server.
To find the Host ID, see To determine the server host ID using the ipconfig command.
6. Select AR Server under Product Feature and enter 1 in Quantity Requested.
7. Click Request License.
Note
You can only request 1 license key at a time.
Your license key will be sent to your email address.
To add a new application license
1. From your browser, log on to BMC Remedy ITSM.

2. From the list of applications on the IT Home page, select AR System Administration > AR System
Administration Console.
3. In the navigation pane, select System > General > Add or Remove Licenses.
The Add or Remove Licenses form appears.
4. Click Add New.
5. From the License Type field, select AR System Server.
6. Enter 1 as the number of licenses.
7. Enter the license key in the License Key field.
8. Click Save.
9. Add licenses whenever you need them from the Add or Remove Licenses page.
Tip
Add only one license key per application, but you should add enough user licenses for the various
BMC Remedy ITSM applications that you are using.
a. From the list displayed, select the type of license that you want to add.
The License Type field is updated with the license type that you selected.
b. Select the number of licenses and enter the license key, if applicable.
c. Click Add New.
10. Click Generate License Usage Report to communicate license usage to your support and account
representatives.

10.
Note
Versions 7.5.00 patch 003 and later of BMC Remedy AR System do not require keys for application
licenses; keys are required only for BMC Remedy AR System server licenses.
To determine the server host ID using the ipconfig command (Windows)
1. Open a command window on the server computer.

2. At the prompt, enter ipconfig /all.
3. Find the physical address for the server computer.
In the following screenshot, the physical address is 00-FF-B0-AB-3D-07.
BMC uses the physical address of your computer without the dashes.
4. To use the server host ID to obtain your license key, remove the dashes from the physical address.
In this example, the server host ID that BMC uses to license the AR System server is 00FFB0AB3D07.
5.
5. Use this information to generate your permanent or temporary license key.
11.1.7 To determine the server host ID using the ifconfig command

(Linux)
6. Open a terminal.
7. At the prompt, enter ifconfig.
8. Record the Hardware Address. For example:
HWaddr 00:50:56:AC:04:10
9. Remove all the colons from the value and convert uppercase letters to lowercase (for example,
005056ac0410).

11.1.8 Completing the planning spreadsheet

Before you start installing or upgrading the products, you must gather information about the required parameters
that the installer prompts for each product. The planning spreadsheet provided in this section helps you to gather
these parameter values. To avoid installation errors, refer to this spreadsheet when you run the installation.
Note
You must know the actual login credentials to a server or database to complete installations. BMC
installers are not integrated with Atrium Single Sign-On, SSL, or other authentication methods to
authenticate users. For example, you cannot use a smart card scan to authenticate a user to perform
installations of BMC products.
To plan for your installation by using the spreadsheet
1. Download and open the 8.1 planning spreadsheet.

2. Enter your selections and parameter values into the Value column with the help of your DBA or system
administrator.
For example, after installing BMC Remedy AR System server, you use the values that you entered in the
spreadsheet when you install BMC applications.
3. Launch the installer.
4. Copy the parameter values from the spreadsheet and paste them into the product fields in the installer.
Tip

4.
The columns and rows in the Microsoft Excel spreadsheet are formatted so that each sheet prints
cleanly in landscape format.
Related topics

Preparing your environment to install
Understanding the server name alias and host name

During the installation on Windows or UNIX, you are asked for the BMC Remedy AR System server alias and a
BMC Remedy AR System server host name or IP address, which is the physical system on which the BMC Remedy
AR System server will be installed. (Because there are multiple aliases for each system, the host name might not
match the server alias.)
Note
When you install BMC Remedy AR System, the computer from which you are installing must be able to
connect ("ping") to the server alias you provide. In the installer's AR System Server Name Alias field, enter
the server's short name (for example, enter alpha instead of alpha.remedy.com). Additionally, make sure
to configure the primary DNS suffix. For more information, ask your system administrator.
If the server will be accessible over a network, the server alias must be resolvable to an IP address. To make sure
that clients can resolve the server alias:
Use only alphanumeric names containing only lowercase letters a through z and numbers 0 through 9.
You can use hyphens (-), but the name cannot start or end with a hyphen.
Avoid underscores (_) and other special characters (for example, $) because these characters do not
comply with DNS rules.
If you are installing multiple BMC Remedy AR System servers on a single computer, make sure each server alias is
unique. To make sure that BMC Remedy AR System server aliases are unique, verify the following:
The correct licenses are used.

The correct BMC Remedy AR System database is used for each BMC Remedy AR System server.
You can selectively stop and start server processes.
The BMC Remedy AR System server alias identifies the configuration file and the service ( armonitor) associated
with each BMC Remedy AR System server.

On UNIX, the following daemons are listed for each BMC Remedy AR System server that is running: armonitor,
arforkd, arplugin, and arserverd. To display all services that are currently running, issue the following
command:
# ps -ef | egrep ar
Understanding port numbers

Port numbers identify the TCP ports where the BMC Remedy AR System server and the plug-in server will run.
The TCP port number for the BMC Remedy AR System server and the port number for the plug-in server cannot
be the same.
In this topic:
Registering with a portmapper

Portmapper and multiple servers
Detecting a portmapper
Assigning port numbers
Default port numbers
BMC Atrium Core ports

Atrium Integrator ports
Related topics
Registering with a portmapper

A portmapper is a service that runs independently of the BMC Remedy AR System server and serves as a directory
of port numbers.
When users log on to BMC Remedy AR System:
If a server is registered with a portmapper, users do not need to specify the port number in the client
because the portmapper can locate the port and direct clients to the appropriate location.
If a server is not registered with a portmapper, or if a Port 111 firewall blocks the portmapper port, users
must specify the port.
When you start the server, it opens a port to listen to. You can specify a port for the server or let the server obtain
an available port dynamically.
You can register a server with a portmapper and assign a port number. For example, if you do this and do not
expose the portmapper outside a firewall, clients within the firewall do not need to be configured to access the
specified port number. They can access the portmapper, which directs them to the port. Clients outside the
firewall must be configured to access the specified port number.

Note
The BMC Remedy AR System server does not have a default port or specific range of ports. The
operating system randomly assigns ports. To make sure that the portmapper always uses the same port
for the BMC Remedy AR System server, specify a port during installation or use the BMC Remedy AR
System Administration Console to configure the server after you install it.
Portmapper and multiple servers

If you use portmapper for one server on the computer, you must assign TCP and plug-in port numbers to all the
servers on the computer. (Only one BMC Remedy AR System server on any server can register with portmapper.)
If you configure two or more servers to use portmapper by mistake, the last server to start is the only one
registered and available for login without identifying a TCP port from the Login window.
If you want to configure two or more servers on one Microsoft Windows computer, make sure that all the servers
on the computer have unique port numbers and are not registered with portmapper.
Note
If you plan to use the portmapper with a server group installation, indicate Yes for the Register with the
Portmapper prompt during the AR System server installation. If you do not specify Yes for Register with
the Portmapper prompt, then the AR System server does not use portmapper.
Detecting a portmapper
On Microsoft Windows, the AR System installer searches for an existing portmapper. If a portmapper is installed
and running and you choose to register with a portmapper, the BMC Remedy AR System registers the server with
that portmapper. If the installer does not detect a running portmapper and you chose to register with
portmapper, the installer installs the portmapper and registers the AR System server with that portmapper.
Note
By default, Microsoft Windows 2008 comes with a portmapper installation. If you want to use the BMC
Remedy AR System portmapper, you must uninstall the portmapper provided by Microsoft and then
continue with the BMC Remedy AR System installation; otherwise you can continue with the BMC
Remedy AR System installation without the BMC Remedy AR System portmapper.
Assigning port numbers

If you do not register with a portmapper, you must assign a port number to any AR System server that you want
clients to access directly, and to the plug-in server.

Important
Do not assign port numbers that conflict with port numbers used by other applications or other
programs running on your system. To find out which port numbers are already in use, use the netstat
-na command (UNIX) or the netstat -a command (Windows) at the command prompt.
Assign port numbers greater than 1024 because:
Port numbers within the range 1 – 1024 are available for use only by the superuser, and many of these
numbers are reserved.
BMC Remedy AR System clients earlier than version 5.0 cannot access port numbers lower than 1024.
Important
When installing on Linux, the installation program crashes if you enter port 12333 for any port
parameter, such as the Java Plug-in Server TCP Port Number or the AR System Server TCP Port Number.
This a known JVM issue in version Java 2 Runtime Environment, Standard Edition, 1.5.0_05.
Note
You can also add the ports to the TCD-Specific-Port and Plugin-Port parameters in the ar.cfg (ar.conf)
file.
For more information about port numbers, go to http://www.iana.org/assignments/port-numbers.
Default port numbers

Following are the default port numbers that are assigned during BMC Remedy AR System installation:
Note
For BMC Remedy AR System version 8.1.00, the installer automatically selects the port numbers for the
different components during installation.
Module Port usage BMC Remedy AR System BMC Remedy AR System BMC Remedy AR
description 7.1.00 and later 7.5.00 and later System 8.1.00
Email Engine RMI 1100 1100 1100 - 1149
Flashboards RMI 1099 1099 1150 - 1199
Mid tier

Standard 8005 (shutdown) 8005 (shutdown) 8005

Tomcat ports 8443 (SSL) 8443 (SSL) (shutdown)
8009 (AJP13 8009 (AJP13 8443 (SSL)
connector) connector) 8009 (AJP13
8082 (proxy) 8082 (proxy) connector)
8080 (standalone 8080 (standalone 8082 (proxy)
http) http) 8080
(standalone
http)
ServletExec 8888 (admin) 8888 (admin)
Plug-in server TCP port Uses portmapper Uses portmapper Uses portmapper
Java plug-in TCP port 9999 9999 9999
Note: If you are planning to install the CMDB,

see the following note.
Carte (Pentaho) server port (for Atrium TCP Not applicable 20000 (version 8.x and 20000 - 20050
Integrator later)
FTS Java plugin server TCP Not applicable 9998 (version 7.6.03 and 9988 - 9998
later) (primary)
9977 - 9982
(secondary)
Important
Before proceeding to the BMC Remedy AR System server installation, make sure that the port
range for Email Engine, Flashboards, Carte (Pentaho), and FTS is available on the system and the
ports are not blocked.
If you are planning to install the CMDB and the Java plug-in port number is not 9999 in the
following files, change the values to 9999 before installing the CMDB. The CMDB must use port
9999 for its web service.
Plugin-Port value in the ar.cfg (ar.conf) file
Java plug-in default port number in pluginsvr_config.xml file
The server does not have any default ports.
BMC Atrium Core ports

This table lists the default port number of all BMC Atrium Core features.
Component Default Port Number Is the port number configurable? Supported port number
NE Plugin port 9555 Yes any

Atrium Plug-in port 9556 Yes any
Tomcat HTTP Port blank Yes any
Tomcat HTTPS Port blank Yes any
Note
If you are using a pre-installed Tomcat, the Tomcat HTTP Port and the Tomcat HTTPS Port fields are
populated with the default port numbers. You cannot change the value of these fields.
Atrium Integrator ports

This table lists the default port number for Atrium Integrator.
Component Default Port Number Is the port number configurable? Supported port number
MS SQL Server 1433 Yes any
Oracle server 1521 Yes any
Related topics
Portmapper service introduction
Setting ports and RPC numbers
ar.cfg or ar.conf
Configuring the Java plug-in server
Understanding what APIs and plug-ins are installed

BMC Remedy AR System includes plug-ins and corresponding application programming interfaces (APIs) that
extend the BMC Remedy AR System functionality to external data sources. The plug-in service, a companion
server to the BMC Remedy AR System server, loads the plug-ins and accesses them upon request from the AR
System server.
When you install BMC Remedy AR System, you can choose what you want to install:
The provided Lightweight Directory Access Protocol (LDAP) plug-ins (AREA LDAP and ARDBC LDAP)
The features to create your own AREA and ARDBC plug-ins
The API package
The BMC Remedy AR System API suite is composed of a C API, a Java API, a plug-in API, and plug-ins that use
APIs:
BMC Remedy AR System External Authentication (AREA) — Accesses network directory services, such as
LDAP. You can create and configure your own custom authentication plug-in, or you can use the provided

plug-in. The AREA plug-in also enables BMC Remedy AR System users to consolidate user authentication
information for external applications or data sources.
BMC Remedy AR System Database Connectivity (ARDBC) — Accesses external sources of data. The ARDBC
plug-in, which you access through vendor forms, enables you to perform the following tasks on external
data:
Create, delete, modify, and get external data
Retrieve lists for external data
Populate search-style character menus
For example, if you need to access data in an external directory service, you can use the ARDBC
LDAP plug-in.
Install the API if you will install the mid tier, or if you require functionality that is not included in the BMC Remedy
AR System client tools.
Related topics
Developing an API program
Using the ARDBC LDAP plug-in
Understanding application server passwords

All application servers must use a password to connect to the BMC Remedy AR System server. When you install
BMC Remedy AR System, you must set the following application server passwords:
Local DSO User Password — Password required to use Distributed Server Option (DSO)
Application Service Password — Password for features such as Email Engine and Flashboards
Mid-Tier Administration Password — Password that the mid tier uses to access the AR System server
If any applications that use the application server passwords are already installed, make sure that the passwords
you enter match the passwords for the corresponding applications. If a password does not match, the application
will fail. The application server passwords are case-sensitive. To avoid authentication failures, application
passwords must not exceed 20 characters.
Warning
When working with server groups, use the same DSO and Application Service password for all servers in
the group.
When you install the AR System server, the installer sets the application server passwords in the ar.cfg or ar.conf
file, and in the configuration files for any of the application servers that are installed at the same time. To change
or set application server passwords after installation, you must make the change for the BMC Remedy AR System

server and for the appropriate application server. To change an application server password on the AR System
server, use the Connection Settings tab in the AR System Administration: Server Information form (accessed from
the BMC Remedy AR System Administration Console).
If you change an application server password on the AR System server after installation, you must also change the
corresponding password for the application server:
Mid Tier Administrator — Titled the "Admin Password" in the Mid Tier Configuration Tool
Email Engine — Updated in the EmailDaemon.properties file
Application Service for the Flashboards server
DSO
If you plan to use AR System server 8.1 with an older mid tier (for example, you are upgrading your server, but will
continue to use an earlier mid tier while you test the new AR System server), set the administrator password for
the earlier mid tier server. To do so, log on to the BMC Remedy Mid Tier Configuration Tool, click the AR Server
Settings link, and add the password to that server.
Related topics
Configuring a password for the DSO user

Configuring the AR Server Settings page
Configuring the Connection Settings page (for information about changing the application server
passwords after installation)
Installing a server group
Configuring the Change Password page
EmailDaemon.properties file
Resetting the Application Service password
Configuring a password for the DSO user
Understanding the BMC Remedy Mid Tier
Tip
For best results, install BMC Remedy Mid Tier on a separate computer from the AR System server.
You can install the mid tier on UNIX or Micrososft Windows with the Tomcat JSP engine, which is bundled with
the mid tier. That is the most common method. Or you can install the mid tier only and use your own JSP engine.
Note
BMC Remedy Mid Tier requires 32-bit JVM if the web server is 32-bit or is running in 32-bit mode. You
can specify this exception in the installer if required for your installation.

BMC recommends that you use the BMC Remedy AR System suite installer to install the mid tier. Alternatively,
you can use a .war file that is bundled with the installer files. (A .war file is available for each supported web
server.)
Review the following topics to prepare to install the mid tier:
Related topics
Checking system requirements and supported configurations

Optional components that you can install
When you install BMC Remedy Mid Tier by using the suite installer, the following optional features are installed (if
you select them):
Tomcat JSP engine — The Tomcat JSP engine is installed in <ARSystemInstallDir>\<serverID>\tomcat.

In BMC Remedy AR System 8.1, you can install Tomcat version 6.0.20. If you select this option, the installer
checks for versions of Tomcat and displays messages accordingly:
No Tomcat version is detected — You can either install Tomcat by using the BMC Remedy Mid Tier
installer or choose not to install Tomcat.
Unsupported Tomcat version is detected — The installer displays a message indicating that you need
to install the supported Tomcat version before continuing with the installation.
Different supported Tomcat version is detected — The installer displays a message indicating that
the supported version is already present. You can install version 6.0.20 or use the version that you
already have installed.
Same Tomcat version is detected — BMC Remedy Mid Tier installation continues.
(Windows only) The required BMC Remedy ODBC DLLs and driver for Crystal Reports — You must have
BusinessObjects Enterprise XI (BOXI) to run Crystal Reports. If you have BusinessObjects Enterprise XI
installed and if you select the AR System Mid-Tier option while installing BMC Remedy AR System, the AR
Crystal Web Application gets installed by default. When you upgrade the mid tier, the installer replaces
your ODBC driver with the latest one.
Note
BMC Remedy AR System supports versions 3.1 and 4.0 of BusinessObjects Enterprise XI. If you are
using Crystal Reports with BMC Remedy AR System and have an earlier version of BusinessObjects
Enterprise XI installed, you must upgrade BusinessObjects Enterprise XI to version 3.1 or 4.0
before installing BMC Remedy AR System.

(Windows only) ARWebReportViewer application — If you have BusinessObjects Enterprise XI installed, the
ARWebReportViewer application is installed. The minimum amounts of free space required for the mid tier
host are as follows:
120,000 KB during installation
40,000 KB after installation
Related topics
Configuring the Crystal reports integration
Configuring BMC Remedy AR System settings for Crystal reports
Installing components and patches for the mid tier

Before you install the mid tier, install the following components. See the pre-installation considerations (if any)
for these components in the sections that follow.
Components to install before you install the mid tier
Component More information
Java Software An SDK that is available from the appropriate third-party vendor's site.
Developer's Kit (SDK)
with the public Java
runtime environment
(JRE)
Web server For a list of the compatible web application servers, see http://www.bmc.com/support/product-availability-compatibility.
BMC Remedy AR The AR System server can be installed locally, but the mid tier is typically installed on a separate computer with network
System server access to the server.
(Optional) Reporting If you are running Crystal Reports on the web, install one of the following tools:
tool
BusinessObjects Enterprise XI (recommended)
Crystal Reports Server XICrystal Web Component Server (which requires advance configuration) is available from
http://www.businessobjects.com/. If this server is installed remotely, you must share the mid tier installation
directory with the remote Crystal Server, specifying the full path to this directory. Make a note of this directory path
if you are accessing Crystal Web Component Server over a network.
(Optional) Home Page The home page form displays entry points on a given server or server group. The home-page server must be a AR System
server server and can be configured as a home-page server.
(Optional) Preference The preference server must be a AR System server, must be configured to be a preference server, and must be entered in
server the list of AR System servers.
(Optional) JavaServer If you are not using the Tomcat JSP engine that is bundled with the mid tier installation, you must install and enable your
Pages (JSP) engine supported JSP engine before you install the mid tier. For a list of supported JSP engines, see
http://www.bmc.com/support/product-availability-compatibility.
The appropriate See the Downloads & Patches link at http://www.bmc.com/support.

patches for your
configuration

Related topics
Reporting in BMC Remedy AR System
Specifying a home page on the server
Setting user preferences
Installing the AR Crystal Web Application

If you have BusinessObjects Enterprise XI installed on the system, you can select the AR Crystal Web Application
option under the Mid Tier option of the suite installer.
When you install the AR Crystal Web Application, the ARWebReportViewer application is installed. This application
is used to enable users to view Crystal Reports.
If you want to run BusinessObjects Enterprise XI on a different machine than the mid tier, you must install the
ARWebReportViewer separately.
Related topics
Preparing your web server

A web server is responsible for accepting HTTP requests from clients (web browsers) and serving them HTTP
responses along with optional data content, such as web pages (HTML documents) and linked objects such as
images.
JavaServer Pages (JSP) and servlets are Java technologies that allow software developers to dynamically generate
HTML, XML, or other types of documents in response to a Web client request. The technology allows Java code
and certain pre-defined actions to be embedded into static content.
The mid tier uses third-party web servers and JSP/servlet engines. The following table outlines the tasks
necessary to prepare your web server for use with the BMC Remedy Mid Tier (depending on the JSP engine you
will use).
Steps to prepare your web server
Web server JSP engine Steps to follow
Apache Tomcat See the following procedure.
IIS Tomcat No pre-requisite steps are necessary.
Other Tomcat No pre-requisite steps are necessary.
Other JBoss No pre-requisite steps are necessary.
Apache or IIS ServletExec No pre-requisite steps are necessary.

Web server JSP engine Steps to follow
Other Other For an Oracle WebLogic, or IBM WebSphere web server, use a .war file.
As you set up the mid tier to work with third-party web servers, remember these tips:
The mid tier installer includes a bundled version of the Tomcat web server. A third-party web server
installation is not necessary.
The mid tier requires HTTP version 1.1.
If you use Tomcat 5.5.28 or later and you have a forward slash (/) in your form or view name, you must
configure Tomcat to allow forward slashes in the URL.
Tuning web servers and JSP/servlet engines is beyond the scope of BMC Support. Contact the vendor for
help with tuning these components.
To prepare an Apache server before installing the mid tier
1. Make sure you have root permissions to the Apache web server that allow you to write to all relevant files
and directories. For example, you must have access to the /usr/conf/httpd.conf file.
2. If you are upgrading and the existing mid tier was installed with a Group ID value of #-1 (default value),
modify the <ApacheInstallDirectory>/conf/httpd.conf file.
Use an editor to search for the Group identifier. If you see Group #-1, change it to the valid group and save
the file.
3. Make sure that the DSO option on your Apache installation is enabled. After the Apache software has been
installed, enter the following command to see the list of modules:
<ApacheInstallDir>/bin/httpd -l
If this list contains the mod_so.c entry, the DSO is enabled.

4. To minimize security exposure, include umask 077 in the web server start sequence.
Using umask 077 ensures that files created by the web server processes will be owned and can only be
used by the user who runs that web server.
Related topics
Understanding the BMC Remedy SNMP Agent

During installation, you are prompted to install and configure the BMC Remedy Simple Network Management
Protocol (SNMP) Agent. SNMP is a set of protocols that network administrators use to manage complex networks
and to query server statistics data. BMC supports the following versions of SNMP: 1, 2c, 3.

The BMC Remedy SNMP Agent monitors the AR System server and the BMC Remedy Distributed Server Option
(DSO) processes.
If any of these processes change state (for example, if a process becomes inactive), the BMC Remedy SNMP Agent
sends a trap (or notification) to a trap receiver. Each trap contains the following information:
Name of the process (for example, BMC Remedy AR System plug-in)

Name of the BMC Remedy AR System server associated with that process (for example, BMC Remedy AR
System 1)
The state of that process (active =1, inactive =2)
You can also configure network management stations to query the BMC Remedy SNMP Agent about the state of
the AR Monitor.
Check with your network administrator to see if you must configure the BMC Remedy SNMP Agent and what
specific configuration settings you must use.
You can now configure the BMC Remedy SNMP Agent through the AR System Administration SNMP Config form.
For more information, see SNMP Configuration form in the AR System Administration Console.
Related topics
BMC Remedy SNMP Agent configuration
11.1.9 Preparing your environment to install

Use the following topics to prepare your Windows, Linux, or UNIX environment:
Preparing your system to install the BMC Remedy AR System server and database
The BMC Remedy AR System suite installer prompts you to enter information about the BMC Remedy AR System
database, which the installer creates during the installation. This database contains the BMC Remedy AR System
server forms and field definitions, and also stores workflow data, structures, and permissions.
To prepare your system to install the BMC Remedy AR System server and database
1. Back up your database and file system before you install.

If you are upgrading, back up your data, object definitions, and applications.
2. Make sure that the server can be resolved to a server alias. If you are installing more than one server on a
computer, make sure that each server has a unique server alias.
3. Determine the ports that you will use.
4. Check if you have installed Microsoft Visual C++ 2008 SP1 Redistributable Package (64-bit).
Note

4.
If Microsoft Visual C++ 2008 SP1 Redistributable Package (64-bit) is not installed, the installer
checks for this version. If this version is not present, the installer installs the required version.
5. Review the pre-installation considerations specific to UNIX and Microsoft Windows (for example, setting
environmental variables).
Preparing the Windows environment

BMC recommends that you read through the material in this topic before installing BMC Remedy AR System
server version 8.1 on Microsoft Windows.
To run the installer on Windows, you must have administrator access.
If you are using Terminal Services, update the Terminal Services configuration options as needed before running
the suite installer. If you are using Terminal Services, the installer will not run until you configure Terminal
Services correctly. To configure Terminal Services for Windows Server 2003 , you use the Terminal Services
Configuration utility, for Windows Server 2008, you use the Group Policy Editor.
If you are using the data execution prevention (DEP) feature in Windows XP (with Service Pack 2 or later),
Windows Server 2003 or Windows Server 2008, you need to configure DEP for the BMC Remedy AR System
installer executable program.
Note
If you do not configure these items before you run the installer, an installer panel appears listing the
steps required to handle these issues.
To update Terminal Services configuration options for Windows Server 2008

To configure the DEP feature
Installing on Windows with Oracle
1. From the Windows Start menu, click Run.

2. Type gpedit.msc, then click OK.
3. Navigate to Computer Configuration > Administrative Templates > Windows Components > Remote
Desktop Services > Remote Desktop Session Host > Temporary Folders.
4. Enable the settings for Do not delete temporary folders on exit and Do not use temporary folders per
session.
5. (optional) Restart the computer.
6. If the settings do not take affect, complete the following steps:
a. From the Windows Start menu, click Run.
b.
6.
b. Type regedit, then click OK.

c. Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server.
d. Update PerSessionTempDir to 0 and DeleteTempDirsOnExit to 0.
e. (optional) Restart the computer.
1. From the Windows Start menu, click Run.

2. Type tscc.msc, then click OK.
3. In Server Settings, set Delete temporary folders on exit to No.
4. Set Use temporary folders per session to No.
6. If the settings do not take affect, complete the following steps:
a. From the Windows Start menu, click Run.
b. Type regedit, then click OK.
c. Go to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Terminal Server.
d. Update PerSessionTempDir to 0 and DeleteTempDirsOnExit to 0.
e. (optional) Restart the computer.
To configure the DEP feature

If you are using the data execution prevention (DEP) feature in Windows, configure DEP for executable programs.
Note
If you do not configure these items before you run the installer, an installer panel appears listing the
steps required to handle these issues.
1. From the Windows Start menu, click Control Panel; then double-click System.
2. Click the Advanced tab.
3. In the Performance area, click Settings.
4. On the Data Execution Prevention tab, verify if the Turn on DEP for all programs and services except those I
select option is selected.
If the Turn on DEP for essential Windows programs and services only option is selected, no configuration is
required.
Note
If you do not select the Turn on DEP for all programs and services except those I select option,
and then perform the remaining steps in this procedure, the installer might not run correctly.
5. If the Turn on DEP for all programs and services except for those I select option is selected, click Add.
6.
6. Browse to the executable, and then click Open.

The installation program appears in the DEP program area.
7. Click Apply; then click OK.
Installing on Windows with Oracle

If you are using parenthesis "()" in the BMC Remedy AR System server installation path, for the BMC Remedy AR
System server installation for Windows with Oracle to be successful, make sure that you install Oracle patch
5059261 (patch set Oracle 10.2.0.4.0).
Preparing the UNIX environment

BMC recommends that you read through the material in this topic before installing BMC Remedy AR System
server version 8.1 on UNIX or Linux. On UNIX, the installer uses a graphical user interface. (Alternatively, you can
also use the silent installer.)
Preparing to install as a non-root user

Running a remote installation on UNIX
Assigning a temporary directory
Removing sticky bit permissions on the temporary directory
Installing in a headless environment
Long file names (HP-UX and Linux)
Preparing to install on Red Hat Linux 6.x
Preparing to install on AIX
Setting ulimit before installing BMC Remedy ITSM
Using kernel tuning to increase transactions and users

You can install the BMC Remedy AR System server as a root or non-root user.
When you install as a non-root user, you must update the system configuration files manually. The installation
script prompts you to do this and instructs you to start a shell where you have root access or full read and write
access.
Installing as a non-root user allows a user to maintain the BMC Remedy AR System software without the
assistance of a system administrator. However, to automatically start the AR System server when your computer
restarts, you must ask your UNIX system administrator to change the system startup scripts accordingly.
1. Make sure that you have access to the following directories and the files under them:
.profile file in your home directory (write access)
/etc/mnttab file (write access, HP-UX 11.23 only)
/etc/arsystem
/usr/tmp directory

/opt/bmc directory
If you do not have a /opt/bmcdirectory, you must create it to complete the installation.
Note
AIX also requires execute and suid permissions to the /usr/sbin/slibclean file, for the root
and non-root user.
JREHomeDirectory/bin (read and execute permission)

2. Make sure that the non-root user belongs to a group that has database access (For example, the dba
group).
This step is valid for all the database types.
You must do this only for installation.
You must add the user to the group where database is installed and give the user read, write, and
execute permissions to access the database file system.
For Oracle client libraries, you must give access to the Oracle client Home and Oracle server Home
directory.
3. Run the BMC Remedy AR System installation.
Some of the actions you will be prompted to perform (as a non-root user) include:
Creating several directories and setting permissions for those directories. For example, the script
prompts you to create the /etc/arsystem directory with read/write permissions for all users.
Merging the contents of files. For example, merge the
<ARSystemServerInstallDir>/ar-<Database>/rpc file with the /etc/rpc file.
4. On the Linux platform, if you will be starting arserverd as a non-root user, make sure that the "open files"
limit of the shell is set to 16384.
5. When installing other BMC applications as a non-root user, you must log in to the UNIX system under the
same UNIX user ID that was used to install BMC Remedy AR System.
Running a remote installation on UNIX

Follow the steps given below to run a remote installation on a UNIX computer:
1. Make sure you have an X Windows client on the local computer.

2. Log in to the remote machine, and set the DISPLAY environment variable to point to the X Windows client
on the local computer.
3. Run the installer.
Note
If you do not have the X Windows client, use the silent installer .

Assigning a temporary directory

The installer uses the IATEMPDIR environment variable to assign the location of a temporary directory to use
during installation. If your /tmp or /home/ userName directories do not have enough free space to run the
installation, it will fail.
If you have access to another drive or partition with more free space, set a new temp directory by using one of
the following commands:
export IATEMPDIR=/ <pathName>

setenv IATEMPDIR / <pathName>
In these commands, <pathName> is a writable directory with more free space available than the default
directories.
Note
BMC recommends that you have 1 GB of free space.
Removing sticky bit permissions on the temporary directory

If you have sticky bit permissions on the temporary directory, the installer does not create the
/tmp/ARSystemInstalledConfiguration.xml file. Therefore, you must remove sticky bit permissions from the
directory before running the installer.
Installing in a headless environment

The installer no longer supports the command-line interface on UNIX as in previous versions. To install on a
headless computer, use a remote X Windows session or the silent installation process.
Long file names (HP-UX and Linux)

For HP-UX and Linux systems, configure the operating system to allow long file names to be read and copied.
You might find operating system configuration issues in installing directly from a DVD. In some cases, the DVD
mount might cause long file names from the DVD not to work.
Preparing to install on Red Hat Linux 6.x

Before installing the AR System server and the BMC Remedy IT Service Management suite on a Red Hat Linux 6.x
server, complete the following steps:
1. Install the following 32-bit RPM packages so that user interface support is available for the installer:
libX11-1.3-2.el6.i686.rpm
libXau-1.0.5-1.el6.i686.rpm
libxcb-1.5-1.el6.i686.rpm
libXext-1.1-3.el6.i686.rpm
libXi-1.3-3.el6.i686.rpm

libXtst-1.0.99.2-3.el6.i686.rpm
2. Install the compat-libstdc++-33-3.2.3-69.el6.i686.rpm RPM package to ensure the BMC Remedy AR
System services start.
3. Check for libstdc++.so.5 under the /usr/lib folder.
4. Start the rpcbind process with -ioption:
# service rpcbind stop

# rpcbind -i
# service rpcbind status
5. Install the AR System server.

6. Launch the installer with the setup.sh script.
This script, which is located in the Disk1 folder, implements ulimit and other checks to prevent the
installation from failing. For more information, see the "Setting ulimit before installing BMC Remedy ITSM"
section below.
7. Install the following packages if you are installing BMC Service Request Management (which is part of the
BMC Remedy IT Service Management suite):
ncurses-devel-5.7-3.20090208.el6.i686.rpm
ncurses-libs-5.7-3.20090208.el6.i686.rpm
Preparing to install on AIX

Before running the installer in an IBM AIX environment, set data, data_hard, core, and core_hard to unlimited in
/etc/security/limits file for the user running the installer. This ensures that the installer will not fail due to data
segment size or core file size when the installer runs the arStart.sh from a shell window.
If you are installing the BMC Remedy AR System server for AIX with Oracle, the BMC Remedy AR System server
installation files must reside on a local file system and not on a network file system.
Setting ulimit before installing BMC Remedy ITSM

Before you install BMC Remedy ITSM, set the size of physical memory or the number of file descriptors. For
example:
ulimit -n unlimited
ulimit -m unlimited
Launch the installer with the setup.sh script. This script, which is located in the Disk1 folder, implements a ulimit
check to prevent the install from failing.
Using kernel tuning to increase transactions and users

Before you install the BMC Remedy AR System server, consider increasing the value of kernel parameters that
affect the BMC Remedy AR System server (or any other multi-threaded server process). This increase ensures that
BMC Remedy applications can support the expected volume of transactions and users.

For example, consider increasing the following process features:
Number of threads available for a process

Available memory — For example, the arserverd process often requires between 500 MB and 1 GB of
memory (for BMC Remedy AR System with no additional forms or applications installed).
Number of associated files or process descriptors — Descriptors should be at least 2.5 to 3 times the
number of expected concurrent connections or 1024 (whichever is greater). Examples of connections
include user logins (client or browser), the Email Engine, and custom APIs.
Contact your system administrator or operating system vendor for more information about kernel tuning.
Related topics
Installing silently
Accessing the Mid Tier Configuration Tool
Setting environment variables for UNIX environments

Setting environment variables includes setting the LD_PRELOAD variable. The BMC Remedy AR System server
might not start due to the LD_PRELOAD=/usr/lib/libumem.so environment variable entry in the
armonitor.conf file. This entry references 32-bit libraries. The installer does not add this entry during installation.
BMC Remedy AR System provides 32-bit and 64-bit programs on all UNIX platforms. The 64-bit programs cannot
load 32-bit libraries (and vice versa), so if you use the LD_PRELOAD environment variables to preload the libraries,
you must make sure that they are compatible with 32-bit and 64-bit programs.
For example, the BMC Remedy AR System server will not start on a 64-bit Solaris computer if the armonitor.conf
file contains a line like this:
Environment-variable: LD_PRELOAD=/usr/lib/libumem.so
The Solaris operating system is 64-bit, and /usr/lib/libumem.so is a 32-bit library.

A simple solution is to remove the directory part of the preload file name:
Environment-variable: LD_PRELOAD=libumem.so
The dynamic linker can find the correct version of the library for both 32-bit and 64-bit programs.
Solaris and Linux provide alternative forms:
LD_PRELOAD_32 — Affects only 32-bit dynamic linking. If this variable is set, the 32-bit dynamic linker
ignores LD_PRELOAD.
LD_PRELOAD_64 — Affects only 64-bit linking. If this variable is set, the 64-bit dynamic linker ignores
LD_PRELOAD.

Environment variables are inherited from parent processes. Therefore, if the LD_PRELOAD variables are set in the
process that starts BMC Remedy AR System (a shell, if you start manually, or a system startup script), then these
variables might interfere with the precise operation.
As an installation prerequisite, ensure that these variables are either set correctly or not set at all.
BMC Remedy Pre-Checker utility

The BMC Remedy Pre-Checker utility is a centralized framework utility that validates the environment for BMC
Remedy AR System install or upgrade. This utility also validates the BMC Remedy AR System server configuration
and customization, and generates a consolidated report.
This topic covers:
BMC Remedy Pre-Checker Utility interfaces

Use either of the following interfaces to execute the utility locally on a computer where BMC Remedy AR System
is installed. You should not run the utility remotely.
Pre-Checker Graphical User Interface (GUI) — Run prechecker-ui.bat (for Microsoft Windows) or
prechecker-ui.sh (for UNIX) to launch the Pre-Checker GUI. For more information, see To run the BMC
Remedy Pre-Checker utility through the GUI.
Pre-Checker command line — Run prechecker.bat (for Microsoft Windows) or prechecker.sh (for UNIX) to
launch the Pre-Checker command line. For more information, see To run the BMC Remedy Pre-Checker
utility through the command-line interface.
BMC Remedy Pre-Checker Utility report

An HTML report is generated once the utility is run. This report is generated from the pre-checker result file (
precheckResult.xml). This report has the following tabs:
Pre-Check Summary — This tab displays the plug-in name, the product that the plug-in belongs to, and the
status of the plug-in execution.
Errors/Warnings — This tab displays the error or warning details.
Note
Unlike the precheckResult.xml file, the HTML report is not backed up. You can generate an HTML report
with the precheckResult.xml file through the command-line interface. Use the Show Result [res]
command.

Setting the target release for the pre-checker

By default, the BMC Remedy Pre-Checker Utility is configured to run a check for the 8.1 version installation or
upgrade. If you want to run the pre-checker for a version prior to 8.1, change the following option in the
./prechecker/config/prechecker_config.xml file:
<param name=”targetVersion”>versionNumber</param>
For example:
<param name=”targetVersion”>8.0.00</param>
Or
<param name=”targetVersion”>7.6.04</param>
If this parameter is missing, the pre-checker checks for the default 8.1.00 version.
If you set a lower version and then run the pre-checker, the pre-checker skips checks that are specific to version
8.1.00. The version-dependent checks are listed in the PreCheckerMisc.doc file in ./prechecker/doc.
To obtain the BMC Remedy Pre-Checker Utility

The precheckerversionNumber_buildNumber.zip is bundled with the BMC Remedy AR System Server installation
zip. For information about how to obtain the files that you need for installation, see Downloading the installation
files.
Note
Make sure that the value of JAVA_HOME is set correctly. Use Java 1.6 or above.
To run the BMC Remedy Pre-Checker Utility through the GUI
1. Run prechecker-ui.bat (for Microsoft Windows) or prechecker-ui.sh (for UNIX).

The following screen is displayed:

Note
For UNIX, provide executable permissions to prechecker-ui.sh. Use any X-Server utility (for
example, MobaXterm) to start the pre-checker GUI.
2. Complete the fields that require inputs.

The following fields are displayed:
Field Description
Name
Load Name and location of the input configuration file that contains the framework configuration and information about the
Pre-Check pre-checker plug-ins. By default, the value of this field is the name and location of the OOTB configuration file. Click Browse
Config to change the file name and location.
File
Note: BMC recommends that you run the utility with the default configuration file.
Load The location where the result file is created. Click Browse to change the default location of the result file. The existing result
Existing file can also be loaded to see the status of last run.
Result File
AR Server The BMC Remedy AR System server name.

Field Description
Name
AR User The BMC Remedy AR System server user name.
Click Edit to open the AR Server Configuration window where you can change the values of the AR Server and AR User fields.
(You must have Administrator credentials to log in.) The following fields are displayed in the AR Server Configuration window:
AR Server — The BMC Remedy AR System server name.
Port — The port number for the BMC Remedy AR System server.
User — The BMC Remedy AR System server user name.
Password — The BMC Remedy AR System server password.
Auth String — The authentication string for BMC Remedy AR System server.
DB Host The BMC Remedy AR System database host name.
DB Type The BMC Remedy AR System database type.
Click Edit to open the DB Configuration window where you can change the values of the DB Host and DB Type fields. These
field values are required for the database compatibility check, which is optional. (These values are not validated on this screen,
but they are validated during the database compatibility check.) The following fields are displayed in the DB Configuration
window:
Oracle, MS-SQL, DB2, or Sybase — Select the required database from these options.
Unicode — Select this option for a unicode database.
Windows Authentication or SQL Authentication — Select either of this option for authentication.
Host Name — The BMC Remedy AR System server host name.
DB Instance Name — The name of the database instance.
AR System DB Name — The BMC Remedy AR System database name.
User — The BMC Remedy AR System server user name.
Temp Dir Location of the temporary directory. A mandatory input for BMC Remedy IT Service Management Suite (ITSM) and Service
Level Management (SLM) products. If you do not provide this path, this check fails.
AR Install The BMC Remedy AR System installation directory.

Dir You must specify this path for fresh installation. However, this is optional for the upgrade process since the utility
automatically finds this path by querying the BMC Remedy AR System server.
Products Displays a list of products for which the utility is executed.

Click Edit to open the Pre-check Product List window where you can edit the default product list. Make sure that at least one
product is selected. By default, all the products are selected, except SSI. You can choose from the following products:
ARS — BMC Remedy AR System.
ITSM — BMC Remedy IT Service Management Suite.
SLM — Service Level Management.
SRM — Service Request Management.
SSI — BMC Remedy ITSM Preconfigured Stack Installer.
The pre-checker configuration is saved in the prechecker_config.xml file. If you change the configuration,
the configuration file is saved as a new file, and subsequent changes are made to that file. (The original
configuration file that is shipped with BMC Remedy AR System is backed up as a separate file.)
3. Click Next to open a window that displays all the available checks based on the inputs that you provided in
the previous window.
Note

3.
When you click Next, the AR Server, Temp Dir, and AR Install Dir fields are validated. If an error
occurs, you must resolve it before going to the next screen.
The summary of some of the inputs is displayed in a read-only mode at the top of this window. The
Summary tab displays the pre-check name, product for which the check will be executed, and the status of
the checks.
4. Select the required pre-checks and click Run to execute the selected checks.
After the checks are executed, if all the checks pass, no messages are displayed in the Errors/Warnings tab.
If there are errors or warnings, they are displayed in detail in the Errors/Warnings tab. Additionally, the
Hints column contains links to helpful information about errors that occur.
For example, the Object Reservation check reports errors as shown below:

The results are stored in an XML file (precheckResult.xml) in the prechecker folder. Even if you close the
GUI session or restart the system, you can still view the status of the last pre-checker run by loading this
XML file.
If you immediately re-run the utility, the precheckResult.xml file is overwritten. If you re-run the checks
after you click Prev or if you close the utility and re-open it, the existing result file is backed up by
appending the time stamp to the name, and the new result file is created with the updated time stamp.
To run the BMC Remedy Pre-Checker Utility through the command-line interface
1. Run prechecker.bat (for Microsoft Windows) or prechecker.sh (for UNIX).
Note
For UNIX, provide executable permissions to prechecker.sh.
2. In the command-line window, provide the required inputs using the commands given in the following
table:
Command Description

2.
Command Description
AR Login Enter the following BMC Remedy AR System configuration details:

[log] Auth String — The authentication string for BMC Remedy AR System server.
User Name — The BMC Remedy AR System server user name.
AR Server — The BMC Remedy AR System server name.
This is a mandatory input required to run majority of checks.
DB Login [db] Enter the following database compatibility information:

MS-SQL (1), Oracle (2), DB2 (3), or Sybase (4) — Select the required database from these options.
Host Name — The BMC Remedy AR System server host name.
TCP Port — The port number for the BMC Remedy AR System server.
DB Instance Name — The name of the database instance.
AR System DB Name — The BMC Remedy AR System database name.
Windows Authentication or SQL Authentication — Select either of this option for authentication.
Unicode — Select this option for a unicode database.
DB User — The BMC Remedy AR System server user name.
Input Config Allows changing the name and location of the input configuration file that contains the framework configuration and
File [f] information about the pre-check plug-ins. By default, the value of this field is the name and location of the OOTB
configuration file.
Note: BMC recommends that you run the utility with the default configuration file.
Result File [rf] Allows changing the name and location of the result file. This is an optional input. By default, the pre-checker result file is
created in the prechecker folder with name as precheckResult.xml.
Path Allows changing the location of the temporary directory (a mandatory input for BMC Remedy IT Service Management Suite
(AR/Temp) (ITSM) and Service Level Management (SLM) products) and the BMC Remedy AR System installation directory (an optional
[path] input).
Report Mode Allows changing the report mode to info, warning (default), or error. Based on the report mode, the error details are
[rmode] displayed. If the report mode is set to info, all messages are displayed. If the report mode is set to warning, the error details
display warnings and errors and the info messages are ignored.
Set Plugin Allows setting product types. First, make sure that you execute the Load Configuration ([lc]) command, so that the existing
Type List [spt] product list is displayed by the ([spt]) command. Select any of the following products by entering 1 or deselect by entering
0:
ARS — BMC Remedy AR System.
ITSM — BMC Remedy IT Service Management Suite.
SLM — Service Level Management.
SRM — Service Request Management.
SSI — BMC Remedy ITSM Preconfigured Stack installer.
Run Test Executes the selected checks. The options are:

[run] 0 — Run All (All the checks are executed and a result file is generated.)
1 — Run Failed (If an earlier result file is present, only failed checks from the earlier run are executed; if no earlier
result file is present or no failed checks are found, no action is taken.)
2 — Run by Name. (Specific checks can be executed. To view the configured plug-in names, run the Get List Plugin
[glp] command.
Show Result Displays the result from the last run. The following options are displayed:
[res] 0— If you select this option, the following sub-options are displayed on the screen:
0 — The pre-checker summary is displayed on the screen, including the pre-check name, product, and the
status.

Command Description
1 — Displays the detailed information about all the failed checks. This is same output that is displayed on the
Errors/Warning tab of the GUI.
2 — Results of specific checks are displayed by providing the name of the pre-check.
1 — Pre-checker generates the HTML report of the last run and the file path is displayed on the screen. This is the
same report that can also be generated from the GUI.
Note: The pre-checker HTML report must be started from the same folder where it is created as it has a dependency
on the prechecker/etc directory.
Encrypt Enables you to encrypt the AR System server password or the database user password and display the encrypted string. The
Password [ep] command enables you to add the encrypted string to the input configuration file manually.
Load Loads the existing pre-checker configuration. This command is not required to run the checks; however, the following
Configuration commands have dependency on the [lc] command:
[lc] To get the existing plug-in types (products) or to get the list of configured plug-in
names.
For the [run] command, the pre-checker framework first loads the configuration and
then runs the checks.
Load Result Loads the existing result file, if present. If you do not provide any file path, the command searches and loads the default file
File [lr] with name precheckResult.xml; else the command is ignored. To re-run any failed check, you must load the existing result
file first and then run the failed checks.
Get List Displays a list of all the configured plug-ins.

Plugins [glp]
Note: Execute the [lc] command before executing the [glp] command.
Get List Displays all the products for which the pre-checker plug-ins are configured.
Plugin Types
[glt] Note: Execute the [lc] command before executing the [glt] command.
Sending a report with Pre-Check results

When you run the BMC Remedy Pre-Checker Utility, an HTML report is generated and placed in the
./prechecker/result folder. You can use pre-checker results to improve your interaction with BMC Support or
other support service providers. You must open the HTML report from the ./prechecker/result folder because the
report has a dependency on the ./prechecker/etc folder.
Setting the report mode

The reports that the BMC Remedy Pre-Checker Utility generates have these modes:
info – Displays all messages (informational, warnings, and errors) in the report
warn (the default) – Displays errors and warning in the report.
error – Displays only errors, but not warnings, in the report
To change the mode for a report
1. Open the prechecker_config.xml file.

2. Change the following parameter:

2.
<param name=”reportMode”>mode</param>
For example:
<param name=”reportMode”>error</param>
Generating log files

A log file is generated and placed in ./prechecker/Logs. By default, logs are generated at the INFO level.
To change the level to DEBUG, set the following line in the ./prechecker/log4j.properties file:
log4j.logger.com.bmc.arsys.prechecker.framework.service.
impl.ARPrecheckerFrameworkServiceImpl=DEBUG
11.1.10 Preparing your components and applications

Use the following topics to prepare your BMC Remedy AR System components and applications:

Performing a new installation
Preparing to install web services

If you select the AR System Server option in the installer, it installs files and forms that enable the plug-in server to
issue remote procedure calls (RPCs).
To use web services for integrations among the product and third-party applications
To make sure that web services are installed properly
To use web services for integrations among the product and third-party applications
1. Install Java SE 1.6 (or later) before installing or upgrading the application.
Operating system Vendor Minimum required version
Windows, Solaris, Linux (Red Hat and SuSE) Oracle Java SE 6 Update 17
HP-UX HP HP-UX 11i Java SE 6.0.06
AIX IBM IBM Java 6 SR7
2. Choose the web service option when you install BMC Remedy AR System.
If you install Java after installing BMC Remedy AR System, or do not select the web service option during
installation of BMC Remedy AR ;System, you must reinstall BMC Remedy AR System.

2.
Note
The first time you use the web service after installation, you must access the Web Service Settings
page in the Mid Tier Configuration Tool for this AR System server and enter Demo or another user
name in the Anonymous User Name field. Otherwise, the following error message appears: Error
149: A user name must be supplied....
To make sure that web services are installed properly

If the Java jvm.dll library is not added to the PATH environment variable, the following error is displayed at the
end of the installation procedure:
arplugin can't find jvm.dll
You can resolve this in either of the following ways:
Enter the Java jvm.dll library path in the PATH environment variable before installing the BMC Remedy AR
System server. The Java jvm.dll library path is found in the RuntimeLib tag of the Registry:
HKLM\SOFTWARE\JavaSoft\Java Runtime Environment\1.5
Reboot your system after the installation. When you install web services, the installer enters the Java
jvm.dll path, but you must reboot before the change takes effect.
Preparing to install BMC Remedy Mid Tier

Before installing BMC Remedy Mid Tier, complete the following steps:
1. To enable the use of the Java Virtual Machine Monitoring, Troubleshooting, and Profiling Tool (jvisualvm
), add the following Java Management Extension (JMX) options to the java command:
-Dcom.sun.management.jmxremote.port=<portNumber>
-Dcom.sun.management.jmxremote.authenticate=false
2. So that Java automatically generates Java heap dumps for troubleshooting purposes, add the following
Java parameter to the Java options file:
-XX:+HeapDumpOnOutOfMemoryError
3. If you will be installing BMC Remedy Mid Tier with IIS as the web server and Tomcat as the JSP engine,
make sure that you have administrator rights.
4. If you will be installing BMC Remedy Mid Tier with IIS 7.x and Tomcat6.x or 7.x, in the Internet Information
Service Manager, select the following options before installing the mid tier:

4.
Httpd redirect
ISAPI and CGI Restrictions
ISAPI Filters

Before installing Email Engine (which is installed when you select the AR System Server option in the installer),
perform the following tasks:
1. Install the Java runtime environment (JRE) on the machine that will run Email Engine.
2. Complete the pre-installation tasks for your computer environment. For more information, see:
Email Engine pre-installation tasks -- Windows
Email Engine pre-installation tasks -- UNIX
Email Engine pre-installation tasks -- Windows

Complete the following tasks before you install the Email Engine on Microsoft Windows.
Environment variables
Before you start the installation, set the PATH environment variable to access the latest JRE directory. Make sure
that you include the bin directory of your Java installation (for example, C:\Program Files\Java\jre7\bin).
Otherwise, the Email Engine might not start correctly after you complete the installation.
Secure Socket Layer option

Determine whether your environment requires the Secure Socket Layer (SSL) option.
MAPI and MBOX mail protocols

This section explains how to set up the system if you are using the MAPI or MBOX mail protocols.
Note
The MAPI protocol for incoming and outgoing mail is disabled for 64-bit JVM.
You do not need to prepare the system if you are using the IMAP4, POP3, or SMTP protocols.
Note
MAPI users (for 32-bit JVM only): If you are upgrading your Email Engine from a previous Email Engine
version and you do not need to change your existing MAPI configuration information, you can skip this
section.
To prepare for MAPI

Note
You must be a Windows domain administrator or Microsoft Exchange administrator to perform these
steps.
1. Install the Exchange server at one of the following locations:

The same domain as the Email Engine domain
A domain with the appropriate trust relationship to the Email Engine domain
2. Install the Exchange client on the computer on which you plan to install the Email Engine.
The client contains the libraries that the email protocols will use.
For more information about the compatible clients for the Email Engine, see Checking system
3. Create and configure a Windows domain account:
a. Create a Windows domain user account at one of the following locations:
On the same domain as the Email Engine
On a domain with appropriate trust relationships
Note the name of the users:
Windows — Incoming mailbox: Server user
Windows — MAPI logon settings: Windows NT user
b. Assign group and domain membership to the domain user account at one of the following locations:
On the same domain as the Email Engine — Give group membership to the local
administrator's group [HTMLUATarsPlanAndInstallFinal2:active directories only].
On a domain with appropriate trust relationships — Give domain membership to the Email
Engine domain or the Exchange Server domain.
c. Grant the domain user the following advanced rights on the computer where you plan to install the
Email Engine:
Act as part of the operating system
Log on as a service
Note
(Active directories only) Make sure that the Effective Rights option shares the correct
advanced rights.
4. Create and configure an Exchange profile:

a. Log in as the domain user on the computer where you plan to install the Email Engine, and create an
Exchange email profile.
b. Configure the profile to:
Work exclusively with the Email Engine.

b.
Be accessible by the Windows domain user account you created earlier in the "Create and
configure a Windows domain account" step.
Point to the Exchange server and mailbox.
5. Check your profile setup.
6. From the computer where you plan to install the Email Engine, log on as the domain user that you created
earlier.
7. Using the Microsoft Outlook client, send and receive emails to verify that the Exchange profile is
functioning correctly.
To prepare the system for using the MBOX protocol
1. Create an email account and an account user.

2. Give the email account user full read and write permissions to relevant directories and files.
3. Verify that the account can send and receive emails.
Related topics
Configuring SSL for the email engine
Setting up UNIX mailboxes
Email Engine pre-installation tasks -- UNIX

Complete the following tasks before you install the Email Engine on UNIX.
Setting up UNIX mailboxes

As superuser, use the following procedure to establish a mailbox address for the UNIX Email Engine. These
instructions are meant only as generic guidelines. If you have questions about the implementation, consult your
UNIX system administrator for details.
To set up UNIX mailboxes
1. Set up an ARSystem user account in the /etc/passwd file. For example (the new entry is the last line):
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.
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 choose a different name, if required.

Verify this step for your UNIX computer. The name 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. See your UNIX system administration documentation or UNIX system
administrator if you have questions or problems. The /usr/spool/mail email directory 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 (HPUX), by
using 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 HPUX, it is mail. To verify the correct group name to use, check the group name for the
mail directory by using the ls -ldg command.
5. Change the mailbox permissions to provide read and write access for all, as in the following example:
# 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

Installing as a non-root user
Note
If you are installing the entire stack as a non-root user, you must provide the non-root user permission
to the MBOX mail directory and all its contents.
After installing the Email Engine, review the manualInstall.txt file and modify the logging. properties and
javamail.providers files as described in mannulInstall.txt file which is located in <ARSystemInstallDir>
/nonRootUserDirectory/<serverName>/<manualInstall>.
Related topics
Preparing the UNIX environment (See "Preparing to install as a non-root user")
Preparing to install BMC Remedy Developer Studio

When planning to install BMC Remedy Developer Studio, remember these tips:
Install the Java Runtime Environment (JRE) on the computer that will run BMC Remedy Developer Studio.
If you are connecting to servers in different locales, install a multi-language version of the JRE.
BMC Remedy Developer Studio requires that the maximum memory setting of the
<DeveloperStudioInstallationDir>\devstudio.ini file be at least 512 MB of RAM. For medium-sized
applications that have a few thousand forms and workflow objects, this configuration is enough — both for
application development and for using Remote Desktop Protocol (RDP) features. However, for large scale
applications, such as ITSM, this configuration might be enough only for application development, and not
sufficient for using RDP features. In such cases, you can increase the maximum memory to 1024 MB.
Increasing memory size might slow the startup time of BMC Remedy Developer Studio, so it is best to
increase memory size only when required.
If you have at least 512 MB of RAM, but you receive errors regarding space issues (for example, if you try to
open many objects at once), change the -Xmx512m setting in the devstudio.ini file to increase the space.
For example, if you have at least 1 GB, change this setting to -Xmx1024m.
The Localization Toolkit option is available by default.
Related topics
Using the localization toolkit to localize your applications
Preparing the AR System server to install BMC Atrium Core and other BMC
applications
The BMC Atrium Core installer prompts you to enter information about the BMC Remedy AR System server. The
following steps will help you prepare your system to install the BMC Atrium Core features on the AR System
server.

1. Review relevant technical bulletins and patches on the BMC Support site before you install BMC Atrium
Core.
2. Review online documentation and white papers.
Review the AR System online documentation.
Review the BMC Atrium Core online documentation.
Check the BMC Support site for white papers, such as Performance Tuning for Business Service
Management, that might contain information to help you optimize your environment for installation.
3. Make sure that the AR System server is correctly licensed.
BMC Atrium Core requires an AR System server with a multi-server license.
4. If you want to install the BMC Remedy ITSM Suite applications, and if you are using a different user, make
sure that BMC Atrium Core user is a member of the Administrator group in the BMC Remedy AR System
User form.
5. Temporarily disable the escalations on the AR System server.
Make sure that BMC Remedy AR System is set to Disable Escalations. The BMC Atrium Core installation
does not complete successfully if BMC Remedy AR System is not set to Disable Escalations.
a. Log on to your AR System server.
b. Open the AR System Administration Console.
c. Choose System > General > Server Information.
d. In the Server Information form, click the Configuration tab.
e. Select the Disable Escalations option.
f. Click OK.
6. Disable temporarily AR System server encryption.
Installation of BMC Atrium Core on an encrypted AR System server is not supported. You can enable
encryption after installation.
a. Log on to the AR System server.
b. Open the AR System Administration Console.
c. Choose System > General > Server Information.
d. From the Server Information form, click the Encryption tab.
e. In the New Encryption Settings area, choose Disabled in the Security Policy list, and click Apply.
f. Restart the AR System server.
Note
Re-enable escalations and encryption when you finish installing all the BMC applications.
7. Because BMC Remedy AR System can restrict the size of attachments, verify that your setting for
attachments is set to at least 500k during the installation.
You can change this setting to a smaller limit after the installation (the default is zero).
8. Set the Next Request ID Block Size parameter to 100.
BMC recommends setting the Next Request ID Block Size parameter to 100 to improve performance when
creating entries on an AR System server configured for multi-threading. This includes creating instances in

8.
BMC Atrium CMDB, such as during bulk data load from a discovery application or a reconciliation merge or
copy activity.
Warning
If you have custom workflow that depends on consecutive request IDs, a Next Request ID Block
Size greater than 1 causes inconsistent results.
a. Open the AR System Application Console.

b. Select System > General > Server Information.
c. Click the Platform tab.
d. Enter Server Name Alias, and click Apply to retrieve the server information.
e. Click the Configuration tab.
f. In the Next Request ID Block Size field, type 100.
g. Click OK.
9. Set the size limit for the AR System database.
If you do not set size limits correctly, the database size limit might be reached.
To prevent BMC Remedy AR System from reaching the size limit of the database, perform the following
changes:
For Microsoft Windows using SQL Server — Open SQL Server Enterprise Manager and select the
Automatically Grow File option for your AR System database.
For UNIX using Oracle — Execute the following SQL statement as the system user:
ALTER DATABASE DATAFILE 'OracleHome/DATABASE/ARSYS' AUTOEXTEND ON NEXT 100M
MAXSIZE UNLIMITED;
Note
You do not need to commit or restart the server after you make the changes.
10. Set the JVM heap size for the Tomcat server.
If you use an existing Tomcat server instance, BMC recommends setting the JVM heap size of Tomcat
servers to a minimum value of 1024 MB and a permanent generation size of 256 MB. Otherwise, you might
see OutOfMemory errors and a failure to publish web services to the BMC Atrium Core Registry.
Setting the JVM heap size for a Windows computer
a. Stop the Tomcat server.
b. Run the tomcat6w application to open the Apache Tomcat Tomcat6 Properties dialog box.
You can find tomcat6w.exe in the C:\Program Files \Apache Software
Foundation\Tomcat6.0\bin folder.
c. Click the Java tab.
d. Set Maximum Memory Pool to 2048 MB or higher.
e.
e. In the Java Options list, set XX:MaxPermSize to 256 MB or higher.
Note
If you do not find XX:MaxPermSize in this list, look for XX:PermSize. Set this
parameter to 256 MB or higher. If you cannot find either of these parameters in the
Java Options list, add either XX:PermSize or XX:MaxPermSize using the following
syntax:
-XX:MaxPermSize=256m or -XXPermSize=256m.
f. Click Apply and then click OK.

g. Start the Tomcat server.
Setting the JVM heap size for a UNIX computer
a. Stop the Tomcat server.
b. Locate the catalina.sh file in the tomcat\bin directory.
c. Export the following parameter in the catalina.sh file:
export CATALINA_OPTS="-Xms1536m -Xmx2048m -XX:PermSize=128m
-XX:MaxPermSize=256m"
d. Start the Tomcat server.
11. On IBM AIX, enable the full installation.
When installing on AIX, set the ncargs system attribute to 32 or higher to ensure that all directories are
installed.
a. Check your current ncargs value by executing this command:
lsattr -E -l sys0 -a ncargs
b. If ncargs is not set to a value of 32 or higher, set it to 32 (or a higher value) by typing this command:
chdev -l sys0 -a ncargs=32
12. If you are using a Linux or a UNIX computer, and you choose to run setup.bin in place of setup.sh, you
must specify the limit on the number of file descriptors (5000) a process may have by using the ulimit
command. Use the following syntax: ulimit -n 5000.
For non-root user, make sure that the "open files" limit of the shell is set to 16384. For this, you must
modify the /etc/security/limits.conf file.
On AIX computers, specify the limit on the number of file descriptors (unlimited) a process may have by
using the following syntax: ulimit -n unlimited.
13. Disable applications running on port 12333.
To prevent port conflicts with port 12333, disable any applications running on port 12333 before you
install. After the installation is complete, programs can resume using port 12333.
Note

BMC Atrium Core is installed using InstallAnywhere, a multi-platform software deployment

solution. Because InstallAnywhere uses port 12333 for installing BMC Atrium Core, you must free
the port before you begin with the installations.
14. Verify if the bc utility is present on UNIX.

Before you begin to install BMC Atrium Core, make sure that the bc utility is installed in your environment.
When you begin to install BMC Atrium Core, the installer verifies that the bc utility exists in your
environment. You will not be able to continue with the installation if the utility is not present.
15. For improved performance if you are using the BMC Remedy ITSM Suite applications with the BMC Atrium
CMDB, run your BMC Remedy AR System server on a private RPC socket with the following values:
Windows:
RE-RPC-Socket 390698 (for the Reconciliation Engine)
Private-RPC-Socket 390698 10 10 (for the BMC Remedy AR System Server)
UNIX:
RE-RPC-Socket 390698 (for the Reconciliation Engine)
Private-RPC-Socket 390698 6 6 (for the AR System server)
Note
You can also use port number 390699, but the port numbers for the BMC Remedy
Reconciliation Engine and the AR System server must match.
16. To allow BMC Service Request Management run on a private server, configure the BMC Remedy AR System
server to run on a private server first. For more information about private servers, see Configuring the AR
Server Settings page.
17. If you configured the AREA plug-ins after installing BMC Remedy AR System, set the value of the
Authentication-Chaining-Mode parameter in the ar.cfg (ar.conf) file to ARS - AREA if the current value is
AREA - ARS.
Note
Restart the server before installing or upgrading the BMC Remedy ITSM Suite.
After the upgrade is complete, restore Authentication-Chaining-Mode to its original setting.
18. If you have changed the AR tcp port, update the port number details in the ar.cfg and the
ARSystemInstalledConfiguration.xml.

11.2 Performing a new installation

The BMC Remedy AR System installer enables you to deploy BMC products in your IT environment.
In this topic:
Choosing products
Minimum set of features need to install other BMC products
To install BMC Remedy AR System
To install BMC Remedy Mid Tier
The suite installer guides you step-by-step through the installation process. When you start the installer, you can
choose one or more features to install at one time. Because certain applications depend on a specific set of
features, you need to run the installer multiple times to install all of the features in the solution. For example, you
first install the AR System server on one computer and then run the installer a second time to install the mid tier
on a different computer.
Recommendation
To reduce installation time significantly, do not install the products over the wide area network
(WAN).
To avoid configuration problems, accept the default values displayed in the installer unless you
have a valid reason to modify them.
For best results, install BMC Remedy Mid Tier on a separate computer from the BMC Remedy AR
System server.
11.2.1 Choosing products

When you run the suite installer, you are asked to select the type of installation you want to perform.
AR System Servers — Installs the BMC Remedy AR System server, Approval Server, Assignment Engine,
Email Engine, and Flashboards.
Also installs plug-ins: AREA LDAP, ARDBC, Web Services, SNMP, and FTS.
AR System Mid-Tier — Installs the BMC Remedy Mid Tier only (and Crystal Web Application if BOXI
installation is available).
AR System Clients — Installs BMC Developer Studio (and the Localization Toolkit), BMC Remedy Data
Import, and Atrium Integrator Spoon.
This option is for Microsoft Windows only; it is not available for Linux or UNIX.

Note
BMC supports only the Atrium Integrator Spoon version that is shipped with the installer. Do not
install any other version of Atrium Integrator Spoon.
11.2.2 Minimum set of features need to install other BMC products

The following table lists the minimum set of features you need when installing other BMC products.
BMC Application Minimum set of features
BMC Atrium Core

AR System Server
Approval Server
Assignment Engine
Atrium Integrator Spoon
BMC ITSM
AR System Server
Approval Server
Assignment Engine
Full Text Search (FTS) Configuration if you plan to install BMC Knowledge Management

AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine
11.2.3 To install BMC Remedy AR System

1. Download the BMC Remedy AR System installer from EPD, or navigate to the installation directory on the
DVD.
2. Unzip the suite installer (for example, ARSuiteKitWindows.zip or ARSuiteKitLinux.zip).
4. Start the installer.
For UNIX, log in as root and run setup.sh.
7.
7. On the Products selection panel, perform the following actions:

a. Select Install.
b. Select AR System Servers and de-select the other options.
The installer validates the system resources of your computer and displays a list of available features.
c. Navigate to the directory in which you want to install the BMC Remedy AR System application.
The default locations are C:\Program Files\BMC Software\ARSystem (Windows) and
/opt/bmc/ARSystem (UNIX or Linux).
d. Click Next.
8. Enter the values from the planning worksheet for the features that you want to install.
After you have entered the required information, the installer validates your input, and then the Installation
Preview panel appears, listing the product and product features that will be installed.
Note
Run Sanity Check is selected by default. BMC recommends that you run the additional validation
tests of your installation.
9. Click Next.
The installer installs the AR System features you have selected. After post-installation cleanup, a summary
of the installation appears.
10. Click View Log to review the SEVERE error messages or warnings in the product installer log.
See whether errors are due to network, host, or other environment-related issues. You can view a log file
of the installation:
12. Click Done to exit the AR System installer.
11.2.4 To install BMC Remedy Mid Tier

1. Download the BMC Remedy AR System installer on a computer other than where you installed the AR
System server.
2. Unzip the suite installer and open the ARSuiteKitWindow folder.
3. Open the Disk 1 folder.
a. Select Install.
b.
7.
b. Select AR System Mid-Tier and de-select the other options.

/opt/bmc/ARSystem (UNIX and Linux).
d. Click Next.
8. Enter the values from the planning worksheet for the Mid Tier.
After you have entered the required information, the installer validates your inputs, and then the
Installation Preview panel appears, listing the product and product features that will be installed.
9. Click Next.
After post-installation cleanup, a summary of the installation appears.
10. Click View Log to review the SEVERE error messages in the product installer log.
12. Open the BMC Remedy Mid Tier Configuration Tool (http://<midTierServer>/arsys/shared/config/config.jsp
).
The default password is arsystem.
13. Click General Settings.
14. Select the AR System server as the authentication server, and then click Save Changes.
15. Log out.

11.2.6 Where to go from here

Post-installation procedures
11.3 Installing a server group

This topic describes the installation flow required to install a server group for BMC Remedy AR System, BMC
Atrium Core, and other BMC products.

Important
Before beginning your installation, review the Planning and Planning a server group installation
topics.
If you are performing a new installation, make sure that the server is clean. A clean system is one
that has not had any BMC Remedy software previously installed on it. If BMC Remedy software
was installed on one or more of your servers, it is recommended to re-image the system back to a
state with no BMC Remedy products installed.
If you are not using a load balancer for your server group, make sure that your network is
configured to resolve the server name. For information about load balancers and BMC Remedy AR
System, see Configuring a hardware load balancer with BMC Remedy AR System.
See the following video for an overview about installing server groups.
Watch video on YouTube at http://www.youtube.com/watch?v=cUAjJ2zxCRk
11.3.1 Preparing to install your server group

Step Task
Note

Step Task

a. Review the the hardware requirements for the computers in your server group.
b. Review the software requirements for the computers in your server group.
c. Review the 32-bit and 64-bit requirements for the computers in your server group.
3 Prepare your databases before you start the server group installation.
Tip
Identify the database that the server group will share, as well as the database login information and database settings. All your AR
System servers will connect to this database. You need this information before you install the first AR System server.
4 Obtain licenses for the BMC AR System server and other BMC products.
7 Prepare your environment and prepare your components and applications
11.3.2 Server group installation flow

Step Task
8 Install the first AR System server.

This step includes:
Installing the BMC Remedy Mid Tier on a separate computer. You use the Mid Tier to configure the AR System server.
Activating licenses on the server
Installing additional BMC Remedy products (for example, BMC Atrium Core or BMC Remedy IT Service Management)
9 Configure the first server to be a server group member.
10 Test and confirm that the first server is working properly.
11 Install the next server in the server group.

The installer automatically selects the server group or upgrade option based on the administrative operations of the BMC Remedy AR System
server and the database version under the controlled table. For example, if the administrative operations are enabled on the server and the
database version is an older version, the installer selects upgrade (forms are imported); otherwise the installer selects server group (forms are
not imported).
12 Configure the next server for the server group.
13 Test and confirm that the current server is working properly.
Note
Repeat steps 11, 12, and 13 for each subsequent server in the group.


Configuring server groups
Installing BMC Remedy IT Service Management in a server group to install the ITSM Suite in a server group
11.3.4 Installing the first AR System server

This section describes how to install the first server in the server group installation. These procedures assume that
you have downloaded the software and are ready to go.
Important
Identify the database and IP address that the server group will share, as well as the database login
information and database settings. All your AR System servers will connect to this database.
On Microsoft Windows, you must be logged on as a domain user on the server rather than a local
user when performing installations. The installer needs to copy files to the database server. On
UNIX, you must also be logged on with a user who has permissions to copy files to the database
server.
To install BMC applications on the primary server

Read through the instructions for each step carefully before attempting to perform the procedures.
1. Install the BMC Remedy AR System server.

The first server needs to be set up and configured as a standalone server when installed. Following the
installation, the server is manually configured to be a server group member.
2. Back up the BMC Remedy AR System database.
This enables you to restore BMC Remedy AR System to its pre-installation state if you encounter problems.

2.
Note
The product workflow is installed in overwrite mode.
3. Install the BMC Remedy Mid Tier installation on the computer that hosts the web server.
Identify the computer that you will use to host the web server and install the mid tier there. You use the
mid tier to:
Confirm that the product installations are working correctly
Access the server administration console to perform configuration options
Access all the other AR System servers in your server group
Note
BMC recommends that you install the mid tier on a different computer than the computer
where you installed the AR System server. Depending on the environment and performance
considerations, you can install the mid tier on the same system as the AR System server, but
this is not recommended except in test environments, not production environments.
4. Test that the installation is working correctly by opening the mid tier and confirming that the forms render
in the mid tier interface.
5. Activate the Remedy AR Server License on the first server.
6. Install other BMC Remedy products on the first server (when repeating step 5, make sure to install the
correct product license for the specific product being installed).
BMC recommends that you install the products in the following order:
BMC Atrium Core
Related topics
Installing AR System in your server group

Installing the BMC Remedy Mid Tier
Obtaining BMC Remedy license keys (server groups)
Testing the mid tier in your server group

Configuring the first server to be a server group member


In this topic:
Choosing products
The suite installer guides you step-by-step through the installation process. When you start the installer, you can
choose one or more features to install at one time. Because certain applications depend on a specific set of
features, you need to run the installer multiple times to install all of the features in the solution. For example, you
first install the AR System server on one computer and then run the installer a second time to install the mid tier
on a different computer.
Recommendation
(WAN).
System server.
Choosing products
AR System Servers — Installs the BMC Remedy AR System server, Approval Server, Assignment Engine,
Email Engine, and Flashboards.
AR System Mid-Tier — Installs the BMC Remedy Mid Tier only (and Crystal Web Application if BOXI
installation is available).
AR System Clients — Installs BMC Developer Studio (and the Localization Toolkit), BMC Remedy Data
Import, and Atrium Integrator Spoon.
This option is for Microsoft Windows only; it is not available for Linux or UNIX.
Note

BMC supports only the Atrium Integrator Spoon version that is shipped with the installer. Do not
install any other version of Atrium Integrator Spoon.

BMC Application Minimum set of features
BMC Atrium Core

AR System Server
Approval Server
Assignment Engine
BMC ITSM
AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine
DVD.
a. Select Install.
b. Select AR System Servers and de-select the other options.
c.
7.
Home b. BMC Software Confidential
/opt/bmc/ARSystem (UNIX or Linux).
d. Click Next.
8. Enter the values from the planning worksheet for the features that you want to install.
Note
9. Click Next.
System server.
2. Unzip the suite installer and open the ARSuiteKitWindow folder.
a. Select Install.
b. Select AR System Mid-Tier and de-select the other options.
/opt/bmc/ARSystem (UNIX and Linux).
d. Click Next.
8.
8. Enter the values from the planning worksheet for the Mid Tier.
After you have entered the required information, the installer validates your inputs, and then the
Installation Preview panel appears, listing the product and product features that will be installed.
9. Click Next.
).
15. Log out.
Related topics
"Preparing to install as a non-root user" in Preparing the UNIX environment
Configuring the approval servers in a server group


To make sure that the mid tier is functioning correctly, verify that you can access the configuration page and one
or more forms.
1. To open the home page, enter the following URL:
http://<hostName>:<port>/arsys/home
For example, you can enter the following URL:
http://localhost:8080/arsys/home
2. To open the configuration page, enter the following URL in the BMC Remedy Mid Tier Configuration Tool:
http://<hostName>:<port>/arsys/shared/config/config.jsp
3. Configure your preference and home page servers.

For more information, see Setting user preferences and Configuring home page preferences.
4. To open forms, enter:

4.
http://<hostName>:<port>/arsys/forms/<ARSystemServerName>/<formName>/<viewName>
The default ports are:
8080 (Tomcat)
8989 (Oracle Java System)
7001 (WebLogic)
9080 (WebSphere)
8080 (JBoss)

Obtaining BMC Remedy license keys for server groups

You must obtain a BMC Remedy license key to install the AR System server. This topic includes the following
sections:
A license key is a value that enables you to activate a license. In BMC Remedy AR System 8.1, only AR System
server licenses require keys. Each key is tied to a particular host; a unique entry for each server is therefore
required within the Add or Remove Licenses form. To request a temporary or permanent key, you must access
the BMC Support Central Site at http://www.bmc.com/support.
Key type Information required
Temporary
Support contract ID
Email address
Permanent
Support contract ID
Purchase order number
Email address
Site Name default to Support Contract ID
To access the self-service license generator, you must be active on support and have an active user login account
on the BMC Support site.
Note
If you do not know our user ID and password, contact http://www.bmc.com/support-contacts

If you purchased your AR System server license through a BMC sales representative or over the web, you can
download the product from the BMC Electronic Product Distribution (EPD) site. Access the EPD site from the
BMC Customer Support website at http://www.bmc.com/support.
To request a license key
1. Log on to BMC Support Central at http://www.bmc.com/support.

2. Click Licensing and Passwords.
3. Click Request a New License.
You can also click Request a Trail/Temporary License if needed. These licenses are valid only for 30 days.
4. Click I Agree.
5. Enter the required information for the license, for example, the purchase order number.
a. Verify that your available licensed products and features you are attempting to obtain are related
with the Support Contract ID displayed on the form. If the correct Support ID is not displayed,
contact BMC Customer Support to help manager your support IDs.
b. Select the correct AR Server version, for example, *7.1 and Higher *.
c. Enter the host ID of the AR System server.
To find the Host ID, see To determine the server host ID using the ipconfig command.
6. Select AR Server under Product Feature and enter 1 in Quantity Requested.
7. Click Request License.
Note
You can only request 1 license key at a time.
Your license key will be sent to your email address.
To add a new application license
1. From your browser, log on to BMC Remedy ITSM.

2. From the list of applications on the IT Home page, select AR System Administration > AR System
3. In the navigation pane, select System > General > Add or Remove Licenses.
The Add or Remove Licenses form appears.
4. Click Add New.
5. From the License Type field, select AR System Server.
6. Enter 1 as the number of licenses.
7. Enter the license key in the License Key field.
8. Click Save.
9. Add licenses whenever you need them from the Add or Remove Licenses page.

9.
Tip
Add only one license key per application, but you should add enough user licenses for the various
BMC Remedy ITSM applications that you are using.
a. From the list displayed, select the type of license that you want to add.
The License Type field is updated with the license type that you selected.
b. Select the number of licenses and enter the license key, if applicable.
c. Click Add New.
10. Click Generate License Usage Report to communicate license usage to your support and account
representatives.
Note
Versions 7.5.00 patch 003 and later of BMC Remedy AR System do not require keys for application
licenses; keys are required only for BMC Remedy AR System server licenses.
To determine the server host ID using the ipconfig command (Windows)
1. Open a command window on the server computer.

2. At the prompt, enter ipconfig /all.
3. Find the physical address for the server computer.
In the following screenshot, the physical address is 00-FF-B0-AB-3D-07.
BMC uses the physical address of your computer without the dashes.
4. To use the server host ID to obtain your license key, remove the dashes from the physical address.
In this example, the server host ID that BMC uses to license the AR System server is 00FFB0AB3D07.
5.
11.3.5 To determine the server host ID using the ifconfig command

(Linux)
6. Open a terminal.
7. At the prompt, enter ifconfig.
8. Record the Hardware Address. For example:
HWaddr 00:50:56:AC:04:10
9. Remove all the colons from the value and convert uppercase letters to lowercase (for example,
005056ac0410).


11.3.6 Configuring the first server to be a server group member
Before you begin

Open the text file of the servers in the server group that you previously created. It should list the entire set of
IP-Name entries. Each server must have the same set of entries containing all resolvable names for each server.
To configure the first server to be a server group member
1. Make the server a server group member.

a. In a browser, open the Home page of the first server.
b.
1.
b. Choose Administration Console > System > General > Server Information.
c. Click the Configuration tab.
d. Select the Server Group Member check box.
e. Click Apply.
2. Edit the ar.cfg file on the first server computer.
a. Open the <ARSystemInstallDir>\ARSystem\Conf\ar.cfg file in a text editor.
b. Confirm that the Server-Group-Member setting is set to T (Server-Group-Member: T).
If the setting is set to F, change it to T. If you do not see this setting, create it and set it to T.
c. Check for an entry called Server-Name. If it exists, verify that is set to a name that resolves to your
load balancer. If it is not, modify the setting's value so that it is. If the entry does not exist, create it,
and set it accordingly. For the example, the name is RemedyServerGroup.
d. Check for an entry called Server-Connect-Name. If it exists, verify that it is set to the name of the
first server. If it is not, modify the setting's value so that it is. If the entry does not exist, create it, and
set it accordingly. For the example, the name of the first AR System server is svr_grp_tst0.
e. Check for an entry called Domain-Name. If it exists, verify that it is set to the domain that resolves to
the load balancer when the Server-Name
and Domain-Name are concatenated. If it is not, modify the setting's value so that it is. If the entry
does not exist, create it, and set it accordingly. In the installation example, if the fully qualified host
name that resolves to the load balancer is test.svgroup.com, then Server-Name should be test, and
Domain-Name should be svgroup.com.
f. Create an IP-Name entry for every possible way a client could connect to all of the servers in the
server group.
Tip
Copy and paste the servers from your server list, which you created in Planning where
software is installed in server groups.
In the example scenario, the following entries are added for the first server:
IP-Name: 192.161.135.31
g. Create the same number of entries for each of your AR System servers. The example scenario uses
only two servers. The following entries are added:
IP-Name: 192.163.122.40
3.
3. Save the ar.cfg file and restart the server.
Related topics
Open the text file of the servers in the server group

Testing and confirming that the first server is working properly
11.3.7 Testing and confirming that the first server is working properly
After the server is rebooted, perform the following procedures to confirm that it is properly configured in server
group mode and that everything is working properly.
1. In a browser, open the AR System Server Group Operation Ranking form:

http://<midTierServer>:<portNumber>/arsys/forms/
<ARSystemServer>/AR+System+Server+Group+Operation+Ranking/
2. Click Search in the top-left corner to view all current rankings.
3. Verify that all of the BMC applications and components are listed, and that they are all set to Rank 1.

Installing the next AR System server in the server group
11.3.8 Installing the next AR System server in the server group
Repeat this set of procedures for each additional server, following the initial server installation.
This section describes how to install and configure the next server in the server group installation (servers B – Z).
These procedures assume that you have downloaded the software.

1. Open the mid tier on the first server and add the AR Server license for the next server.
To add the license, you can determine the server host ID by using the ipconfig /all command on
your computer to Obtaining BMC Remedy license keys.
2. Install BMC Remedy AR System.

When installing the second server and all servers afterward, the Server Group option is not displayed
because the installer automatically detects this information based on the database details provided during
installation and the installation continues. Remember that you are using a common database that the
server group shares, as well as the database login information and database settings. All your AR System
servers will connect to this database.
If you plan to use the portmapper with your server group installation, do not specify the port
number for the AR System server installation. If you specify a port number, that tells the system
that the AR System server is not using portmapper.
3. Log on to the BMC Remedy Mid Tier Configuration Tool and add the AR Server.
4. If you are using a load balancer, configure it so that it does not route traffic to the primary server during the
installation or upgrade.
5. After the AR System server is installed, install other products in the following order:
BMC Atrium Core
BMC Remedy IT Service Management
To install BMC Service Level Management on a secondary server, perform the following steps:
a. i. Run the installation.
ii.
a.
ii. When the Application Overwrite Selection panel appears, select Reinstall SLM Application and
then click Next.
iii. Verify the options and then click Next to continue the installation.

Make sure to use the server group installation method. This server group method is automatically
selected in most cases, as the products and component installations can see that the already
installed AR Server is setup as a server group. Each of the product installations handle that a little
differently and most of them display some type of message indicating that they recognize the server
group and are installing as such.
Verify that each product or component is working before you attempt to install another product or
component.
6. To install the next server, go back to step 1, and repeat the process.
Repeat this until all servers are installed and configured.
If this is the last server you are installing, you are now finished.
If the product you are installing was already installed and licensed on the first server, you do not
need to install a license for it. With server groups, each license (other than the AR System server
license) needs to be installed only once.
Related topics
Licensing for server groups
Adding or deleting a server

Configuring the next server for the server group
11.3.9 Configuring the next server for the server group

Before you begin

Open the text file of the servers in the server group that you previously created. It should list the entire set of
IP-Name entries. Each server must have the same set of entries containing all resolvable names for each server.
To configure the next server for the server group
1. Confirm that the server is a server group member.

a. In a browser, open the Home page of the first server.
b. Choose Administration Console > System > General > System Information.
c. Click the Configuration tab.
d. Verify that the Server Group Member check box is selected. If it is not, select it.
e. Click Apply.
2. Edit the ar.cfg file on the second (third, fourth, and so on) server computers.
a. On a Microsoft Windows server, open the <ARSystemInstallDir>\ARSystem\Conf\ar.cfg file in a text
editor.
b. Confirm that the Server-Group-Member setting is set to T (Server-Group-Member: T).
If the setting is set to F, change it to T. If you do not see this setting, create it and set it to T.
c. Check for an entry called Server-Name.
If it exists, verify that is set to a name that resolves to your load balancer. If it does not, modify the
setting's value so that it does. If the entry does not exist, create it, and set it accordingly. For the
installation test example, the name is RemedyServerGroup.
d. Check for an entry called Server-Connect-Name.
If it exists, verify that it is set to the unique name of the second server (or third, or forth, and so on). If
it is not, modify the setting's value so that it is. If the entry does not exist, create it, and set
accordingly. For the installation test example, the name of the second AR System server is
svr_grp_tst3.
e. Check for an entry called Domain-Name.
If it exists, verify that it is set to the lowest subdomain name used in your implementation. If it is not,
modify the setting's value so that it is. If the entry does not exist, create it, and set it accordingly. For
the example, the lowest subdomain name is test.svgroup.com.
f.
f. Open the text file that you created with the IP-Name entries for all servers in the server group, when
you were configuring the first server.
g. Copy and paste the text with the IP-Name entries for all servers into ar.cfg.
h. Save the ar.cfg file and restart the server.
Related topics
Opening the text file of the servers in the server group

Testing and confirming that the current server is working properly
11.3.10 Configuring the approval servers in a server group

In an AR System server group environment, two or more servers share the same database. If one server stops
working, another one continues to process approvals.
In a server group environment, when an AR System server becomes unavailable, the newly active AR System
server performs the following actions:
Sets Approval-Server-Suspended: T in the ar.cfg (ar.conf) file on the unavailable server. This indicates that
the approval server on that AR System server is unavailable for processing.
Sets Approval-Server-Suspended: F in the local ar.cfg (ar.conf) file. The local approval server begins
processing the approval requests.
Consider that servers with the following configuration are used to set up a server group named SvrGrp:
Server type Server name Processor architecture Processor type Available RAM Operating system Database
AR System SvrA SPARC Dual 4 GB Solaris 10 -
AR System SvrB SPARC Dual 4 GB Solaris 10 -
Database DataSvrC SPARC Quad 16 GB Solaris 10 Oracle 10g

Instance name:
svrgrpdb
To configure the approval servers in a server group
1. Install the AR System server on SvrA so that svrgrpdb hosts the AR System server data files.
2. Install the AR System server on SvrB. Use svrgrpdb as Database Name or Connection String.
3. Log in to SvrA, and perform the following steps:
a. In the AR System Administration Console in a browser, choose System > General > Server
Information.
b. On the Configuration tab, select the Server Group Member check box.
c. Click OK to apply the changes.
d.
d. Restart the server for the changes to take effect.

4. Repeat step 3 for SvrB.
Note
The change in Server Group Name is effective only when all servers in the group are restarted.
5. Log in to any one of the servers, and perform the following steps:
a. Open the AR System Server Group Operation Ranking form.
b. Configure the approval server operation of Server SvrA to hold Rank 1, and save the form.
c. Configure the approval server operation of Server SvrB to hold Rank 2, and save the form.
d. Restart SvrA and SvrB for the changes to take effect.
Related topics
11.3.11 Testing and confirming that the current server is working properly
After the server is rebooted, perform the procedures listed below to confirm that it is properly configured in
server group mode and that everything is working properly.
Before you begin

Review server group planning to make sure that you understand how you want to distribute the applications and
components in the server group, especially the following:
Setting failover rankings for servers and operations

Server groups overview
Server roles
Example configurations

To test and confirm that the current server is working properly
1. In a browser, open the AR System Server Group Operation Ranking form:

2. Click Search in the top-left corner of the screen to view all current rankings.
3. When you finish installing all the applications and components on all the servers in the server group, verify
that all of the BMC applications and components are listed for all installed servers.
4. Manually set the rankings of the applications and components in the servers in the server group.
You 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. Here you define
the fail-over ranking of the applications and components in the remaining servers if, for example, Server 1
fails. For example, set the Approval Server on the second server to 2 and to 3 on the third server.
Note
If you used the BMC Remedy ITSM Suite Preconfigured Stack installer, you can skip the next step
because all of the applications have already been installed on the current server.
Post-installation procedures

11.4 Performing other installations

You can perform other instalaltion such as running the suite installer to install multiple BMC Remedy AR System
features on one computer simultaneously. You can also run a separate installer for features like BMC Remedy
Developer Studio or BMC Atrium Integrator Spoon.
The following topics are provided:
11.4.1 Installing silently

To run the installer in a headless environment or to run the installer on multiple systems at the same time, you
can run the installer in silent mode.
Running the installer in silent mode

This section explains the steps to run the silent installer.
Before running the silent installer

Before running the silent installer, you must create an Options.txt file. An example ARSystem-ini-template.txt file
contains all of the options you can place in Options.txt file. You can find the example file in the utility folder of the
BMC Remedy AR System installer files.
To run the installer in silent mode
1. Create an options.txt file that contains the options for the installer:
Copy and paste options from ARSystem-ini-template.txt file (usually found in the utility folder) into
an options.txt file for the installation that you want to run.
Use an options.txt file generated in an earlier installation.
Create an options.txt file from an example options.txt file.
2. Using the worksheets in Completing the planning spreadsheet as a guide, edit the options accordingly,
ensuring that you include the appropriate -P, -J, or -A option:
Option Description Example
-P Sets the installation directory for a product. -P installLocation=<filePath>

Windows: -P
installLocation=C:\Program Files\
BMC Software\ARSystem
UNIX: -P
installLocation=/opt/bmc/ARSystem
-A Specifies the products and features you want to install. The product and -A product <productName>
feature names are listed at the top of the ARSystem-ini-template.txt file. To -A feature <featureName>
install more than one product or feature, include a -A line for each.
For example:

-A product ARSuiteKit
-A feature Clients
Note: The product names are case sensitive.
Refer to the ARSystem-ini-template.txt for
complete product names.
-J Specifies Java properties that correspond to user inputs. See the -J HOST_NAME=foo.bar.com
ARSystem-ini-template.txt file for examples. -J LOGIN=admin
-J PASSWORD=admin
As you edit the options.txt file, apply the following guidelines:

Remove the comment (#) markers.
To use an encrypted password, use the -J passwordOption= option.
In UNIX environments, ensure that no Ctrl+M characters appear in the options.txt file.
Enter Yes for the BMC_EULA_ACCEPT parameter:
## BMC EULA Accept
-J BMC_EULA_ACCEPT=Yes
(Windows) setup.exe -i silent -DOPTIONS_FILE=c:\path\to\options.txt
(UNIX) ./setup.bin -i silent -DOPTIONS_FILE=/path/to/options.txt
Automatically generating an options.txt file

Before you can run the installer in silent mode, you must create an options.txt file to identify the options that you
want the installer to include in the installation or upgrade.
To create an options.txt file
1. Run an installation on a computer that you want to use as a model for silent installations on other
computers.
2. Use one of the following methods to create the options.txt file:
Method Steps
Make the installer generate an options file Add the following option to the command line when you run the installer:
based on the current installation. -DGENERATE_OPTIONS_FILE=<OutputOptionsFileName>.txt
Create an options.txt file from an installation 1. From an installation log in the Log Viewer, click the tab of the installation run from
log. which you want to generate an options file.
2. Select File > Save As.
3. From the Save As Type list, select Project Options File.
4. Enter a file name, and click OK.
Create an options.txt file from an installed 1. Open the productNameInstalledConfiguration.xml file, located in the installation folder.
configuration XML file. 2. Select File > Save As.
3. From the Save As Type list, select Project Options File.
4. Enter a file name, and click OK.


Running the installer in silent mode
Example options.txt file

This is an example of an options.txt file that is used to run the installer in silent mode.
-P installLocation=E:\BMCSoftware\AR
-A featureARSystemServers
-J BMC_ARSYSTEM_INSTALL_OPTION=Install
-J BMC_DATABASE_TYPE=SQL_SERVER
-J BMC_DATABASE_HOST=vm-w28x-prem09
-J BMC_DATABASE_PORT=1433
-J BMC_DATABASE_INSTANCE=vm-w28x-prem09
-J BMC_SQLSERVER_WINDOWSAUTH_OR_SQLAUTH=SQLAUTH
-J BMC_DATABASE_LOGIN=ARADMIN
-J BMC_DATABASE_PASSWORD=AR#Admin#
-J BMC_DATABASE_CONFIRM_PASSWORD=AR#Admin#
-J BMC_DATABASE_DBA_LOGIN=sa
-J BMC_DATABASE_DBA_PASSWORD=Asimil8
-J BMC_DATABASE_DBA_TABLESPACE_NAME=arsystem
-J BMC_DATABASE_DBA_DATAFILE_NAME=arsys
-J BMC_DATABASE_DBA_DATAFILE_SIZE=3000
-J BMC_DATABASE_DBA_LOGFILE_NAME=arsyslog
-J BMC_DATABASE_DBA_LOGFILE_SIZE=2000
-J BMC_DATABASE_UTF=true
-J BMC_AR_USER=Demo
-J BMC_AR_PASSWORD=
-J BMC_AR_CONFIRM_PASSWORD=
-J BMC_AR_SERVER_NAME=vm-w28x-prem09
-J BMC_AR_SERVER_HOST_NAME=vm-w28x-prem09
-J BMC_JAVA_PLUGIN_PORT=9999
-J BMC_PORT_MAPPER_ENABLED=true
Encrypting passwords for silent installations

The options file for BMC Remedy AR System must contain the administrator password for the target computer.
The Maintenance Tool enables you to create an encrypted password that you can paste into the options file.
To encrypt a password for a silent installation
1. Start the Maintenance Tool utility.

2. Click the Encrypt tab.
3. In the Password and Confirm Password boxes, type your password.
4. Click Encrypt.
5.
5. Copy and paste the encrypted password into the options.txt file for your silent installer.
For example, if you want to encrypt the BMC Remedy AR System password and the output is
DES\:b76c59dbc2e1433c7a9c2f006a2e2429116840dce695aea9, enter the following strings:
# -J BMC_AR_PASSWORD=DES\:b76c59dbc2e1433c7a9c2f006a2e2429116840dce695aea9
# -J BMC_AR_CONFIRM_PASSWORD=DES\:b76c59dbc2e1433c7a9c2f006a2e2429116840dce695aea9
Note
You can use the -encrypt option to encrypt a password through the command line. For example, enter:
<product>MaintenanceTool.cmd -silent -encrypt -encrypt -password=<password>

-confirm_password=<password>
For more information, see the command-line help for the Maintenance Tool.
Related topics
Example options.txt file
Automatically generating an options.txt file
Uninstalling in silent mode
1. Create a text file called options.txt.

For more information, see Automatically generating an options.txt file.
Make sure to include the appropriate -P, -J, or -U option.
-P Sets the installation directory for a -P installLocation=C:\Program Files\BMC Software\ARSystem

product.
-U Uninstalls the entire product or an -U product <productName>

individual feature. -U feature <featureName>
For example:
-U product ARSuiteKit
-U feature Clients
Note
The product names are case sensitive. Refer to the ARSystem-ini-template.txt

for complete product names.
2.
2. Change to the directory where the uninstall file is located:

The default locations are as follows:
Windows — C:\Program Files\BMC Software\ARSystem\UninstallBMCARSystem
UNIX — /opt/bmc/ARSystem/UninstallBMCARSystem
3. Run the uninstaller with the -i silent option.
For Windows:
uninstall.exe -i silent -DOPTIONS_FILE= <pathToFile>\Options.txt
For UNIX:
./uninstall \-i silent \-DOPTIONS_FILE= <pathToFile>/Options.txt
11.4.2 Configuring your web server and installing BMC Remedy Mid Tier
with a .war file
BMC recommends that you install the mid tier with the BMC Remedy installer, but this section describes the
alternative .war file method. The following topics are provided:
Configuring your BEA WebLogic web server

BMC Software recommends that you do not use the .war file to deploy the mid tier on WebLogic. Instead, use the
mid tier installer and follow the configuration steps outlined in this section:
To install the mid tier with a BEA WebLogic web server, complete the following steps:
1. Install the BEA WebLogic web server. (See the BEA WebLogic product documentation.)
2. Configure a new domain. (See To configure a new domain.)
3. Install the mid tier. (See Understanding the BMC Remedy Mid Tier and Performing a new installation.)
Choose Other for your web server and Other for your JSP engine.
4. Install an enterprise application. (See To install an enterprise application.)
5. Change the context name to the standard name. (See To change the context name to the standard name.)
6. Enable your mid tier to run Web reports. (See To enable your mid tier to run Web reports.)
7. Include arsys in the cookie path. (See To include arsys in the cookie path.)
Note
If you are installing mid tier on HP-UX, where BEA WebLogic web server has been configured, the
mid tier deployment from the WebLogic Administration Console fails with errors. To resolve this
issue, add the following in the weblogic.xml file:

<container-descriptor>
<prefer-web-inf-classes>true</prefer-web-inf-classes>
</container-descriptor>
To configure a new domain
1. Start the WebLogic Configuration Wizard.

On Windows, choose All Programs > BEA Products > Tools > Configuration Wizard.
On UNIX, make sure that you have UI access enabled. (Set your display, or run from the console.)
Then, after a clean installation of WebLogic Server 9.1, go to the WebLogic ../common/bin directory,
and run the config.sh script.
The Welcome screen appears.
2. Select Create New WebLogic Domain, and click Next.
The Select Domain Source screen appears.
3. Select Generate a domain configured automatically.
The WebLogic Server (recommended) option is selected by default.
4. Click Next.
The Configure Admin Username and Password screen appears.
5. In the Username field, enter weblogic.
6. In the Password fields, enter weblogic, and click Next.
The Configure Start Mode and JDK screen appears.
7. Select Development Mode, and select BEA Supplied JDK (or an alternate), and click Next.
The Customize Environment and Services Settings screen appears.
8. Select No, and click Next.
The Create Domain screen appears.
9. Enter a Domain Name (such as testing ), enter the Domain Location, and click Create.
The Creating Domain screen appears.
10. After the script finishes the configuration, click Done.
11. Start WebLogic Server.
To install an enterprise application
1. Install BMC Remedy Mid Tier. (See Understanding the BMC Remedy Mid Tierand Performing a new
installation.)
2. Log in to the WebLogic Administration Console through a URL similar to:
http://<hostName>:7001/console
Use the login information that you specified in step 5 and step 6 in To configure a new domain.
3. Under the Change Center, complete the following steps:
a. Click Lock and Edit.
b. Click the Deployments folder.
c. Click Install.
d.
3.
d. Click Location (host name), and go to the directory in which the mid tier is installed.
e. Click Next.
f. Select Install this deployment as an application, and click Next.
g. In the Name for deployment field, enter arsys, and click Next.
h. Click Finish, and click Save.
4. Under the Change Center, click Activate Change.
5. Click Start.
6. On Windows platforms, verify that the mid tier installer added the \WEB-INF\lib mid tier installation
directory path in the PATH variable.
7. On UNIX systems, update the mid tier installation path in the BEA WebLogic start script as follows:
a. Stop the WebLogic server.
b. Update the BEA WebLogic start script with the appropriate path:
Platform Path
AIX LIBPATH=/usr/ar/mid-tier/WEB-INF/lib:$LIBPATH;export LIBPATH
HP_UX SHLIB_PATH =/usr/ar/mid-tier/WEB-INF/lib:$SHLIB_PATH;export SHLIB_PATH
Solaris and Linux LD_LIBRARY_PATH=/usr/ar/mid-tier/WEB-INF/lib:$LD_LIBRARYPATH;export LD_LIBRARY_PATH
c. Restart the WebLogic server.
To change the context name to the standard name
1. Create a weblogic.xmlfile in one of the following directories:

Windows — C:\Program Files\BMC Remedy AR System\Mid-Tier\WEB-INF
UNIX — /usr/ar/mid-tier/WEB-INF
2. Change the context name to the standard name of arsysby adding the following lines to the file:
<?xml version="1.0" encoding="ISO-8859-1" ?>

<!DOCTYPE weblogic-web-app>
<weblogic-web-app>
<context-root>arsys</context-root>
</weblogic-web-app>
To enable your mid tier to run Web reports
1. Shut down the Weblogic Server.

2. Open weblogic.xml with a text editor.
3. Add the following lines after the <context-root>line:

For example:
<weblogic-web-app>
<context-root>arsys</context-root>
</weblogic-web-app>
4. Save weblogic.xml.
5. Restart the Weblogic server.
To include arsys in the cookie path
1. Shut down the Weblogic Server.

2. Open weblogic.xml with a text editor.
3. Add the following lines to the file:
<session-descriptor>
<cookie-path>/arsys</cookie-path>
</session-descriptor>
4. Save weblogic.xml.
5. Restart the Weblogic server.
Configuring and installing BMC Remedy Mid Tier on IBM WebSphere

To install the mid tier with an IBM WebSphere web server, complete the following steps:
1. Install IBM WebSphere.

2. Deploy the mid tier with the .war file.
3. Configure system requirements.
4. Configure the WebSphere Application Server to support the WBMP MIME type.
To install IBM WebSphere
1. Create an Administrator User with the following advanced rights:

Act as part of the operating system
Log on as services
2. Install IBM WebSphere.
See your IBM WebSphere Application Server product documentation for specific installation instructions.

To deploy the mid tier with the .war file
1. Locate the midtier.war, midtierCombined.war, or midtier_<platform>.war file.

The .war file is located with the BMC Remedy AR System installation files. If you have BusinessObjects or
Crystal software installed, use the midtierCombined.war file.
2. Start the IBM WebSphere server.
In the output command window, check for the Open for e-business message, which confirms that the
server has started.
3. Open the WebSphere Application Server console.
The default URL is http://<hostName>:9060/admin.
4. Log on as the administrator that you created in To install IBM WebSphere.
5. If the BMC Remedy Mid Tier is installed, stop it and uninstall it by using the WebSphere Application Server
console.
6. Choose Applications > Install New Application.
7. In the Preparing for the application installation section, browse to the midtier_<platform>.war file.
8. Designate a name for BMC Remedy Mid Tier on WebSphere in the Context Root subsection.
The recommended path is /arsys.
9. Click Next.
10. In the Select Installation Options section, enter ARSYSTEM in the Application Name field, and click Next.
11. In the Map Modules to Application Servers section, select the BMC Remedy AR System check box, and click
Next.
12. In the Map Virtual Hosts for Web Modules section, select the BMC Remedy AR System check box, and click
Next.
13. In the Summary section, click Finish.
14. In the Application appName Installed Successfully section, click Save directly to the master configuration.
15. In the WebSphere Application Server console, select ARSYSTEM and click Startto start the server.
Note
If you are deploying mid tier with the .war file for the mid tier home page, user form, group form,
and any form created with trim fields to open:
Stop the WebSphere server and then delete or rename the aspectjrt.jar file from the WebSphere6.1
InstallDir/lib directory (for example: /opt/IBM/WebSphere61/lib). Then, start the WebSphere
server.
This will make sure that WebSphere uses the aspectjrt.jar file provided by the mid tier.
To configure system requirements
1. Make the following modifications:

1.
On Windows, add the BMC Remedy Mid Tier lib directory to the system PATH environment variable
as in the following example:
C:\Program
Files\WebSphere\AppServer\installedApps\<computerName>\<midTierName>.ear\midtier\<platform>.war\WE
On UNIX, modify the startServer.sh file and add <midTierInstallDir>/WEB-INF/lib as follows,
depending on your operating system:
Platform Path
AIX LIBPATH=/usr/WebSphere/AppServer/installedApps/<computerName>/
arsys.ear/midtier_<platform>.war/WEB-INF/lib;export LIBPATH
HP_UX SHLIB_PATH =/usr/WebSphere/AppServer/installedApps/<computerName>/

arsys.ear/midtier_<platform>.war/WEB-INF/lib;export SHLIB_PATH
Solaris LD_LIBRARY_PATH=/usr/WebSphere/AppServer/installedApps/<computerName>/
and Linux arsys.ear/midtier_<platform>.war/WEB-INF/lib;export LD_LIBRARY_PATH
2. Modify the config.properties file in the

<WebSphereInstallDir>/installedApps/<computerName>/<midTierName>.ear/midtier<platform>.war/WEB-INF/classe
directory.
Modify all directory references to point to your newly installed BMC Remedy AR System directories. For
example, modify the following directory references as shown:
Windows:
arsystem.log_filepath=<WebSphereInstallDir>\installedApps\arsys.ear\midtier_<platform>.war\work\logsarsy
UNIX:
arsystem.log_filepath=<WebSphereInstallDir>/installedApps/arsys.ear/midtier_<platform>.war/work/logsarsy
3. In the Websphere Admin Console, choose WebSphere Application Servers > serverName > Session
management > Enable Cookies.
Make sure that the path is set to the context root of the mid tier.
4. To ensure that users can log in successfully, create a new NoAdditionalSessionInfoproperty:
a. Choose WebSphere Application Servers > serverName > Web Container > Custom Properties.
b. Create a new NoAdditionalSessionInfo property, and set it to True.
5. Restart the IBM WebSphere server.
Note
When you start the mid tier for the first time, WebSphere might send socket I/O errors. To fix this,
set the ServerIOTimeout to 300. For more information, see
http://publib.boulder.ibm.com/infocenter/wasinfo/v5r0/index.jsp?topic=/com.ibm.websphere.base.doc/info/a
.

To configure the WebSphere Application Server to support the WBMP MIME type
If you are using WebSphere Application Server, perform the following steps to configure WebSphere Application
Server to support the WBMP MIME type:
1. Log in to the WebSphere Application Server Administrative Console.

2. Expand the Environments icon (forward arrow) to Virtual Hosts.
3. Select default_host.
4. Select MIME Types under Additional Properties.
5. Click New.
6. Enter text/css in the MIME Type field.
7. Enter css in the Extension field.
8. Click OK to save the new MIME type.
9. Click New.
10. Enter image/png in the MIME Type field.
11. Enter png in the Extension field.
12. Click OK to save the new MIME type.
13. Save the configuration changes.
Installing and deploying on JBoss

To install and deploy the mid tier with JBoss Application Server, complete the following steps:
1. Install JBoss Application Server. (For instructions, see the appropriate JBoss Application Server
documentation.)
2. Deploy the WAR file by either extracting the WAR file or using the JBoss Admin Console.
To extract the WAR file
1. Download the MidTier.war file from the BMC Support website.

2. Rename MidTier.war to MidTier.zip.
3. Extract the contents of the MidTier.zip file to a folder called MidTier.
Ensure that the MidTier folder contains two subfolders: Resources and WEB-INF.
4. Rename the MidTier folder to arsys.war.
5. Copy the arsys.war folder to the <JBOSSInstallationFolder>\server\default\deploy location.
6. Navigate to the <JBOSSInstallationFolder>\bin folder and open the run.conf.bat file to set the value of the
JVM Memory allocation pool parameter as follows:
set JAVA_OPTS=-Xms1024m -Xmx2048m -XX:MaxPermSize=256m
7. Verify whether the deployment was successful.

See Testing the mid tier.

To use the JBoss Admin Console
1. Download the MidTier.war file from the BMC Support website.

2. Start JBoss Application Server.
3. Open a browser and type http://<hostName>:8080 in the Address field.
4. On the Welcome page, click the Admin Console link and log on to the Admin Console using your user
name and password.
5. On the Admin Console, click the Web Application (WAR) link.
6. In the Summary tab, click Add a new resource and navigate to the MidTier.war file.
7. For the Deploy Exploded option, select Yes.
8. Click Continue and wait until the installation is complete.
9. Verify whether the deployment was successful.
See Testing the mid tier.
Deploying the .war file on Tomcat

After deploying the .war file on Tomcat, perform the following manual configuration steps for the deployment to
be successful:
1. Set the following variables to the mid tier installation directory path (\WEB-INF\lib):
Platform Path
Windows PATH
Linux and Solaris LD_LIBRARY_PATH
HP-UX SHLIB_PATH
AIX LIBPATH
2. Only for UNIX platform, install the required libstdc++5 libraries.
Testing the mid tier

To make sure that the mid tier is functioning correctly, verify that you can access the configuration page and one
or more forms.
1. To open the home page, enter the following URL:
http://<hostName>:<port>/arsys/home
For example, you can enter the following URL:
http://localhost:8080/arsys/home
2. To open the configuration page, enter the following URL in the BMC Remedy Mid Tier Configuration Tool:
http://<hostName>:<port>/arsys/shared/config/config.jsp
3.
3. Configure your preference and home page servers.

For more information, see Setting user preferences and Configuring home page preferences.
4. To open forms, enter:
http://<hostName>:<port>/arsys/forms/<ARSystemServerName>/<formName>/<viewName>
The default ports are:
8080 (Tomcat)
8989 (Oracle Java System)
7001 (WebLogic)
9080 (WebSphere)
8080 (JBoss)
11.4.3 Remotely installing or upgrading Email Engine

This topic discusses remotely installing or upgrading Email Engine on the following platforms:
Microsoft Windows
UNIX
Remotely installing or upgrading Email Engine on Microsoft Windows
Note
Follow these two steps first, if you are creating a service where the Email Engine form and arx data is not
present:
1. Import the AR_Email_Workflow.def file located in the AREmail folder using BMC Remedy
Developer Studio.
2. Import the approval_templates.arx file located in the AREmail folder using the BMC Remedy Data
Import tool.
After following the above steps, continue with the steps given below.
1. Copy the Email Engine binaries to the AREmail folder. For example: C:\Program Files\BMC
Software\ARSystem\AREmail.
2. Update or add the following entry in the logging.properties file, located in the lib folder where JRE is
installed:
com.bmc.arsys.emaildaemon.level=SEVERE
3. Update or add the following entries in the javamail.providers file, located in the lib folder where JRE is
installed:
protocol=mbox; type=store;

3.
class=gnu.mail.providers.mbox.MboxStore;vendor=dog@gnu.org;
protocol=mapistore;type=store;class=com.bmc.mail.mapi.MAPIStore;vendor=mapi@bmc.com;
protocol=mapitransport;type=transport;class=com.bmc.mail.mapi.MAPITransport;vendor=mapi@bm
4. Set the following two entries in the EmailStart.bat file (Microsoft Windows), located in the AREmail folder:
set LIBVER=<BuildVersion> For example, <BuildVersion> = 80_build002
set JavaPath=<BinPathOfInstalledJRE> For example, <BinPathOfInstalledJRE> = C:\Program
Files\Java\jre7\bin
5. Set the following entry in the EmailStop.bat file (Microsoft Windows), located in the AREmail folder:
set JavaPath=<BinPathOfInstalledJRE> For example, <BinPathOfInstalledJRE> = C:\Program
Files\Java\jre7\bin
6. Update or add the following entries to the EmailDaemon.properties file, located in the AREmail folder:
com.bmc.arsys.emaildaemon.servers=<ARServerHostName>
com.bmc.arsys.emaildaemon.<ARServerHostName>.TCP=<ARServerPort>
com.bmc.arsys.emaildaemon.<ARServerHostName>.RPC=<EmailEngineRPCPort>
com.bmc.arsys.emaildaemon.<ARServerHostName>.Language=en_US
com.bmc.arsys.emaildaemon.<ARServerHostName>.Password=<EncryptedARApplicationPassword>
com.bmc.arsys.emaildaemon.<ARServerHostName>.Interval=30
com.bmc.arsys.emaildaemon.<ARServerHostName>.Authentication=
7. Create an empty logs folder under the AREmail folder.
8. Open the command prompt and navigate to the AREmail folder.
9. Create the Email Engine Service using the armaild.bat file, located in the AREmail folder.
10. Pass the following arguments to the batch file in the specified sequence:
a. Action: either "install" or "uninstall".
b. The full path to the Java VM .dll file, that is, C:\Program Files\Java\jre6\bin\client\jvm.dll.
c. The Email daemon installation directory where the libraries are located. For example,
emaildaemon.jar, arapi80_build002.jar, and other .jar files.)
d. The AR library version. For example, 80_build002.
e. The AR Server name where the Email Engine is configured.
For example, C:\Program Files\BMC Software\ARSystem\AREmail>armaild.bat install "C:\Program
Files\Java\jre6\bin\client\jvm.dll" "C:\Program Files\BMC Software\ARSystem\AREmail" 80_build002
VW-PUN-REM-QA5L.bmc.com
Note
Run the command with administrator privileges. If you do not run the command with
administrator privileges, the following error is displayed in the command prompt:
Error while checking to see if service is installed: Access is denied.
11. Start the Email Engine service.

Remotely installing or upgrading Email Engine on UNIX
Note
Follow these two steps first, if you are creating a service where the Email Engine form and arx data is not
present:
1. Import the AR_Email_Workflow.def file located in the AREmail folder using BMC Remedy
Developer Studio.
2. Import the approval_templates.arx file located in the AREmail folder using the BMC Remedy Data
Import tool.
After following the above steps, continue with the steps given below.
1. Copy the AREmail folder from the installed UNIX system to the other UNIX system. For example, the Email
Engine Install Directory will be /opt/bmc/ARSystem/AREmail.
2. Update or add the following entry in the logging.properties file, located in the lib folder where JRE is
installed:
com.bmc.arsys.emaildaemon.level=SEVERE
3. Update or add the following entries in the javamail.providers file, located in the lib folder where JRE is
installed:
protocol=mbox; type=store;
class=gnu.mail.providers.mbox.MboxStore;vendor=dog@gnu.org;
protocol=mapistore;type=store;class=com.bmc.mail.mapi.MAPIStore;vendor=mapi@bmc.com;
protocol=mapitransport;type=transport;class=com.bmc.mail.mapi.MAPITransport;vendor=mapi@bm
4. Update the following entries to the EmailDaemon.properties file, located in the AREmail folder. For
example, /opt/bmc/ARSystem/AREmail.
com.bmc.arsys.emaildaemon.servers=<ARServerHostName>
com.bmc.arsys.emaildaemon.<ARServerHostName>.TCP=<ARServerPort>
com.bmc.arsys.emaildaemon.<ARServerHostName>.RPC=<EmailEngineRPCPort>
com.bmc.arsys.emaildaemon.<ARServerHostName>.Language=en_US
com.bmc.arsys.emaildaemon.<ARServerHostName>.Password=<EncryptedARApplicationPassword>
com.bmc.arsys.emaildaemon.<ARServerHostName>.Interval=30
com.bmc.arsys.emaildaemon.<ARServerHostName>.Authentication=
5. Update the following entries in the emaild.sh (UNIX) file, located in the AREmail folder:
JAVA_DIR=<HomePathOfInstalledJRE> For example,/usr/jdk/jdk1.6.0_21/jre

5.
JAVA_BIN=<BinPathOfInstalledJRE> For example, /usr/jdk/jdk1.6.0_21/jre/bin/sparcv9

InstallPath=<EmailEngineInstallLocation> For example, /opt/bmc/ARSystem/AREmail
LIBVER=<BuildVersion> For example, 80_build002
6. Start the Email Engine service by executing the ./emaild.sh start & command.
11.4.4 Remotely installing or upgrading Flashboards

Follow the steps given below to remotely install or upgrade Flashboards.
For Microsoft Windows
1. Copy the Fashboard binaries to the flashboards folder.

For example, C:\Program Files\BMC Software\ARSystem\flashboards
2. Update or add the following entries to the server.conf file, located in the flashboards folder:
ARServerName=<ServerName>
ARServerTcpPort=<ServerTCPPort>
RMIRegistryPort=<FlashBoardRMIRegistryPort>
ARServerRpcNumber=<FlashBoardRPCPort>
Password=<EncryptedARApplicationPassword>
3. Update or add the following entries to the server.bat file, located in the flashboards folder:
set LIBVER=<BuildVersion> For example, <BuildVersion> = 80_build002
4. Create an empty logs folder under the flashboards folder.
5. Create a Flashboard service using the fbserver.bat file, located in the flashboards folder.
6. Pass the following arguments to the batch file:
Install folder
The jvm.dll path
The Flashboard install directory path
The Build Version
The server name where Flashboard is getting configured
For example, c:\Program Files\BMC Software\AR System\flashboards>"C:\Program
Files\BMC Software\AR System\flashboards\fbserver.bat" install "C:\Program
Files\Java\jre6\bin\server\jvm.dll" "C:\Program Files\BMC Software\AR
System\flashboards" 80_build002 VW-PUN-REM-QA5L.bmc.com
7. Start the Flashboard service.
For UNIX
1. Copy the flashboard binaries to the Flashboard install directory. For example,
/opt/bmc/ARSystem/flashboards
2. Update or add the following entries to the server.conf file, located in the flashboards folder:
ARServerName=<ServerName>
ARServerTcpPort=<ServerTCPPort>

2.
RMIRegistryPort=<FlashBoardRMIRegistryPort>
ARServerRpcNumber=<FlashBoardRPCPort>
Password=<EncryptedARApplicationPassword>
3. Update or add the following entries to the server.sh file, located in the flashboards folder:
JAVA_DIR=<HomePathOfInstalledJRE> For example, /opt/java/jre7
JAVA_BIN=<BinPathOfInstalledJRE> For example, /opt/java/jre7/bin
JAVA_LIB=<libPathOfInstalledJRE> For example, /opt/java/jre7/lib
flashInstallPath=<FlashboardInstallLocation> For example,
{{/opt/bmc/ARSystem/flashboards
LIBVER=<BuildVersion> For example, {{80_build002
4. Create an empty logs folder under the flashboards folder.
5. Start the Flashboard service.
11.4.5 Installing BMC Remedy Encryption Security

The following topics provide information and instructions for installing and uninstalling the BMC Remedy
Encryption Security products:
The instructions assume that you have installed or upgraded to BMC Remedy AR System 8.1.
To use the following encryption products, you must install them on both the server and its clients:
BMC Remedy Encryption Performance Security 8.1 (Performance Security)

BMC Remedy Encryption Premium Security 8.1 (Premium Security)
Clients include BMC Remedy, third-party, and user-developed applications that use the BMC Remedy API.
Important
Before installing Performance Security or Premium Security on an BMC Remedy AR System server, you
must add an AR Server license and the appropriate BMC Remedy AR Encryption license to the server.
You cannot install encryption products on AR System servers that have evaluation or trial licenses. For
information about adding licenses to servers, see Adding licenses.
Before uninstalling or upgrading BMC Remedy Encryption Security products, stop the Atrium Integrator
Service.
Standard security is built into the BMC Remedy AR System API, so you do not need to install it.
Installing an application that communicates with encrypted servers

This procedure explains how to install an application that must communicate with a BMC Remedy AR System
server on which encryption is already activated.

To install an application that communicates with an encrypted server
1. Deactivate encryption on the appropriate server.

See Configuring the data key.
2. Install the application.
3. On the application, install the same level of encryption that the server uses.
See Installing encryption on BMC Remedy applications.
Note
If the server uses standard security, do not install encryption. Standard security is built into the
BMC Remedy AR System 8.1 API.
4. Reactivate encryption on the server.

Installing encryption on BMC Remedy applications

This topic describes how to install Performance and Premium 8.1 encryption on BMC Remedy AR System servers
and clients. Use the same procedure for both Microsoft Windows and UNIX platforms.
To install encryption on third-party or user applications that use the AR System API to communicate with AR
System servers, see Non-BMC Remedy applications.
Warning
If you update the Oracle Java runtime environment (JRE) or Java development kit (JDK) on a computer
after installing Performance Security or Premium Security, you must reinstall encryption. See
Configuring the data key.
To install encryption on BMC Remedy AR System servers and clients
1. Verify the following items:

All servers and clients on which you plan to install a BMC Remedy Encryption Security 8.1 product
are using AR System 8.1.
The BMC Remedy Encryption Security 8.1 products are compatible with your system. See FIPS 140-2
certification in FIPS Encryption options.
The appropriate AR Encryption license is added to each server on which you plan to install
encryption. (For information about adding licenses to servers, see the BMC Remedy AR System
Configuring section.)
2. Go to the directory that contains the encryption installer.
3.
3. Run the appropriate installer:

Operating system Encryption level Installer
Windows Performance PerformanceSecurity.exe
Windows Premium PremiumSecurity.exe
UNIX Performance PerformanceSecurity.bin
UNIX Premium PremiumSecurity.bin
4. If the Notification screen appears, follow the instructions on the screen.

If you restart your computer to comply with the instructions, you must also restart the installer.
5. In the Welcome screen, click Next.
Note
At any time during setup, you can click Cancel to exit the installer. Your settings up to that point in
the installer, however, are not saved.
6. Select I agree to the terms of the license agreement, and click Next.
7. (Optional) In the Directory Selection screen, click Browse to change the temporary installation directory.
8. Click Next.
9. In the Select AR Component screen, select the components to install encryption on.
If you do not want to install encryption on a preselected component, clear the component's check box.
To add a component to the list:
a. In the Add Component area, select the appropriate component in the Component list.
b. Click Browse.
c. Navigate to the folder in which to install the component's encryption library.
Note
The encryption library must be stored in the folder that contains the component's
arapi75.dll file.
d. Select the folder, and click Open.

e. Click Add to List.
10. Click Next.
11. (Server only) If you are installing encryption on a server, the AR Components Detection Validation Result
screen appears to notify you that the installation program will restart the server.
12. Click Next.
13.
13. (Java only) If you are installing encryption on Java-based components, select the JRE directories used by
those components in the Java Platform Selection Panel screen.
You should select both the JDK JRE directory and the public JRE directory.
Note
Java-based components include BMC Remedy Mid Tier, BMC Remedy Developer Studio, the BMC
Remedy Flashboards server, BMC Remedy Email Engine, the Java plug-in server, and
user-developed clients that use the BMC Remedy AR System Java API.
To add a JRE directory to the table:

a. Click Add.
b. Navigate to the folder that contains the definition.
c. Select the folder, and click Open.
14. (Java only) Click Next.
15. (Server only) If you are installing encryption on a server, select one of these options in the Security Mode
Information screen:
FIPS Compliant — If you select this option, your encryption configuration will comply with Federal
Information Processing Standard (FIPS) 140-2. See FIPS encryption options.
Encryption Algorithm — Select an encryption algorithm:
AES — Advanced Encryption Standard (AES) is a block cipher. It is the U.S. Federal
government-approved encryption algorithm and provides a higher level of security than RC4.
RC4 — Rivest Cipher 4 (RC4) is a stream cipher. It is less secure than AES but faster. This option is not
available for FIPS-compliant servers.
Security Policy — Select a security policy:
Optional — Clients with and without encryption installed can communicate with the server.
This option is not available for FIPS-compliant servers.
Required — Only clients with encryption installed can communicate with the server.
Disabled — Whether encryption is installed on a client or not, communication with the server
is not encrypted.
16. (Server only) Click Next.
17. In the Installation Preview screen, perform one of these tasks:
To change the installation setup, click the Previous button to return to the screens that need editing.
To start the installation, click Install.
The installer copies the encryption libraries into the specified folder for each selected component
(see step 9) and updates product log files and registry entries. If you are installing encryption on a
server, it also restarts the server.
18. When the installation is finished, do this:
a. (Optional) To review the install log file, click View Log.
b. To exit the wizard, click Done.

To modify a server's encryption settings after installation, see Configuring encryption security.
Note
If you install Performance Security or Premium Security on a BMC Remedy AR System server before
adding the appropriate BMC Remedy AR System Encryption Performance or Premium license to the
server, the installation program automatically disables encryption. To activate encryption, you must add
the license to your server (see Configuring) and then activate encryption (see Configuring the data key).
Installing encryption on non-BMC Remedy applications

This topic explains how to install Performance Security or Premium Security 8.1 on third-party or user
applications that use the BMC Remedy AR System 8.1 API to communicate with BMC Remedy AR System servers.
Use the same procedure for both Microsoft Windows and UNIX.
To install encryption on non-BMC Remedy applications
1. Upgrade the application to use the BMC Remedy AR System 8.1 API.
2. Install the appropriate Performance Security or Premium Security 8.1 product on your BMC Remedy AR
System server.
3. Exit or stop any processes for the application that are running.
4. Copy the encryption libraries for the appropriate platform from the server installation directory to the
folder containing the application's BMC Remedy AR System API file.
Platform Encryption library files AR System API files
IBM AIX 32-bit libarencrypt.a libar.a (archive)

libcrypto.so libar.so (shared library)
IBM AIX 64-bit libarencrypt_aixp64.a libar_aixp64.a (archive)

libcrypto_aixp64.so libar_aixp64.so (shared library)
HP Itanium 32-bit libarencrypt_hpia32.sl libar.a (archive)

libcrypto_hpia32.so libar.sl (shared library)
HP Itanium 64-bit libarencrypt_hpia64.sl libar_hpia64.a (archive)

libcrypto_hpia64.so libar_hpia64.sl (shared library)
HP-UX 32-bit libarencrypt.sl libar.a (archive)

libcrypto.sl libar.sl (shared library)
HP-UX 64-bit libarencrypt_hppa64.sl libar_hppa64.a (archive)

libcrypto_hppa64.sl libar_hppa64.sl (shared library)
Oracle Solaris 32-bit libarencrypt.so libar.a (archive)

Solaris 64-bit libarencrypt_solsp64.so libar_solsp64.a (archive)

libcrypto_solsp64.so libar_solsp64.so (shared library)
Linux ^^ 32-bit

libarencrypt.so libar.a (archive)

Linux 64-bit libarencrypt_lx64.so libar_lx64.a (archive)

libarcrypto_lx64.so libar_lx64.so (shared library)
Windows 32-bit arencrypt VerNum.dll arapi VerNum.dll
Windows 64-bit arencrypt VerNum.win64.dll arapi VerNum.win64.dll
5. If necessary, restart the application.
FIPS encryption options

To be used by U.S. Federal government agencies, software must comply with Federal Information Processing
Standard (FIPS) 200. According to FIPS 200, information that needs cryptographic protection must be handled by
software that complies with FIPS 140-2.
The following products include a FIPS encryption option:
BMC Remedy Encryption Performance Security — When this option is activated, AR System encrypts
network traffic by using AES CBC with a 128-bit key for data encryption and a 1024-bit modulus for the
RSA key exchange, and SHA-1 for message authentication.
BMC Remedy Encryption Premium Security — When this option is activated, AR System encrypts network
traffic by using AES CBC with a 256-bit key for data encryption and a 2048-bit modulus for the RSA key
exchange, and SHA-1 for message authentication.
Note
The built-in BMC Remedy Encryption Standard Security product does not include a FIPS option.
To activate FIPS encryption, see Activating FIPS compliance.
Note
From the 8.1 release of BMC Remedy AR System, Atrium SSO integration is now FIPS compliant. For
more information, see Configuring an external Tomcat instance for FIPS-140 and Configuring FIPS-140
mode.
FIPS-compliant AREA and ARDBC LDAP plug-ins

When you install the AR System server, the FIPS-certified Network Security Services (NSS) 3.11.4 libraries from
Mozilla are added to the following Lightweight Directory Access Protocol (LDAP) plug-ins:
AR System External Authentication (AREA)

AR System Database Connectivity (ARDBC)
To comply with FIPS 140-2, the plug-ins must use SSL to connect to the LDAP server.
Important
These libraries provide the capability to comply with FIPS 140-2. To make your LDAP environment
actually compliant with FIPS 140-2, you must further configure your LDAP server. For more information,
see the Federal government FIPS 200 and 140-2 guidelines and your LDAP server documentation.
FIPS 140-2 certification

The following FIPS-certified libraries provide the cryptography used by the Performance and Premium FIPS
encryption options:
Network Security Services (NSS) 3.11.4

OpenSSL FIPS 1.2
RSA Crypto-J 4.0 FIPS-140
11.4.6 Installing BMC Remedy Migrator

Use the following procedure to install BMC Remedy Migrator. You use the Delta Data Migration Tool installed
with BMC Remedy Migrator to migrate delta data.
Note
You must have administrator privileges for the machine on which you are installing BMC Remedy
Migrator. You must install BMC Remedy Migrator 8.1 and the latest binary fix to perform the full
migration.
Always download and install the latest BMC Remedy Migrator version available when you are
migrating delta data.
To install BMC Remedy Migrator
1. Shut down all other running applications before you start.

2. Insert the BMC Remedy Migrator DVD into your DVD drive.
If the BMC Remedy Migrator setup program starts a few seconds after inserting the disk, skip to step 4 or
follow the on-screen instructions.
3. From your DVD drive, double-click setup.exe.
A progress bar appears as the files are extracted.
4.
4. Click Next when you see the Welcome screen.

5. In the License Information dialog box, read the
license agreement, and click Agree.
For more information about licensing, see Configuring BMC Remedy Migrator and Working with BMC
Remedy AR System licenses.
6. Perform either of the following actions:
Click Next to accept the default installation directory.
Click Browse to select another installation directory.
7. Click Next.
8. Click the check box to place the BMC Remedy Migrator program icon on your desktop, and click Next.
9. Review the installation options you selected; if they are correct, click Install to begin the installation.
Note
You might see validation warnings related to the mfc71.dll, mfc71u.dll, and msv1_0.dll2 files.
These warnings can be ignored because they do not affect the ability of BMC Remedy Migrator to
be installed.
10. When installation is complete, click Done. (Optionally, you can click View Log to see the installation log.)
To begin using BMC Remedy Migrator, you must restart your computer.
11.4.7 Installing SSO with the AR System server and mid tier
This section describes how to perform a single sign-on (SSO) installation. Click the following BMC Atrium Single
Sign-On 8.1 installation video for more information:
Watch video on YouTube at http://www.youtube.com/watch?v=gmSZJnin1WM
Installing SSO includes the following steps:
Important
BMC recommends that you install BMC Remedy Mid Tier on a separate server from BMC Remedy AR
System.
Note
For detailed information on installing and configuring BMC Atrium Service Context, see Setting up BMC
Atrium Service Context. As a bare minimum, you must install the Web Services Registry (UDDI), which is

required for BMC Atrium Service Context. The Web Services Registry is an option within the BMC Atrium
Core installation program.
Installing the BMC Atrium Single Sign-On server as a standalone

This topic provides instructions for performing a BMC Atrium Single Sign-On standalone installation. In this
installation, a Tomcat server and JVM are installed and properly configured for use by the BMC Atrium Single
Sign-On server. This installation method is the simplest and easiest to perform since all of the administrative and
configuration details are performed by the installation program.
This section contains the following topics:
Before you begin

To install BMC Atrium Single Sign-On as a standalone
Before you begin
Obtain the zipped BMC Atrium Single Sign-On files from the BMC product package via Electronic Product
Download (EPD) or the BMC Atrium Single Sign-On DVD.
If there is already an installation of BMC Atrium Single Sign-On on the target computer, the installer will
not allow another installation. Uninstall the existing version.
Prepare to run the installation program for your operating system.
For example, you must update Terminal Services configuration options and configure the DEP feature if
you are using Windows. For more information, see Configuring Terminal Services and DEP parameters.
Important
The BMC Atrium Single Sign-On Tomcat server cannot be shared with any product (for example, the AR
System server or the BMC Remedy Mid Tier) that integrates with BMC Atrium Single Sign-On. BMC
recommends that you install BMC Atrium Single Sign-On on a different computer than the computer
where you plan to install a BMC product (for example, the AR System server or the BMC Remedy Mid
Tier).
To install BMC Atrium Single Sign-On as a standalone
1. Unzip the BMC Atrium Single Sign-On files.

2. Run the installation program.
The setup executable is located in the Disk1 directory of the extracted files.
(Microsoft Windows ) Run setup.cmd.
(UNIX ) Run setup.sh (which automatically detects the appropriate subscript to execute).
4.
5. Accept the default destination directory or browse to select a different directory, and then click Next.
6. In the Host Name Information panel, verify that the hostname presented is the Fully Qualified Domain
Name (FQDN) for the host, and then click Next.
Correct the value as needed.
7. Choose to install non-clustered or clustered Atrium Single Sign-On Server, and then click Next.
Non-clustered Atrium Single Sign-On Server – Standalone Single Sign-On Server.
Clustered Atrium Single Sign-On Server – Implemented as a redundant system with session failover.
Clustered install requires at least two nodes. For more information, see Installing BMC Atrium Single
Sign-On as a High Availability cluster.
8. Verify that Install New Tomcat is selected, and then click Next.
The Tomcat server options are:
Install New Tomcat (default)
Use External Tomcat. See Installing BMC Atrium Single Sign-On on an external Tomcat server to
install with this option.
9. Accept the default Tomcat HTTP port number (8080), HTTPS port number (8443), and Shutdown port
number (8005), or enter different port numbers, and then click Next.
If any of the port numbers are incorrect, a panel identifies the incorrect port number and requires you to
return to the previous page to correct the values before proceeding with the installation.
Note
When installing on Linux servers, port selections below 1000 require the server to run as root, or
use a port forwarding mechanism.
10. Enter a cookie domain, and then click Next.

The domain value of the cookie should be the network domain of BMC Atrium Single Sign-On or one of its
parent domains. See Default cookie domain for more information.
Important
The higher the level of the selected parent domain, the higher the risk of user
impersonation. Top-level domains are not supported (for example, com or com.ca ).
You cannot use sibling domains or cross-domains with BMC Atrium Single Sign-On. For
example, installing the BMC Atrium Single Sign-On server in the remedy.com domain and
the AR System server in the bmc.com domain is not supported. You must move all your
computers into the same domain.
11.
11. Enter a strong administrator password (at least 8 characters long), confirm the password, and then click
Next.
The default SSO administrator name is amadmin.
Note
Passwords with special characters must be specified in quotes.
See Administrator password for more information.

12. Review the installation summary and click Install.
13. Verify that your BMC Atrium Single Sign-On installation was successful by accessing the BMC Atrium Single
Sign-On URL.
a. Navigate to Start > All Programs > BMC Software > BMC Atrium SSO > Administrator to launch the
BMC Atrium SSO Admin Console .
The URL to open the BMC Atrium SSO Admin Console is:
https://<ssoserver>.<domain>:<port>/atriumsso
For example:
https://ssoserver.bmc.com:8443/atriumsso
b. When you are prompted that you are connecting to an insecure or untrusted connection, add the
exception and then continue.
Note
Browsers display this warning because you have not yet configured the SSO authentication
as a trusted provider.
c. Confirm that you can view the BMC Atrium SSO logon panel.
d. Log on with the SSO administrator name (for example, amadmin) and password.
The BMC Atrium SSO Admin Console appears.
14.
14. (Optional) Create an administrative user account for BMC Products to perform search functions on the
user store (for example, to list user names and emails).
If you are using the BMC Atrium Single Sign-On server's internal LDAP, assign the BMCSearchAdmins
group to the new user account.
If you are using an external system for authentication (such as AR System, LDAP, or Active Directory),
assign the BmcSearchAdmins group to either an already existing user account or a new user
account.

Installing AR System server with BMC Remedy Single Sign-On
Related topics
Managing user groups (for more information about administrative user accounts for BMC products)
Installing AR System server with BMC Remedy Single Sign-On

You must install or upgrade the AR System server to version 8.1 as part of the BMC Atrium Single Sign-On
configuration.
Recommendation
When you are installing BMC Remedy AR System, BMC recommends:
(WAN).
Install BMC Remedy Mid Tier on a separate computer from the AR System server.
Before you begin
Install the SSO server.

Prepare to run the AR System installer for your operating system.
you are using Windows. For more information, see Preparing the Windows environment.
Make sure that 32-bit or 64-bit JRE is installed.
Review the planning spreadsheet for AR System installations.
To install or upgrade the BMC Remedy AR System server
1. Download the AR System installer, or navigate to the installation directory on the CD.
2.
2. Unzip the suite installer (ARSuiteKitWindows.zip).

a. Select Install.
b. Select AR System Server.
The default location is C:\Program Files\BMC Software\ARSystem.
d. Click Next.
8. Create an AR System administrator user with a strong login name and password to use with Atrium Single
Sign-On.
Note
To correctly configure Atrium Single Sign-On, the AR System administrator user requires a
password. You cannot use the default installed Demo user with no password.
9. Enter the values from the planning spreadsheet for the features that you want to install.
Note
10. Click Next.



Installing BMC Remedy Mid Tier with BMC Remedy Single Sign-On
Related topics
For detailed information on installing the AR System, see:

Installing BMC Remedy Mid Tier with BMC Remedy Single Sign-On
You must install the BMC Remedy Mid Tier to version 8.1 as part of the BMC Single Sign-On configuration.
Recommendation
When you are installing BMC Remedy AR System, BMC recommends:
(WAN).
Install BMC Remedy Mid Tier on a separate computer from the AR System server.
Do not install BMC Atrium Single Sign-on and BMC Remedy Mid-Tier on the same computer. BMC
Atrium Single Sign-on and BMC Remedy Mid-Tier must use different Tomcat instances because if
the mid-tier computer needs to be restarted, all the other applications will be unavailable because
BMC Atrium Single Sign-on will be down during the restart.
Before you begin
Install the BMC Single Sign-On server.

Prepare to run the AR System installer for your operating system.
you are using Windows. For more information, see Preparing the Windows environment.
Install the 32-bit or 64-bit JRE and JDK 1.6.0_23 or higher.
Set the JAVA_HOME and JRE_HOME environment variables.
For Solaris, JDK7 has a different folder structure than JDK6. For example, set the JDK7 JAVA_HOME
to /data1/software/jdk1.7.0_05/bin/sparcv9/.
Review the planning worksheet for AR System installations.

To install or upgrade the BMC Remedy Mid Tier
1. Download the AR System installer, or navigate to the installation directory on the CD.
2. Unzip the suite installer (ARSuiteKitWindows.zip).
a. Select Install.
b. Select AR System Mid-Tier.
The default location is C:\Program Files\BMC Software\ARSystem.
d. Click Next.
8. In the AR System Server List panel, perform the following actions:
a. Enter the fully-qualified domain names of the AR System servers.
b. Enter the remaining values:
c. Click Next.
9. Enter the values from the planning worksheets for the features that you want to install.
Note
10. Click Next.



Configuring the BMC Atrium Single Sign-On server for AR System
Related topics
For detailed information on installing the AR System, see:

Configuring the BMC Atrium Single Sign-On server for AR System

The included page could not be found.

Running the SSOARIntegration utility on the AR System server
Running the SSOARIntegration utility on the AR System server

Performing the Single Sign-On integration with the BMC Remedy AR System server and the BMC Remedy Mid Tier
is a two-step sequence:
1. Run the SSOARIntegration utility on the computer where the AR System server is installed (this procedure).
2. Run the SSOMidtierIntegration utility on the computer where the Mid Tier is installed .
Before you begin
Make sure that Oracle JRE 1.6.0_23 or higher is installed on the AR System server.
If you have enabled FIPS-140 mode in BMC Atrium Single Sign-On, you must install the FIPS encryption on
AR System server before running the SSOARIntegration utility.
To run the SSOARIntegration utility to integrate Single Sign-On and the AR System server
1. On the computer where the AR System server is installed, navigate to the

<ARSystemServerInstall>\artools\AtriumSSOIntegrationUtility directory.
For example, navigate to C:\Program Files\BMC Software\ARSystem\artools\AtriumSSOIntegrationUtility.
2. Open the arintegration.txt file and update the parameters for your environment.
For example, you can enter the supported container types such as Tomcat 6, JBOSS v4, and so on.
Tip
When you are using a BMC Atrium SSO load balancer, you must add the load balancer URL in the
--atrium-sso-url parameter instead of adding the server URL.

#AR Server Name, Provide the AR server name.

--ar-server-name=arsystemserver.bmc.com
#AR Server User, Provide the AR server user.

--ar-server-user=Demo
#AR Server Password, Provide the AR server password.

--ar-server-password=Demo
#AR Server Port, Provide the AR server port.

--ar-server-port=0
#Atrium SSO URL, Provide the Atrium SSO URL

#and and make sure the server name is
#provided with fully qualified domain name
#and port is also provided in the URL.
--atrium-sso-url=https://ssoserver.bmc.com:8443/atriumsso
#Atrium SSO Admin Name

--admin-name=amadmin
#Atrium SSO Password

--admin-pwd=ssoadminpassword
#TrustStore Path, Path to the truststore directory.

#This is an optional parameter.
#Remove # to uncomment and use the below property.
#--truststore=truststorepath | Optional parameter.
#TrustStore Password. This is an optional parameter.

#--truststore-password=truststorepassword | Optional parameter.
#force option, It accepts values as "Yes" or "No" where default is "No".

#If "Yes" is provided then utility will not wait
#for user to shutdown the webserver, if not shutdown already.
#This is true in case, where webserver is other then tomcat or jboss.
#--force=<Yes or No>
Note
Blank passwords are not supported. Your AR System server user must have a password
before you run this utility.
Fully-qualified domain names for the AR System server and Atrium SSO URL parameters are
required.
The --truststore=truststorepath and --truststore-password=truststorepassword parameters
are optional when integrating Single Sign-On and the AR System server. The #TrustStore
Path is the local java truststore path and the value is used for providing the path of the

certificate. This value is added automatically by the SSOARIntegration utility using the local
java truststore.
The --force=Yes or No parameter is optional. If you pass this input, you are not prompted
for any manual inputs to restart the AR System server and the server is started
automatically. Otherwise, you are prompted to restart the AR System server.
Review the optional inputs carefully for your environment.
3. Open a command window and navigate to the

<ARSystemServerInstall>\artools\AtriumSSOIntegrationUtility directory.
4. Enter the following command:
java -jar SSOARIntegration.jar -Datsso.sdk.in.fips140.mode=true --inputfile arintegration.txt
5. When prompted by the utility, restart the AR System server.

6. Review AR server external authentication settings and group mapping and restart the AR System server.
7. When execution is successfully completed, run the SSOMidtierIntegration utility on the Mid Tier.
Info
To troubleshoot installation failures, or for information about log files or configurations

performed by the SSOMidtierIntegration utility, see Troubleshooting AR System server and Mid
Tier integrations.
Reviewing AR server external authentication settings and configuring group mapping

Running the SSOMidtierIntegration utility on the Mid Tier
Running the SSOMidtierIntegration utility on the Mid Tier

After you ran SSOARIntegration utility on the computer where the AR System server is installed, you must now
run the SSOMidtierIntegration utility on the computer where the Mid Tier is installed.
Note
When BMC Remedy Mid Tier is deployed in cluster environment, you must run the SSOMidtierIntegration
utility on the all the computers where the Mid Tier is installed.

Before you begin
Make sure that Oracle JRE 1.6.0_23 or higher is installed.

Before you begin, perform the BMC Atrium Single Sign-On and AR System server integration.
If the Mid Tier web server is not Tomcat or JBoss, verify the Mid Tier URL before passing it as an input; you
cannot verify it later when the web server is shut down.
If you have enabled FIPS-140 mode in BMC Atrium Single Sign-On, you must install the FIPS encryption on
mid tier server before running the SSOARIntegration utility.
To run the SSOMidtierIntegration utility to integrate Single Sign-On and the Mid Tier
1. On the computer where the Mid Tier is installed, navigate to the

<MidTierInstall>\AtriumSSOIntegrationUtility directory.
For example, navigate to C:\Program Files\BMC Software\ARSystem\midtier\AtriumSSOIntegrationUtility.
2. Open the midtierintegration.txt file and update the parameters for your environment.
For example, you can enter the supported container types such as Tomcat 6, JBOSS v4, and so on.
Tip
When you are using a BMC Atrium SSO load balancer, you must add the load balancer URL
in the --atrium-sso-url parameter instead of adding the server URL.
When you are using a mid tier load balancer or reverse proxy, you must add the
--web-app-url and --notify-url URLs. In this case, add the load balancer URL in the
--web-app-url parameter and add the mid tier URL in the --notify-url parameter.
When you are not using a mid tier load balancer, do not use the --notify-url parameter
and add the mid tier URL in the --web-app-url.
# Install mode, it accepts values as "Install" or "Uninstall" and it is case insensitive.

# Provide "Install", if you want to install the agent. Provide "Uninstall", if you want to
Uninstall the Agent.
--install-mode=Install
# Container Type, Type of webserver being used to host midtier

--container-type=TOMCATV6
# Supported container types include JBOSSV4, JBOSSV5, SERVLETEXECV5, SERVLETEXECV6,
# TOMCATV5, TOMCATV6, TOMCATV7, WEBSPHEREV6, WEBSPHEREV7, WEBLOGICV10
#Web App URL, Provide the midtier URL in case load balancer is not there otherwise provide the load
balancer url,
# and make sure the server name is provided with fully qualified domain name
# and port is also provided in the URL.
#--web-app-url=MidtierURL or LoadBalancerURL
--web-app-url=http://midtierloadbalancer.bmc.com:8080/arsys
#Container Base Directory, Provide the webserver home directory.

--container-base-dir=C:\Program Files\Apache Software Foundation\Tomcat6.0
#JRE Path, Provide the path to the JRE home and make sure that you haven't provided till "bin".
--jre-path=C:\Program Files\Java\jre7
#Midtier Home, Midtier Home Directory

--midtier-home=C:\Program Files\BMC Software\ARSystem\midtier
#Midtier URL, Provide the midtier URL here in case load balancer is being used.
#--notify-url=http://midtier.bmc.com:8080/arsys
#Atrium SSO URL, Provide the Atrium SSO URL and and make sure the server name is
# provided with fully qualified domain name and port is also provided in the URL.
#If SSO load balancer is used, add the Atrium SSO load balancer URL instead of Atrium SSO server
name.
--atrium-sso-url=https://ssoserver.bmc.com:8443/atriumsso
#Atrium SSO Admin Name

--admin-name=amadmin
#Atrium SSO Password

--admin-pwd=ssoadminpassword
#TrustStore Path, Path to the truststore directory. This is an optional parameter.

#--truststore=truststorepath | Optional parameter.
#TrustStore Passowrd. This is an optional parameter.

#--truststore-password=truststorepassword | Optional parameter.
#The Atrium SSO realm that this agent will use for user authentication. Default is /BmcRealm.
#--agent-realm=RealmName
#force option, It accepts values as "Yes" or "No" where default is "No".

#If
"Yes" is provided then utility will not wait for user to shutdown the
webserver, if not done already in case, webserver is other then tomcat
or jboss.
--force=<Yes or No>
#Server
Instance Name, Provide the name of Websphere instance name being used.
It is required only in case Websphere being used to host the midtier.
#--server-instance-name=WebSphere server instance name
#Server
Instance Name, Provide the path to the Websphere instance configuration
directory. It is required only in case Websphere being used to host the

midtier.
#--instance-config-directory=WebSphere server instance configuration directory
#Weblogic Domain Name, Provide the Weblogic domain name. It is required only in case WebLogic being
used to host the midtier.
#--weblogic-domain-home=Domain Name
Note
Blank passwords are not supported. Your AR System server user must have a password
before you run this utility.
Fully-qualified domain names for the AR System server and BMC Atrium SSO URL
parameters are required.
If necessary, you can run the SSOMidtierIntegration utility multiple times, for example, to
install or uninstall the integration (depending on the install-mode setting in the
midtierintegration.txt file). The utility checks if an agent exists from a previous installation. If
an agent exists, the utility uninstalls it and then re-installs a new agent.
Review the optional inputs carefully for your environment.
3. Save your changes to midtierintegration.txt.

4. At the command prompt or shell window, navigate to the <MidTierInstall>\AtriumSSOIntegrationUtility
directory.
5. Enter the following jar command at the command prompt:
java -jar SSOMidtierIntegration.jar --inputfile midtierintegration.txt
6. Manually shut down the web server if you are prompted by the utility.
Note
The utility automatically shuts down Tomcat and JBoss.
7. When execution is successfully completed, open the BMC Atrium SSO Admin console.
The URL to open the BMC Atrium SSO Admin console is:
https://<ssoServer>.<domain>:<port>/atriumsso
For example:
https://ssoServer.bmc.com:8443/atriumsso/atsso

Note
To troubleshoot installation failures, or for information about log files or configurations

performed by the SSOMidtierIntegration utility, see Troubleshooting AR System server and Mid
Tier integrations.
8. When you are prompted that you are connecting to an insecure or untrusted connection, add the
exception and then continue.
9. Under Agents List, verify that the agent was created.
For example, /arsys@MidTier.labs.bmc.com:8080 should be present.
Reverse proxy URLs
Important
Before you pass the reverse proxy URL as input in the utility command, make sure that you can log
on to the application using the reverse proxy URL from the Mid-Tier computer where the
command is run.
If the reverse proxy server and the Mid Tier are installed on the same computer, stop the reverse
proxy server before you run the SSOMidtierIntegration utility with the Mid Tier. When the utility
completes its operation, restart the reverse proxy server.
If you must use reverse proxy URLs to run the Mid-Tier integration with the SSOMidtierIntegration utility, the
utility works with or without ports in the --web-app-url parameter.
1. Configure BMC Atrium Single Sign-On for AR authentication and set up users and groups .
Note

1.
If you do not plan to use BMC Atrium Single Sign-On AR authentication and plan to use different
authentication methods, see Configuring after installation.
To use and manage authentication chaining, see Managing authentication modules.
To set up and manage users and user groups, see Managing users and Managing user
groups.
2. Run a health check on the BMC Atrium Single Sign-On installation.
Running a health check on the BMC Atrium Single Sign-On installation

After you finish all these procedures, run a health check of your integration of BMC Atrium Single Sign-On with
To run a health check on the BMC Atrium Single Sign-On integration
1. Log on to the BMC Remedy Mid Tier Configuration Tool.

The default path is http://<FQDN midtier server>:<port>/arsys/shared/config/config.jsp.
For example:
http://Midtier.bmc.com:8080/arsys/shared/config/config.jsp
Tip
Clear the cache on your browser if you see redirect errors.
If your integration is successful, you should see the normal Mid Tier configuration logon, not the BMC
Atrium SSO logon screen.
2.
2. In the AR Server Setting panel, verify that the list of AR System servers includes their fully-qualified domain
names.
3. Log on to the AR System server.
For example:
http://Midtier.bmc.com:8080/arsys
The BMC Atrium Single Sign-On server redirects the server URL to the BMC Atrium Single Sign-On server,
and the BMC Atrium SSO logon screen appears.
4. Enter the User Name and Password of an AR System user and then click Log In.
If BMC Atrium Single Sign-On is properly integrated and configured, the Applications startup page appears.
Configuring the connection to the BMC Atrium SSO integration

The BMC Remedy AR System server is integrated with the BMC Atrium Single Sign-On solution by a new Atrium
Single Sign-On plug-in. To configure this plug-in, you must provide values for certain configuration parameters
on the new Atrium Single Sign-On Integration tab, located on the AR System Administration: Server Information
form.
Alternatively, you can also perform the Atrium Single Sign-On integration related configuration while installing
the AR System server. To do this, you must provide the values for the configuration parameters on the new
Atrium Single Sign-On Configuration screen after selecting the Configure Atrium SSO check box.

Note
To activate the connection to BMC Atrium Single Sign-On, use the Atrium SSO Integration tab of the AR
System Administration: Server Information form.
BMC Atrium Single Sign-On integration is supported only on web clients. For information about
manually configuring the mid tier for Atrium Single Sign-On integration, see Manually configuring mid
tier for BMC Atrium Single Sign-On user authentication.
Before you begin

Install the BMC Atrium Single Sign-On server
Note
The BMC Atrium Single Sign-On Tomcat server cannot be shared with any product (for example, the AR
System server or the BMC Remedy Mid Tier) that integrates with BMC Atrium Single Sign-On. BMC
recommends that BMC Atrium Single Sign-On be the only application in the Tomcat server.
To configure the connection to the BMC Atrium Single Sign-On Solution
1. From the mid tier interface, open the AR System Administration Console, and click System > General >
Server Information.
2. In the AR System Administration: Server Information form, click the Atrium SSO Integration tab.
AR System Administration: Server Information form--Atrium SSO Integration tab
3. Enter the BMC Atrium Single Sign-On server Location.

Host Name--The host name of the computer where BMC Atrium Single Sign-On server is
configured. If the AR System server and BMC Atrium Single Sign-On server are in same domain, enter
the machine name or the machine name with domain name. Make sure that the BMC Atrium Single

3.
Sign-On host name is accessible from the machine where AR System server is installed. If the AR
System server and BMC Atrium Single Sign-On server are in different domains, a trust relationship
between these two domains must be established before configuring BMC Atrium Single Sign-On
server.
Note
Use the FQDN for the BMC Atrium Single Sign-On server host name, not simply the host
name.
Port number — The port on which BMC Atrium Single Sign-On server is configured (typically 8443).
Protocol — (optional parameter) The default value for this parameter is https. However, this field can
also be set to http. For example:
https://<server>:<port>/<AtriumSSO-URI>
https://ssoServer.bmc.com:8443/atriumsso]
4. Enter the Atrium Single Sign-On Admin User.
The BMC Atrium Single Sign-On administrator name, by default, is amadmin.
5. Enter the Atrium Single Sign-On Admin Password.
6. (Optional) Enter the Atrium Single Sign-On Keystore Path.
The keystore file location is where the BMC Atrium Single Sign-On keystore is saved. This path includes the
keystore file name. Enter this value only if you have configured a keystore. This field is not mandatory and
you can define it later.|
7. (Optional) Enter the Atrium Single Sign-On Keystore Password.
Enter this value only if you specify the Keystore path.
8. Click Apply.
For more information on a full single sign-on solution that includes BMC Atrium, see the Knowledge Base article
KA286851. You must have a BMC customer support account to access this information.
The example is not a supported product and there is no implied support if you use it.

Manually configuring mid tier for BMC Atrium Single Sign-On user authentication
11.4.8 Installing a stand-alone Atrium Integrator server

This topic describes the installation of the Atrium Integrator server in a stand-alone configuration (without a BMC
Remedy AR System server on the same computer).

This type of stand-alone implementation of the Atrium Integrator server for BMC Remedy AR System is intended
for customers who want to transfer data to BMC Atrium CMDB from a computer where a BMC Remedy AR
System server is not installed. For example, BMC Remedy OnDemand customers might want to install the Atrium
Integrator server on a separate computer for transferring data between BMC Atrium CMDB and their data center
server (typically, the remote computer on which the Atrium Integrator server is installed).
Important
BMC supports the stand-alone implementation of the Atrium Integrator server for BMC Remedy AR
System on Windows only.
Downloading the diserver folder

When you install BMC Remedy AR System, the installer deploys the diserver folder that contains:
The data-integration folder

The ardbc_plugin folder
The .kettle folder
When you install the Atrium Integrator server, the installer deploys the ngie folder inside data-integration.
For Atrium Integrator server to function correctly without the presence of BMC Remedy AR System, the diserver
folder must be present on the computer on which you plan to install the Atrium Integrator server.
1. Create a folder named ARSystem following a similar path as the BMC Remedy AR System installation
directory. This path is typically C:\Program Files\BMC Software\ARSystem.
2. Create a temporary folder anywhere on your computer.
3. Open the ARSystemfolder of an existing installation of AR System.
Important
Make sure that the Atrium Integrator server is installed on this computer.
4. Copy the diserver folder from this folder to the newly created ARSystem folder on the remote computer.
Configuring a stand-alone BMC Atrium Integrator server
1. Create a folder called Conf under the ARSystem folder (on the remote computer).
2. On the computer on which BMC Remedy AR System is installed, open the Conf folder from the C:\Program
Files\BMC Software\ARSystem directory.
3. Copy the ar.cfg file from this folder to the Conf folder that you created on the remote computer.
4.
4. From C:\Program Files\BMC Software\ARSystem\diserver\data-integration open the set-pentaho-env.bat

file in a text editor.
5. Set the PENTAHO_JAVA_HOME parameter to reflect the value of the Java home path.
6. Save your changes.
7. From C:\Program Files\BMC Software\ARSystem\diserver\data-integration, open the Carte.bat file in a text
editor.
8. Set KETTLE_HOME to reflect the path of the diserver folder. For example, if you copied diserver folder to
C:\Program Files\BMC Software\ARSystem, set KETTLE_HOME to C:\Program Files\BMC
Software\ARSystem\diserver.
10. From C:\Program Files\BMC Software\ARSystem\diserver\data-integration, open the Spoon.bat file.
11. Set KETTLE_HOME to reflect the path of the diserver folder. For example, if you copied diserver folder to
C:\Program Files\BMC Software\ARSystem, set KETTLE_HOME to C:\Program Files\BMC
Software\ARSystem\diserver.
13. On the command line, launch the BMC Atrium Integrator Spoon by running the Carte.bat file from the
diserver folder.
Configuring BMC Remedy AR System to communicate with the stand-alone Atrium

Integrator server
1. Open the UDM:Config form in a browser. You can access this form with the following syntax:
http://<ARsystemMidtier>:<port>/arsys/forms/<ARsever>/UDM:Config
2. Set Atrium Integrator Engine Server Name to reflect the name of the remote computer.
4. In a browser, open the UDM:RAppPassword form.
5. Set Server Name to reflect the name of the remote computer.
6. Set RApp Passwordto reflect the Remedy Application Service password.
You can find this password in the ar.cfg file.

8. Open the UDM:PermissionInfo form and set Atrium Integration Engine Server Name to reflect the name of
the remote computer for all sample jobs. (Assign the remote computer on this form if you create a job
without schedule information.)
Note
For CSV and XML type of jobs, copy the source files on the AR System server and remote computer with
a similar folder structure. For more information, see Editing Atrium Integrator transformation properties.

Configuring AIE to AI Migration Tool

The AIE to AI Migration Tool enables you to automate the migration of your existing BMC Atrium Integration
Engine data exchanges to corresponding jobs or transformations in Atrium Integrator. For migrating exchanges
from The Atrium Integration Engine to the Atrium Integrator server installed on the remote computer, configure
the AIE to AI Migration Tool.
1. From the data-integration folder residing at C:\Program Files\BMC Software\ARSystem\diserver, open the
aimt.cmd file in a text editor.
2. Set JAVA_HOME to reflect the path of the Java home directory.
3. Set AI_HOME to reflect the path to the data-integration folder (typically, C:\Program Files\BMC
Software\ARSystem\diserver\data-integration).
5. From the Command Prompt, run the aimt.cmd file to launch AIE to AI Migration Tool.
6. After the migration of data from Atrium Integration Engine to the Atrium Integrator server is complete,
open the UDM:PermissionInfo form in a browser.
7. Set Atrium Integration Engine Server Name to reflect the name of the remote computer.
11.4.9 Installing multiple instances of BMC Remedy AR System on one

computer
Using the ARSuiteKit installer, you can install BMC Remedy AR System features (for example, the BMC Remedy AR
System server, Email Engine, and Approval Server) in multiple directories on one computer.
Note
You cannot install multiple instances of features by using the client installers (ARClientsSuiteKit and
ARDeveloperSuiteKit).
Additionally, you cannot install multiple instances of BMC Remedy Migrator on the same computer.
For the BMC Remedy Encryption Security products, you must install these products into a single
directory on the computer. You can then install and uninstall encryption on multiple instances of BMC
Remedy AR System in any directories on the computer.
To install multiple instances
1. Run the suite installer and choose a directory for the first installation.
2. Run the installer again, and choose different directory for the installation.
3. Repeat the installation process as needed.
You can install the same or different features in the various directories.

Tips for installing BMC Remedy AR System server

When installing a new instance of the BMC Remedy AR System server, be sure to enter:
A different BMC Remedy AR System installation location

Unique network-resolvable instance names
Uniquely named tablespaces (or devices)
Additionally, only one instance of BMC Remedy AR System server can use the portmapper, so do not select the
portmapper option for more than one server instance. Generally, all specifically named port numbers used for
one instance should be different from the ports for other instances. For more information, see Understanding
port numbers.
Limitations for installing on Windows platforms

Multiple instances of the following features on Windows platform have these additional limitations:
Only one Flashboards server can be supported at a time.

Only one mid tier installed on Microsoft Internet Information Server with Tomcat can be supported at a
time.
Numbering scheme for multiple instances

Each installation is numbered, so when you want to uninstall a feature, the BMC Remedy AR System installations
are labeled accordingly, for example, "BMC Remedy Action Request System 8.1 Install 1," "BMC Remedy Action
Request System 8.1 Install 2," and so on.
The following table shows an example scenario:
Example installation of multiple instances
Destination Folder Feature Add or Remove Programs entry
C:\A BMC Remedy Mid Tier BMC Remedy Action Request System 8.1 Install 1
C:\A Email Engine BMC Remedy Action Request System 8.1 Install 1
C:\B BMC Remedy AR System server BMC Remedy Action Request System 8.1 Install 2
C:\B BMC Remedy Mid Tier BMC Remedy Action Request System 8.1 Install 2
C:\C BMC Remedy AR System server BMC Remedy Action Request System 8.1 Install 3
In this scenario, if you use the Add or Remove Programs window to uninstall a feature from "BMC Remedy Action
Request System 8.1 Install 1," all of the features installed in C:\A are listed (BMC Remedy Mid Tier, and Email
Engine). You can select one or more of the features that you want to uninstall. If you select some (but not all) of
the installed features, "BMC Remedy Action Request System 8.1 Install 1" remains in the Add or Remove Programs
window after you uninstall the selected features. If you select all of the features, "BMC Remedy Action Request
System 8.1 Install 1" is removed entirely.

So that you know the installation to which a client belongs, the options in the Start menu are also numbered, for
example:
Start > All Programs > BMC Software > BMC Remedy AR System 1 > BMC Developer Studio .
If installed, the client tools appear in the Start > All Programs menu as follows:

BMC Remedy Mid Tier Configuration Tool
11.5 Post-installation procedures

After you complete the installation, you might need to perform post-installation procedures depending upon the
features you installed.
See also:
SNMP Configuration form in the AR System Administration Console

FTS Configuration form in the AR System Administration Console
See more configuration topics in Configuring after installation.
11.5.1 BMC Remedy AR System server post-installation procedures

This section describes tasks you can perform after you install BMC Remedy AR System.
Starting and stopping the BMC Remedy AR System server manually

The installation script starts the BMC Remedy AR System server automatically, but you can stop the server and
start it manually to verify the installation or troubleshoot problems.
To start or stop the BMC Remedy AR System server on Windows
1. Access the Services screen.

a. Go to Start > Settings > Control Panel.
b. Double-click Administrative Tools.
c. Double-click the Services icon.
2. Select the appropriate server.
The first or the only BMC Remedy AR System server installed on a computer is called BMC Remedy
Action Request System server.
Additional servers are listed as BMC Remedy AR System serverName.
3.
3. Choose Action > Start or Action > Stop, as required. If you want to stop other BMC Remedy AR System
services, stop them in the following order:
a. BMC Remedy AR System server
b. BMC Remedy Email Engine
c. BMC Remedy AR System Portmapper
To start or stop the BMC Remedy AR System server on UNIX
1. Log in as root.
In a non-root installation, log in as the user who starts the BMC Remedy AR System server.
2. Enter the arsystem stop or arsystem startcommand:
<ARSystemInstallDir>/bin/arsystem start
<ARSystemInstallDir>/bin/arsystem stop
Warning
Do not use the kill -9 command to stop the BMC Remedy AR System server, or your database
might be left in an inconsistent state.
Increasing the default maximum memory growth on HP-UX

Use the following procedure to increase the current default maximum memory growth potential of arserverd,
you can use the chatr utility.
To increase the default maximum memory growth
1. Configure the file system for large files. To verify this, enter:
fsadm -F vxfs /d1
You will see the following output if it is configured for large files:
largefiles
If the output displays nolargefiles, see the man pages for fsadm. If you do not configure your file
system for largefiles and a process core dump failure occurs, the core file will be truncated if the resident
memory size of the process is greater than 2 GB.
2. Enter the following command to set ulimit to unlimited:
ulimit -d unlimited
Setting the Next-ID-Block-Size parameter value

After installing or upgrading AR System, set the Next-ID-Block-Size parameter value to 100 in the ar.cfg or ar.conf
file on the AR System server.

For more information, see Allocating blocks of Next-IDs for faster create operations and Defining next ID block
size, cache, status history, and tags.
Important
If you have not done so already, perform this task immediately after completing the AR System install or
upgrade and before installing other applications like Atrium or ITSM.
Setting the LD_LIBRARY_PATH variable

Before running the driver for the BMC Remedy AR System server on a UNIX system, add an entry to the library
path environment variable (LD_LIBRARY_PATH). This variable is not set by default. The following examples show
how to adjust the variable if you are using the Bourne shell:
AIX
LIBPATH=$LIBPATH:/<ARSystemServerInstallDir>/bin
export LIBPATH
HP-UX
SHLIB_PATH=$SHLIB_PATH:/<ARSystemServerInstallDir>/bin
export SHLIB_PATH
Solaris and Linux
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/<ARSystemServerInstallDir>/bin
export LD_LIBRARY_PATH
Configuring environment variables for armonitor

After you install BMC Remedy AR System, you might determine that the following environment variables should
be set for your environment. After setting any of these variables, restart armonitor.
V_WAIT_BEFORE_STARTUP — Wait time period in seconds before starting the AR System server.
V_WAIT_BEFORE_POLLING — Wait time period in seconds that armonitor waits for the AR System server
to start (the default is 900).
V_SERVER_NAME — AR System server name. This value is overridden by the -s <serverName> parameter
in the command line or by Server-Name in the ar.cfg (ar.conf) file.
V_LOGFILE_NAME — Log file name for armonitor output. This is different from the data logged in
armonitor.log. The armonitor process normally writes output to the screen when started manually.
Setting this variable enables armonitor to write the information to a log file.

In UNIX environments, you can set them in the armonitor script or user shell environment. In Windows
environments, set the system variables. Alternatively, if the AR System server runs as a specific user, you can set
the individual user variable for that account.
11.5.2 Mid Tier post-installation procedures

This section describes the tasks that you should complete after you install the mid tier. It also includes some
troubleshooting tips. The following topics are included:
For complete configuration information, see BMC Remedy Mid Tier configuration.
Verifying that the mid tier is working

To verify if the mid tier is working, access the following URL:
http://<yourWebServer>:<optionalPortNumber>/arsys/shared/config/config.jsp
For example:
http://XYZCompany:8080/arsys/shared/config/config.jsp
Verifying that the JSP engine has the proper permissions

If you are using the existing ServletExec, Tomcat JSP engine, or JBOSS, make sure that the JS engine process
owner has read, write, and execute permissions to the mid tier installation directory:
Windows: C:\Program Files\BMC Software\ARSystem\midtier

UNIX: /opt/bmc/ARSystem/midtier
If you are installing Tomcat from the suite installer, make sure that the Tomcat's destination directory (for
example, /opt/apche/Tomcat6.0) has read, write, and execute permissions for the user running the installer.
Proxy server and load balancer settings

The mid tier implementation is in a servlet filter, which overrides the HttpServletResponse.sendRedirect(String
Url) method so that all redirects that the mid tier sends are relative. (The standard
HttpServletResponse.sendRedirect(String Url) method makes the URLs absolute.)
To enable the filter, edit the web.xml file or use the servlet container's administration console to add the filter.
See Enabling filter parameters.
When using proxy servers, remember:
If the proxy server does not support reverse proxy, you must use a proxy filter.

Sometimes SSO and proxy caches can conflict. If the proxy uses a cache, it can cause outdated or
incorrect JavaScript to be delivered to the browser.
Behavior when the servlet filter is not active

If the filter is not active, redirect URLs in the Location HTTP header of the response sent from the mid tier using
the following format:
"http[s]://<localWebServerName>.<domainName>.com/arsys/path/to/resource"
In this example, <localWebServerName>.<domainName>.com is the host name or domain name where the
servlet engine is running. That host name or domain name is incorrect in reverse proxy and load balanced
environments.
Some proxy servers cannot overwrite <hostName>.<domain> in the Location HTTP header of the redirect
response. Those proxy servers cannot connect the URL back to the proxy server's <hostName>.<domain>. The
URL sent to the browser in these cases is not back through the proxy server, but includes a host name that is not
resolvable nor routable from the external network.
When the host name changes from the original URL that is used to initially connect through the proxy, the
browser does not send the proper cookies that the servlet engine and mid tier set for session tracking and other
functions. The URL in the Location HTTP header of redirect responses is sometimes wrong in load balanced
environments, because the local host name of one of the web servers in the farm does not match the virtual host
name of the load balancer.
If the filter is not active, the URL in the redirect response is:
"http[s]://<internalServerSomewhereOnAnother>.<internalDomain>.com/arsys/shared/login.jsp"
This URL cannot make it back through the proxy server.
Similar problems occur with cookies that the servlet engine and mid tier return. Some proxy servers cannot
change the Set-Cookie HTTP header to reset the path on cookies to the proxy server's alias for web applications
behind the proxy. In these cases, the proxy has an alias that directs requests to different internal web servers (for
example, http[s]://external.hostname.somewhere.com/helpdesk directs HTTP requests to a mid-tier application,
and http[s]://external.hostname.somewhere.com/marketing directs HTTP requests to a different internal web
server). The path for cookies that the servlet API returns is incorrect, and the following actions must occur:
The proxy server must adjust the path. By default, the servlet API sets the cookie path to the name of the
application context path. For the mid tier, the path usually is /arsys.
The filter parameters must be enabled as described in Enabling filter parameters. You can reset the path for
cookies to /helpdesk or simply to the root path (/).

Warning
Some servlet engines cannot reset the cookie path for the JSESSIONID cookie, even with the filter
parameters enabled.
Behavior when the servlet filter is active

If the filter is active, redirect URLs in the Location HTTP header of the response sent from the mid tier using the
following format:
"../../../../path/to/resource"
The browser receives this relative URL and calculates the full URL to access the resource. For example, when the
filter is active, the redirect to the login.jsp response from the URL:
http[s]://<correctProxyServerName>. <correctDomain>.com/arsys/forms/arserver1/sampleForm/sampleView
to login.jsp is similar to:
"../../../../shared/login/jsp"
Enabling filter parameters

To enable the filter, add the following highlighted tags to the mid tier application's web.xml file near the top.
Tip
Make sure to preserve the order in which the XML tags appear within the web.xml file.
<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN'
'http://java.sun.com/dtd/web-app_2_3.dtd'>


<web-app>
<display-name>Remedy AR System</display-name>
Add this code to enable the filter:
<filter>
<filter-name>ProxyFilter</filter-name>
<filter-class>com.remedy.arsys.stubs.ProxyFilter </filter-class>
</filter>

<filter-mapping>
<filter-name>ProxyFilter</filter-name>
<url-pattern>/</url-pattern>
</filter-mapping>
<listener>
<listener-class>
com.remedy.arsys.stubs.SessionData$ReleaseSessionData
</listener-class>
</listener>
<servlet>
<servlet-name>SetupServlet</servlet-name>
<servlet-class>com.remedy.arsys.stubs.SetupServlet
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>

(... Rest of web.xml file ...)
Proxy servers
A proxy server services its clients' requests by forwarding requests to other servers. A client connects to the proxy
server to request a service (such as a file, connection, web page, or other resource) that is available from a
different server. The proxy server connects to the specified server and requests the service on behalf of the client.
Optionally, a proxy server can alter the client's request or the server's response. It can also serve the request
without contacting the specified server.
The mid tier does not provide out-of-the-box proxy services, but it can use third-party proxy servers.

Running Tomcat with IIS

The 64-bit version of Microsoft Internet Information Services (IIS) does not load the Tomcat ISAPI filter by default
because the Tomcat filter is designed for 32-bit platforms. Complete the following procedure to run IIS with
Tomcat on this platform.
To run Tomcat with IIS on a 64-bit version Windows 2003 Server and Windows 2008 Server
1. Install the mid tier, and choose Tomcat as the JSP engine.
2. Stop and restart IIS.
3. Open the BMC Remedy Mid Tier Configuration Tool to verify that the Tomcat ISAPI filter is working:
http://<yourWebServer>/arsys/shared/config/config.jsp
Changing the mid tier configuration password

Consider changing the mid tier configuration password after you complete the installation.
To change the mid tier configuration password
1. Start the Mid Tier Configuration Tool in a browser.

The URL is http://<webServer>:<port>/arsys/shared/config/config.jsp.
2. In the login screen, enter the default password (arsystem).
3. Click Change Password in the left panel.
4. Enter the new password.
11.5.3 Flashboards post-installation procedures

This section describes the tasks that you can perform after you install Flashboards. The following topics are
provided:
Installing and configuring Flashboards samples

The Flashboards samples show how to gather statistics. The suite installer does not prompt you to install
Flashboards samples. You must install the samples manually.
To install Flashboards samples manually
1. In the BMC Remedy AR System Navigator pane of BMC Remedy Developer Studio, right-click on the name
of the server where the samples should be installed.
2. Choose Import > Object Definitions to open the Import Objects window.
3. In the Import File field, enter the full path name for the ServerStat.def file.
Windows — C:\Program Files\BMC Software\ARSystem\flashboardserver \ServerStat.def
UNIX — /opt/bmc/ARSystem/flashboardserver/ServerStat.def
4. Click Next.
5.
5. Select the objects, and click Finish.
To configure the Flashboards samples
1. Open the AR System Administration: Server Information form.

2. Select the server that contains the installed samples.
4. In the Default Web Path field, enter the following web path:
http://<webServerName>:<port>/arsys
where <webServerName> is the name of the web server on which the mid tier is installed and <port> is
the port number. The port number is optional.
5. In the Server Statistics section, select the Cumulative Queue option.
6. Click OK to save the changes.
To configure Flashboards sample variables
1. Open BMC Remedy Developer Studio.

2. In BMC Remedy AR System Navigator, expand serverName > All Objects, where serverName is the server
that contains the installed samples.
3. Double-click Flashboards Variables.
4. In the Flashboards Variables list, double-click the Set Entry Calls Per Hour variable.
5. Open the Data Collection panel and select the Collect Data option.
6. Open the History panel and set the collection interval.
7. Save the changes.
8. Repeat this procedure for the Set Entry Calls Per Second and Total Number of Fixed Licenses variables.
Running the Flashboards server after exiting a shell

If you plan to exit a shell after starting the Flashboards server in that shell, enter the following command to start
the server:
nohup server.sh start &
When you enter this command, the Flashboards server continues running in the background after you exit the
shell.
11.5.4 IPv6 post-installation procedures

This section describes the tasks that you can perform after you install BMC Remedy AR System on an
IPv6-configured network. The following topics are provided:

Enabling LDAP plug-ins for SSL connections post-installation
Note
This topic explains how to enable LDAP plug-ins for SSL connections in configured networks after a new
installation. For information on adding a certificate for SSL communication after a new installation, see Enabling
LDAP plug-ins for SSL connections post-upgrade.
For more information about BMC Remedy AR System support for IPv6, see Support for IPv6
Adding an LDAP certificate to the certificate database

To enable LDAP plug-ins for SSL connections in configured networks after a new installation, you must add a
LDAP certificate to the certificate database for SSL communication. LDAPJ plug-ins support SSL communication
to the LDAP server. When you configure LDAP plug-ins that use SSL connections, you specify the file location of
the keystore that contains the certificate. LDAPJ then uses the Java KeyStore (JKS) type to store the certificates.
Note
Pre-8.1 releases use the NSS based keystore. For more information, see Enabling LDAP plug-ins to
establish SSL connections with LDAP servers.
To add a certificate for SSL communication after a new installation
1. Download a digital certificate from the LDAP server.

For more information, see the documentation for your LDAP server. For example, see the vendor's
documentation on how to download a certificate for an Active Directory server.
2. Create a keystore.
To create and maintain the digital certificate data stores, the Java installation provides an out-of-the-box
utility called keytool.
3. Import the downloaded certificate into the keystore by using the following command:
keytool -import -noprompt -trustcacerts -keystore <keystorePath> -storepass <password> -alias

<aliasName> -file <certificatePath>
Where:
-trustcacerts — Stores the certificate as a trusted certificate in the keystore
-keystore — The full path of the keystore file (for example C:\certdb\ldaptruststore.jks)

Note
If the keystore does not already exist, the command creates a new keystore.
-storepass — Stores the password. Keystore password must contain at least 6 characters.
-alias — The alias, or nickname, of the certificate
-file — The file path of the digital certificate (for example C:\ldapCert\cert6b.rfc)
For example, the command to import the downloaded certificate might look as follows:
keytool -import -noprompt -trustcacerts -keystore C:\certdb\ldaptruststore.jks -storepass admin

-alias bmcAlias -file C:\ldapCert\cert6b.rfc
4. List any available certificates in the keystore by using the following command:
keytool -list -keystore C:\certdb\ldaptruststore.jks -storepass admin
Where:
-list — Lists the available certificates in the store
For example, using this command can result in the following:

Keystore type: JKS
Keystore provider: SUN
Your keystore contains 1 entry
cerqa6b, Aug 2, 2012, trustedCertEntry,
Certificate fingerprint (MD5): 64:01:F3:E6:DD:A0:33:CA:E2:4A:92:50:10:51:59:70
5. Configure the full path of the certificate keystore file in the Certificate Database field in the AREA LDAP
Configuration and ARDBC LDAP Configuration forms.
Certificate Database field in the AREA LDAP Configuration form

This configures the keystore in these forms.
Updating configuration after changing from IPv4 to IPv6
Recommendation
Instead of changing a server from an IPv4 network to an IPv6 network directly, BMC recommends
leaving the server in dual mode so that the IPv4 and IPv6 clients can both connect to the server.
If you must switch a server from an IPv4 network to an IPv6 network, then follow the procedures in this
topic.
If you have installed BMC Remedy AR System and BMC Atrium Core on a server with an IPv4 address and then
changed it to an IPv6 address, you must complete the following tasks:
Before you restart the BMC Remedy AR System server after switching to an IPv6 domain, you must ensure that
the hostname, or fully qualified domain name (FQDN) in the configuration files is valid in the IPv6 environment.
Otherwise, BMC Atrium Core components might not work as expected, such as adding or editing CIs in BMC
Atrium Explorer.

To verify valid domain names for IPv6 servers

For all platforms, you need to verify that the domain name specified in the configuration files are valid in the IPv6
environment.
1. On the server where BMC Atrium Core is installed, open each of the following files in a text editor:
Windows:
<BMC_AR_SYSTEM_HOME>\conf\ar.cfg
<BMC_AR_SYSTEM_HOME>\conf\armonitor.cfg
<ATRIUMCORE_HOME>\wsc\wsregistryapi\conf\registryserver.properties
UNIX and Linux:
<ARSYSTEM_HOME>/conf/ar.conf
/etc/arsystem/<MACHINE_NAME>/armonitor.conf
<ATRIUMCORE_HOME>/wsc/wsregistryapi/conf/registryserver.properties
<ATRIUMCORE_HOME>/cmdb/server/bin/normeng.sh
<ATRIUMCORE_HOME>/cmdb/server/bin/atriumplugin.sh
2. For the plugin aliases in ar.cfg and ar.conf, verify that the specified hostname is valid on the IPv6 network.
For example, if arserver1.calbro.com:9999 is the specified hostname, check that it is valid in the IPv6
environment. If it is not, you might have to remove the domain name (arserver1:9999) or change it to a
valid hostname, such as arserver1.ipv6lab.calbro.com.
The following code is an example of plugin aliases with the domain names.
Server-Plugin-Alias: ARSYS.ARF.REGISTRY ARSYS.ARF.REGISTRY arserver1.calbro.com:9999

Server-Plugin-Alias: ARSYS.ARDBC.REGISTRY ARSYS.ARDBC.REGISTRY arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARDBC.ARREPORTENGINE ARSYS.ARDBC.ARREPORTENGINE
arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.QUERYPARSER ARSYS.ARF.QUERYPARSER arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ALRT.WEBSERVICE ARSYS.ALRT.WEBSERVICE arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.PARSEPARAMETERS ARSYS.ARF.PARSEPARAMETERS arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.PUBLISHREPORT ARSYS.ARF.PUBLISHREPORT arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.REPORTSCHEDULER ARSYS.ARF.REPORTSCHEDULER arserver1.calbro.com:9999
. . .
3. For armonitor.conf, armonitor.cfg, registryserver.properties, normeng.sh, and atriumplugin.sh, search for

and verify domain names.
The following code is an example of server entries with the domain names.
bmc.uddi.registryserver.url.security=http://webservices1.calbro.com:8080/uddi/services/security
bmc.uddi.registryserver.url.inquiry=http://webservices1.calbro.com:8080/uddi/services/inquiry
bmc.uddi.registryserver.url.publishing=http://webservices1.calbro.com:8080/uddi/services/publicationbmc.uddi.re
4. Save the edited files.
5.
5. If you have a server group configuration prior to switching from an IPv4 to IPv6 network, check and update
the entries in the AR System Server Group Operation Ranking form.
a. Open the AR System Server Group Operation Ranking form in search mode.
http://:/arsys/forms/ /GroupAR+System+Server+Group+Operation+Ranking/
b. Perform an unqualified search to see the entries in the form.
c. For each server, check the Server value.
d. Verify that the domain name is valid for all entries in the IPv6 environment.
e. If it is not, remove the domain name or change it to a valid IPv6 domain name.
f. Save the AR System Server Group Operation Ranking form.
6. Restart the AR System server and the BMC Atrium Core Web Services Tomcat server.
If you have a server group, restart all the AR System servers in the group.
To update the Administration configuration

This issue occurs in a setup in which the server group setting is present before switching the network from IPV4
to IPV6.
If you have not verified the domain names as described above in AR System Server Group Operation Ranking
form, then, on restart, the BMC Remedy AR System server might not recognize upon restart the hostname (such
as arserver1.calbro.com). It then sets that property in the server configuration information and adds a new set of
entries for the hostname in the AR System Server Group Operation Ranking.
If that happens, you must delete the new set of entries and edit the the Server Name Alias field to reflect the
correct hostname/FQDN in an IPV6 network.
1. Log in to the BMC Remedy AR System Administration Console.

2. Open the AR System Server Group Operation Ranking form in search mode.
*http://:/arsys/forms/ /GroupAR+System+Server+Group+Operation+Ranking/*
3. Perform an unqualified search to see the entries in the form.
4. For each server, check the Server value.
5. Verify that the domain name/FQDN is valid for all entries in the IPv6 environment.
6. If it is not, remove the domain name or change it to a valid IPv6 domain name.
7. Save the AR System Server Group Operation Ranking form.
8. Restart the AR System server.
11.5.5 Post-installation checks

Starting with the BMC Remedy AR System 7.6.03 release, post-installation checks were added. After the
installation of BMC Remedy AR System and its components is complete, post-installation checks are
automatically run for the components that you have selected during the installation. A sample data is run as a part
of the post-installation check, to verify if the component is installed and working correctly.
BMC Remedy AR System server post-installation check


BMC Remedy Distributed Server Option post-installation check
BMC Remedy Approval Server post-installation check
BMC Remedy Email Engine post-installation check
BMC Remedy Migrator post-installation check
Note
The status of the post-installation checks is displayed on the Installation Summary screen.
You can also run the post-installation checks through the BMC Remedy AR System Maintenance Tool using the
Health Check tab. Using this tab, you can run these checks on the components selected during the installation
any number of times after the installation is complete.
For more information, see Running a Health Check.

After installing BMC Remedy AR System, the following items are checked to make sure that the BMC Remedy AR
System server is installed and working correctly:
The connections to the database instance are created successfully.

The basic BMC Remedy AR System operations such as create and set entries, create and set forms are
working correctly.
The plug-ins are installed, are able to connect, and the plug-in server is working correctly.
If the checks fail, the following error messages are displayed on the Installation Summary screen of the installer or
on the Health Check Summary screen of the Maintenance Tool:
If the sample form cannot connect to the BMC Remedy AR System: Failed to connect to AR Server
If the sample form create operation fails: Sample form creation check failed
If the sample field create operation fails: Sample field creation check failed
If the create entry operation on sample form fails: Sample entry creation check failed
If the modify entry operation on sample form fails: Sample entry modification check failed
If the delete entry operation on sample form fails: Sample entry deletion check failed
If the modify sample form operation fails: Sample form modification check failed
If the delete sample form operation fails: Sample form deletion check failed
If there is any problem connecting to the BMC Remedy AR System server: AR Server post
installation check failed
If the communication to the plug-in server fails: Sample plugin call check failed
Note

If all the BMC Remedy AR System post-installation checks are successful, the AR Server post
installation check passed message is displayed.
BMC Remedy Assignment Engine post-installation check

After installing BMC Remedy AR System, a sample application is created for the Assignment Engine, which
contains:
Forms — DAssignee, DRequest

Assignment Process — DProcess
Assignment Rule — select driver
Filter — DRequest_trigger_assignment
Note
The data created on the sample forms is deleted once the check is executed successfully.
The sample application, that is, the forms, filter, process, and rules are created only once and re-used later.
The Assignment Engine post-installation check does the following to check if the Assignment Engine is installed
and working correctly:
Checks if the Assignment Engine process is running.

Creates a request in the DRequest sample form.
Verifies that the sample form is getting assigned to the sample assignee.
If the check fails, the following error messages are displayed on the Installation Summary screen of the installer or
on the Health Check Summary screen of the Maintenance tool:
If the Assignment Engine process is not executing correctly: Assignment Engine process is down
If the Assignment Engine process on the sample form is not working: Assignment Engine is not
functioning properly
If there is a problem communicating with the BMC Remedy AR System server: Assignment Engine post
Note
If the Assignment Engine is working correctly, the Assignment Engine post installation check
passed message is displayed.

BMC Remedy Distributed Server Option post-installation check

After installing BMC Remedy AR System, a sample application is created to verify if the Distributed Server Option
(DSO) is installed and working correctly. This sample application contains:
Forms — DSO-Sample:Source, DSO-Sample:Destination

Distributed Mapping — DSO-Sample:Mapping
Filter — DSO-Sample: DSO Transfer
Note
The sample application, that is, the forms, filter, process, and rules are created only once and re-used later.
The DSO post-installation check does the following to check if the DSO is installed and working correctly:
Checks if the DSO process is running.

Creates a request in the sample form, DSO-Sample:Source.
Verifies that the sample form is getting transferred to the sample destination form,
DSO-Sample:Destination.
If the DSO process is not running: DSO process is down

If the DSO process is not running due to the absence of a DSO license: AR Distributed Server
license is not applied
If the DSO process is not running because the DSO process entry is commented in the armonitor.cfg file:
DSO process is commented in armonitor.cfg file
If the default distributed pool of DSO is configured in polling mode: Default distributed pool is
configured as polling thread, hence can not perform DSO post install check
If the DSO is not working correctly: DSO is not functioning properly
If the DSO transfer operation on the sample form, DSO-Sample:Source is not working correctly: Sample
DSO Transfer operation check failed
If the DSO update operation on the sample form, DSO-Sample:Source is not working correctly: Sample
DSO Update operation check failed
If the DSO delete operation on the sample form, DSO-Sample:Source is not working correctly: Sample
DSO Delete operation check failed
If there is any error while communicating with the BMC Remedy AR System server: DSO post

Note
If all DSO operations on the sample forms are working correctly, the DSO post installation check
BMC Remedy Approval Server post-installation check

After installing BMC Remedy AR System, the Approval Server post-installation check does the following to check
if the Approval Server is installed and working correctly:
Checks if the Approval Server process is running.

Creates a sample data on the AP-Sample2:Get Agreement form.
Note
If the Approval Server is not working correctly or if any failure occurs during execution: Approval Server
post installation check failed
If the Approval Server process is down: Approval Server service is not running
Note
When the Approval Server is working correctly, the Approval Server post installation check
BMC Remedy Email Engine post-installation check

After installing BMC Remedy AR System, the Email Engine post-installation check does the following to check if
the Email Engine is installed and working correctly:
Checks if the Email Engine process is running.

Creates a sample data on the AR System Email Messages form.
Note

If the Email Engine process is down: Email Engine process is down

If the Email Engine is not working correctly: Email Engine is not functioning properly
If the Email Engine is not configured: Email Engine is not configured
If the mailbox polling interval is in minutes, the Email Engine post-installation check is skipped: Email
Engine is not configured for post install check execution
If any failure occurs during the working of the Email Engine: Email Engine post installation check
failed
Note
When the Email Engine is working correctly, the Email Engine post installation check passed
message is displayed. The Email Engine post-installation check also verifies remote Email Engine
installation.
BMC Remedy Migrator post-installation check

After installing BMC Remedy AR System, the Migrator post-installation check does the following to check if the
Migrator is installed and working correctly:
Checks if the Sample::Enrollments sample form is available on the BMC Remedy AR System server.
Collects the BMC Remedy AR System server login credentials from the user to check if the BMC Remedy
AR System server is running.
Executes the Run MigratorCli command for migrating the sample form from the BMC Remedy AR
System server to a temporary migrator file created in the directory where migratorcli.exe exists. A
temporary log file is also generated here.
On successfully performing the above operations, migrates the sample form from the migrator file back to the
BMC Remedy AR System server.
Note
If the Migrator license is not available on the target server: Migrator CLI run command failed

If the Sample::Enrollments sample form is not available on the target server: Migrator CLI run
command failed
If the temporary log file is not generated: MigratorCli tmp log file not found
Note
When the Migrator is working correctly, the Migrator post installation check passed message
is displayed.
11.6 Uninstalling BMC Remedy AR System features and clients

This secton describes how to uninstall the BMC Remedy AR System features and clients.
11.6.1 Uninstalling BMC Remedy AR System features

When you run the uninstaller, the BMC Remedy AR System binaries are removed, but the BMC Remedy AR System
database remains intact.
To uninstall BMC Remedy AR System features on Windows
1. Go to <ARSystemInstallDir>\UninstallBMCARSystem.
2. Double-click the uninstall.exe file.
3. Follow the wizard's prompts.
To uninstall BMC Remedy AR System features on UNIX
1. Go to <ARSystemServer>/uninstallBMCARSystem.
2. Run the uninstall file.
3. Follow the wizard's prompts.
Note
If you customize forms, any automatically installed forms are overwritten when you perform an
upgrade.

11.6.2 Uninstalling encryption security

This section explains how to uninstall the BMC Remedy Encryption Performance Security and BMC Remedy
Encryption Premium Security. The instructions assume that you have installed or upgraded to BMC Remedy
Action Request System 8.1.
Note
By design, if more than one BMC Remedy AR System component was encrypted using the BMC Remedy
Encryption Security installer, and you attempt to uninstall encryption from only one component, the
encryption unistaller will be available for uninstallation of remaining components.
To uninstall encryption on Microsoft Windows
Note
You cannot uninstall standard security because it is built into the BMC Remedy AR System API. To disable
it, see Configuring the data key.
1. Shut down any BMC Remedy AR System processes that are running.
2. From the Start menu, select Settings > Control Panel.
3. Double-click the Add or Remove Programs icon.
4. In the Add or Remove Programs dialog box, select the appropriate encryption product:
BMC Remedy Encryption Performance Security 8.1
BMC Remedy Encryption Premium Security 8.1
5. Click Change/Remove.
6. In the uninstaller Welcome screen, click Next.
Note
At any time during setup, you can click Cancel to exit the uninstaller. However, your settings up to
that point in the uninstallation process are not saved.
7. In the Select Features screen, select the encryption product to uninstall.

8. Click Next.
9. In the Uninstallation Preview screen, review the information and perform one of these tasks:
Click the Previous buttons and return to the screens that require editing, to change the
uninstallation setup.

9.
Click Uninstall to start the uninstallation.

10. When the uninstallation is finished:
a. (Optional) Click View Log to review the uninstall log file.
b. Click Done to exit the wizard.
11. Delete the arencrypt75.dll file from the folder that contains the application's arapi75.dll file to remove the
encryption libraries for a third-party or user-developed application.
12. Restart the BMC Remedy AR System server.
To uninstall encryption
Note
You cannot uninstall standard security because it is built into the BMC Remedy AR System 8.1 API. To
disable it, see Configuring the data key.
1. Shut down any BMC Remedy AR System processes that are running.
2. Delete the BMC Remedy 8.1 encryption library files.
For file names and locations, see Installing an application that communicates with encrypted servers
3. In the ar.conf file, delete the Encrypt-Security-Policy entry or change its setting to 2 (encryption is
disabled).
Optionally, you can delete all encryption entries in the ar.conf file.
4. Change the encryption policy for the Java plug-in server back to the default of 2 by editing the
pluginsvr_config.xml file and changing <encryptionPolicy>1</encryptionPolicy> to
<encryptionPolicy>2</encryptionPolicy>.
11.6.3 Uninstalling BMC Remedy Migrator

Uninstall BMC Remedy Migrator from the Control Panel on Windows.
To uninstall BMC Remedy Migrator
1. Close BMC Remedy Migrator.

2. Select Start > Settings > Control Panel.
3. From the Control Panel, select Add/Remove Programs.
4. From the Currently Installed Programs list, select BMC Remedy Migrator VerNum, and click Remove.
5. In response to the prompt, click Yes to begin the uninstall process.
6. When the uninstallation is done, click OK to close the confirmation message box.

11.6.4 Uninstallation tips for BMC Remedy Mid Tier

If you install SSO with the mid tier, when you uninstall the mid tier, you must also uninstall the web agent.
(This safely removes the reference of the mid tier URL from Atrium SSO server.) To uninstall the mid tier
successfully:
1. Shut down the mid-tier Tomcat service.
2. Uninstall the web agent by executing the deployer command with -uninstall option.
3. Uninstall the mid tier.
If you chose to install Tomcat when you installed the mid tier, you have to option to uninstall Tomcat when
you uninstall the mid tier.
If you installed Tomcat and the mid tier, and you are running Windows in an IIS environment, Redirector is
installed. Redirector is not removed during the uninstallation process. You must remove it manually.
If you upgrade BMC Remedy AR System (including AR System server and the mid tier), you can also choose
to upgrade Tomcat (for example, to version 6.0). If you then choose to uninstall your entire BMC Remedy
AR System installation using Add/Remove Programs from the Control Panel, only the newest version of
Tomcat is removed. The older version of Tomcat (for example, version 5.5) in Administrative Tools >
Services continues to exist. If you then want to install a version of BMC Remedy AR System that has the
same older version of Tomcat (for example, version 5.5) that remains on that on the same machine, you
must first remove the older version of Tomcat that remains in Services via the registry to avoid conflicts.
If you are using the Apache web server, remove the following lines from the
<ApacheInstallDir>/conf/httpd.conf file:
LoadModule jk_module modules/mod_jk.so

JkWorkersFile /usr/ar/apache-tomcat-version/conf/
arsysworker.properties
JkLogFile /usr/apache_version/logs/mod_jk.log
JkLogLevel info
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
JkOptions +ForwardURIEscaped +ForwardURICompatUnparsed
JkRequestLogFormat "%w %V %T"
JkMount /arsys/* arsysWorker1

12 Configuring after installation

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 Configuring AR System servers
Setting up a server group to provide fail-over protection Configuring server groups
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 BMC Remedy Mid Tier configuration
Using a hardware load balancer to improve the scalability and availability of the BMC Remedy AR Configuring a hardware load balancer with
System BMC Remedy AR System
Configuring Unicode database support to enable multiple languages on a single AR System server Configuring a Unicode 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 reporting
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 Configuring the BMC Remedy Approval
with flowcharts, and with a separate plug-in server instance 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 Configuring BMC Remedy Flashboards
file, and configuring flashboards
Licensing and logging on to BMC Remedy Migrator Configuring 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) Using Oracle CLOBs with BMC Remedy AR
storage in a database table System

12.1 Logging on to the system

This section explains how to log on to various BMC Remedy AR System components:
Product or Component See
BMC Remedy Data Import Starting Data Import and logging on to AR System servers
BMC Remedy Developer Studio 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
12.2 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.
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.
Tune and manage the system performance.
Set up a mid tier server to use cache table statistics.
Enable the HTTP TRACE function to return HTTP header information .
12.3 Working with BMC Remedy AR System licenses

The following topics provide information about licensing BMC Remedy AR System:
12.3.1 Adding or removing licenses

You can add or remove licenses, follow the given procedures.
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. 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 From the list, select the type of license to activate. You can also enter a custom license type that is not in the list.
Type
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 For the specified license type, enter the appropriate number of licenses.
of 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 Used to further identify license behavior

Qualifier 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 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
Date 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:
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.
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.
12.3.2 Exporting or importing licenses

You can use the Add or Remove Licenses form to export or import licenses.

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
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.
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
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.
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. See Adding licenses.
7. In the confirmation message, click OK.
12.3.3 Displaying license usage

The following topics provide information about the license usage forms and how to track license usage:
License usage forms

The following read-only forms provide data about current and historical license usage:
AR System Current License Usage

AR System Historical License Usage
The following topic provides information about how to record data in the forms:
Recording data in the license usage forms

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 Application that the license applies to

Name
License Type of license (fixed, floating, and so on)

Type
Server Server to which the license is applied

Name
Time Time that the user acquired the license

Acquired
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 Type of record used to track license usage:

Record
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)
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.
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.
Warning
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.
Tracking server group license usage

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. 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.
When the user releases one of the licenses, its subrecord is deleted. When the last subrecord is deleted, 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.
12.3.4 Reviewing license usage

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:
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
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
2. In the Add or Remove Licenses form, click Generate License Usage Report.
3. Click the arrow 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 arrow 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.
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.

6.
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).
12.3.5 Generating a license usage report

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.
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.
-o Specifies the full or relative path to the output file. By default, the output file name is ReportResult.csv and is in this directory:
(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.
-s 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.
-e 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.
-r Backs up the current LicenseReport.txt file by renaming it LicenseReport- fileCreateDate- currentDate.txt and generating a new
LicenseReport.txt file.
Note
You can also generate a license usage report from the Administration Console. See Generating a license
usage report.
12.3.6 Licensing for server groups

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.
12.4 Configuring AR System servers

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.
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 Enables you to configure passwords used between the AR System server and its external Setting server passwords, RPC
Settings subsystems. options, and plug-in timeouts
Currency Specifies currency types available in AR System. Setting currency types

Types
Database Displays information about the database that the selected server communicates with. You also Setting database options
define a database password and configuration file location in this tab.
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
Configures full text search (FTS) options. Configuring Full Text Search

Tab Information See
Full Text
Search
Licenses Displays the type and number of BMC Remedy AR System licenses on a server. You also set the Setting license options
Submitter Mode in this tab.
Log Files Enables the logging for various log files. You also set the log level in this tab. Setting log files options
Platform Displays information about the platform on which the selected server is running. Setting platform options
Ports and Configures BMC Remedy AR System to communicate with client tools, services, and other servers
Queues on the network. Displays information relevant to the user of the multiple threads in the AR System Setting ports and RPC
server. numbers
Configuring a server for
alerts
Defining queues and
configuring threads
Server Events Sets the options for logging internal server changes. Setting server logging options
Timeouts Sets various timeouts for the selected server. Setting timeout options
Version Sets source control integration within BMC Remedy AR System. Setting version control options
Control
WS Registry Enables the use of the AR System Web Service Registry form by configuring a connection to a Setting a connection to the
Integration BMC Atrium Web Services Registry. Also provides a button to update the registry. BMC Atrium Web Services
Registry
Atrium SSO Enables the integration of the AR System server with the Atrium SSO server for the purpose of Setting a connection to the
Integration single-sign on. BMC Atrium SSO server
Server Sets parameters related to server statistics. This link was added in Service Pack 1 for version Setting server statistics options
Statistics 8.1.00.
Attachment Enables you to restrict users from uploading and viewing files with certain extensions in BMC Setting security restrictions on
Security Remedy Mid Tier. This link was added in Service Pack 1 for version 8.1.00. 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.
12.4.1 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.
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.
12.4.2 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.
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.
12.4.3 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.
12.4.4 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.
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.
12.4.5 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.
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
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.
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 - BMC Remedy AR System tries to authenticate the user by using the User form, then Windows or UNIX authentication, and
AREA then the AREA plug-in.
ARS - AREA - BMC Remedy AR System tries to authenticate the user by using the User form, then the AREA plug-in, and then Windows or
OS 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.
12.4.6 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.
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).
12.4.7 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
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

3.
Field Name Description
Object Selecting Enforced causes the server to require object reservation. See Using object reservation.
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 Selecting Enabled causes the server to log every change to objects. See Using the object modification log.
Modification
Log
Save Definition Selecting Yes causes the server to write a definition file each time an object is created or changed. This option is available
Files 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.
12.4.8 Setting timeout options

Use the Timeouts tab to set the timeouts for the selected server.
To set timeouts
2. Click the Timeouts tab.
AR System Administration: Server Information form — Timeouts tab



Timeouts tab fields
Area name Field Description
Name
Process Prevents a server from being blocked when a process requested in a Set Fields filter or escalation action does not
Timeout return a value soon enough.
(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 Sets the time limit for making contact with alert clients.
Send Two attempts are made to deliver an alert and if the second attempt fails, the alert registration is removed. The
Timeout default is 7 seconds.
(seconds)
Filter API Sets the time limit (in seconds) for the Filter API RPC to respond to the server's request.
RPC The default is 40 seconds. The minimum is 1, and the maximum is 300.
Timeout
(seconds)
Floating Write Sets a time limit for how long a floating license remains reserved if the user is not accessing AR System.
License When a user is using a floating license, a license is reserved while the user is connected to the server. If the user
Timeout does not perform an AR System operation for the period of time specified in this field, the license is automatically
(hours) 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 Client Sets the interval (in minutes) that clients (for example, the Web) use when refreshing currency conversion ratios
Ratio Refresh stored on the server.
Cache Interval This refresh action makes sure that calculations for functional currencies are up to date.
Refresh
Interval
(minutes)
4. Click Apply.
12.4.9 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.
12.4.10 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.
12.4.11 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
2. Click the Platform tab.
AR System Administration: Server Information form — Platform tab


Platform tab fields
Field Description
Server Displays the version number of the BMC Remedy AR System software on the server.
Version This value corresponds to the $VERSION$ keyword.
Server Displays the folder (directory) where the AR System server is installed on the server system.
Directory
Hardware Displays the hardware platform on which the server is running.

This value corresponds to the $HARDWARE$ keyword.
Operating Displays the operating system software version running on the server system.
System This value corresponds to the $OS$ keyword.
Server Specifies an alias that is always interpreted as the current server.

Name An alias enables you to use a functional name for a server rather than a computer name (for example, ACME or HelpDesk). Do
Alias 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 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.

Field Description
Server Displays the current time on the server (in the local time zone).
Time
4. Click Apply.
12.4.12 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 System
serverName\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.
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 Description Default file Default form

log name name
API Logs information about all API calls made by all clients. arapi.log AR System
This information is logged on entry and exit of every API call. Log: API
Escalation Logs information about escalation activity. arescl.log AR System

This information includes the escalations that executed, whether the escalation qualification found any Log:
matches, and any escalation actions taken. Escalation
Filter Logs information about filter activity for each operation. arfilter.log AR System
This information includes the filters that tried to execute and all filter actions performed. Log: Filter
SQL Logs SQL commands sent to the database. arsql.log AR System

This information is logged for each SQL command issued, including a time stamp and the user name of Log: SQL
the user performing the operation.
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. aruser.log AR System
This information includes whether the user can obtain a license and when each floating license is Log: User
released. This enables you to keep an audit trail of user activity to help you determine whether you need
more floating licenses.
Alert Logs detailed information about user registration and about the generation and delivery of alerts. aralert.log AR System
Log: Alert
Full Text Logs information about full text search indexer activity. arftindx.log AR System
Index Log: Full
Text Index
Server Logs information about server group activity. arsrvgrp.log AR System

Group Records information about the starting and stopping of operations, the evaluation of other servers, and Log: Server
the timing of each event. Group
ARFORK ( On UNIX systems, logs all arforkd activity (a process that reduces the amount of memory an AR System arfork.log No form is
UNIX only server uses when forking new processes). created for
) This file is not subject to the maximum file size specified in the Maximum Log-File Size field. arforkd.

Type of Description Default file Default form

log name name
DSO If you are licensed for Distributed Server Option (DSO), logs information about DSO server activity. See ardist.log No form is
BMC Remedy Distributed Server Option logging. created for
DSO.
Plug-In Logs the events of plug-ins that AR System uses. For more information about plug-ins, see Enabling arplugin.log No form is
Server Plug-ins. created for
the plug-in
server.
For more information, see Analyzing logs.
To set log files or forms
2. Click the Log Files tab.
AR System Administration: Server Information form — Log Files tab
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 or a question
mark . 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 Description
Name
Plugin Log Specifies the level of logging for the plug-in server. The options are
Level 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.
Off — None. The default value is 10000.
Log-File Defines how logs are created. The options are

Creation 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 Defines the group that can use logging options in AR System clients. Logging options are disabled for users who are not
Logging members of this group. For more information about client logging, see Enabling logs.
Group
Maximum 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
Log-File cannot be set to less than 4096. When the log file reaches the maximum, new information wraps to the top of the file,
Size (byte) 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 Defines the maximum number of backup (.bak) log files to be allowed when the log file reaches the Maximum Log-File Size
Backups 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.
Buffer Buffers logged lines instead of having them immediately written to disk. Selecting this option decreases the impact to AR
Logged System performance when logging is enabled. See Buffering log output.
Lines
Log Per Creates per-thread log files. Selecting this option decreases the impact to AR System performance when logging is enabled.
Thread See Thread log.
8. Click Apply.

12.4.13 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
2. Click the Server Events tab.
AR System Administration: Server Information form -- Server Events tab

Server Events tab fields

Area Field Name Description
name
Server Specifies the name of the form populated with information about specific server events. BMC Remedy AR System
Events automatically generates this form, and the form is defined from a unique combination of BMC Remedy AR System
Form 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 Server Determines the objects for which changes are recorded in the Server Events form. Select the check box next to any
Event Cache of the following events to log changes to these objects:
Type Changes 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 Group form, or
Changes any user or group changes using the access control utilities arcache and arreload. Changes are recorded in the
Server Events form.
Server Determines whether an entry is created in the Server Events form as a result of an ARSetServerInfo call.
Setting
Changes
Archive Determines whether an entry is created in the Server Events form as a result of archiving data to an archive form.
Server Determines whether an entry is created in the Server Events form as a result of server group activities.
Group
Actions
4. Click Apply.
12.4.14 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.
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
2. Click the Ports and Queues tab.
AR System Administration: Server Information form--Ports and Queues tab

3. Edit the options as needed:
Ports and Queues tab fields

Server Defines the TCP/IP port number for the AR System server. Enables clients to have access to the server without a portmapper.
TCP/IP Port 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 Obsolete. See Assigning an RPC program number to DSO.

Server RPC
Program
Number
Alert The specific TCP port to which the server binds when sending alert messages to registered clients. If multiple alert threads
Outbound are started, the number represents the starting port number in a consecutive range of numbers available for the alert threads.
Port If no port number is specified or if 0 is entered, the portmapper randomly assigns an available port to the server.
Register Defines whether the AR System server and the plug-in server are registered with AR System Portmapper. If the check box is
with Selected — They are registered. The server is registered if not previously registered. AR System clients can get the port
Portmapper 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.
Server Enables you to define server queues specific to your needs. For most types of server queues, you can specify a minimum and
Queue 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 queue or specify only one thread, two threads are started to meet the minimum system
requirements.
If you specify a list queue and specify only one thread, two threads are started to meet the minimum system
requirements.
If you do not specify a list queue, one is not started.
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 maximum thread per
server queue.
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 .
12.4.15 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
2. Click the Database tab.
AR System Administration: Server Information form — Database tab

The information displayed on this tab varies depending on the relational database you have installed.
Database tab fields


3.
Database Displays the type of database that the AR System server is using.
Type
Database (UNIX only) Displays the directory path of the underlying database that the AR System server is using.
Home
Database Displays the name of the database created for AR System in the underlying database server.
Name
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 (Sybase, Oracle, Microsoft SQL Server, and DB2 databases only) Enables you to define the password that BMC Remedy AR
Password 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.conf configuration file, delete it from that file.
Database Displays the contents of the ardb configuration file used by the advanced BMC Remedy AR System feature that appends
Configuration clauses to the SQL statements that create tables and indexes. For more information about the ardb file, see ardb.cfg or
File ardb.conf.
Database Indicates whether the database in use is case sensitive. This field is read-only.
Case
Sensitive
Request ID (Microsoft SQL Server, Sybase, and DB2 databases only) Indicates whether AR System creates the Request ID field as a
Uses clustered index to boost performance. By default, this option is selected.
Clustered
Index
Store CLOB (Oracle databases only) Specifies how Oracle CLOBs are stored:
In-Row 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.
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.
12.4.16 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


Currency Types tab fields
Area Description
name
Choose Allowable currency types are types that are valid entries in a currency field. These currency types are visible in menus or lists in
Default BMC Remedy Developer Studio and in client screens. From the list in the left column, select a currency type, and click Add.
Allowable Your selection is added to the table on the right, which shows the three-character currency type and the default decimal
Types 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 submitted that includes a
Default currency value, the server converts that value to a functional currency type and stores it. You must include at least one
Functional functional currency type. You can specify an unlimited number of functional currency types; however, adding more than five
Types 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.
12.4.17 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
Server Information.
2. Click the Licenses tab.
AR System Administration: Server Information form--Licenses tab

Licenses tab fields

Field Description
Name
Server Displays the license type of the server.

License
Type
Fixed Displays the total number of Fixed licenses on the server.

Write
Licenses
Floating Displays the total number of Floating licenses on the server.

Write
Licenses
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
Allowed many forms as you want.
on Server
AR System Displays the BMC Remedy AR System identifier code attached to the server license.
Server ID
Submitter Defines the conditions under which submitters can modify the requests they initially submit (that is, where their names are in
Mode 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.
12.4.18 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
Server Information.
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
Authentication 390695. Entering no value or 0 disables authentication using an AREA service, and the BMC Remedy AR
Server RPC System server accesses the operating system for authentication purposes.
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 RPC Sets the time limit (in seconds) within which the plug-in server must respond to the BMC Remedy AR
Authentication System server when making external authentication (AREA) calls before an error is returned. If this is set
Server to 0, BMC Remedy AR System server uses the default of 40 seconds.
Timeout
(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 Defines how BMC Remedy AR System validates a user who has no record in the User form. When a user
Unregistered logs in to BMC Remedy AR System, the server tries to validate the user against registered users (users who
Users 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
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. See Configuring 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 Defines how BMC Remedy AR System authenticates a user whose User form record has no password.
Blank When a user logs in, BMC Remedy AR System searches its own database for that user. If the user has a
Password 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 Specifies the order in which BMC Remedy AR System tries to authenticate users when they log on:
Chaining Default — Disables authentication chaining.
Mode 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.
Group LDAP Area The name of the LDAP group to map to the BMC Remedy AR System group in the same row of the Group
Mapping name Mapping table.
AR Group The name of the BMC Remedy AR System group to map to the LDAP group in the same row of the Group
Name Mapping table.
Ignore Excess Enables BMC Remedy AR System to authenticate a user when any single LDAP group to which the user
Groups belongs matches a BMC Remedy AR System group.
12.4.19 Setting performance and security options

Use the Advanced tab to create settings for performance and security:
Server Information.
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 Specifies the base URL for the mid tier and is used by clients such as Flashboards. The URL looks like this:
Path 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 For forms that contain hierarchical data, such as manager and employee relationships, specifies the
Depth for maximum number of levels in the hierarchy that a recursive query retrieves. By default, the maximum is 25.
Hierarchical Enter any integer greater than 0. See ARGetListEntryWithMultiSchemaFields.
Query
Maximum Specifies the maximum number of temporary tables that can exist on an AR System server for a single
Vendor vendor form. The ARGetListEntryWithMultiSchemaFields function stores data from vendor data
Temp Tables 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.
Email Suppress Suppresses the server domain in the URL. The option is clear by default.
Server
Domain in
URL
Maximum Specifies the maximum line length that can be in an email. The default is 1024. If a single line of the message
Line Length is over this length, a return is automatically inserted. Limits the line length of email messages passed
in Email through the mail server to protect users from excessively long lines.
Email Specifies the base URL that appears in email notifications. If this field is left blank, the Default Web Path is
Notification used. (The Email Notifications Web Path field is available because the Default Web Path is specified for other
Web Path 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 Active Link Specifies the only directory that the Run Process active link action can run from, for example, C:\arsys. If no
Run Process directory is specified, active link processes can run from any directory.
Directory
Active Link Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no path is specified,
Run Process administrators can specify any shell.
Shell (UNIX
servers only)
Allow Enables the administrator to use the arcache and arreload utilities. See arcache.exe or arcache and
arcache and arreload.exe or arreload. The option is selected by default.
arreload
Transaction Maximum Specifies the maximum number of client managed transactions (CMT) which are allowed on the system.
Control Connections Valid values are 0 to 100. When set to 0, CMT is disabled on that system. The default is 10.
Transaction Specifies the maximum allowed time interval (in seconds) between client managed transaction API calls.
Timeout When a client managed transaction starts, if the consecutive API call is not made within the specified time
(seconds) 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.
Localized Localize Enables the administrator to enable or disable localization of the server.
Error Server Selected — The server is localized and is enabled for such tasks as searching entries in localized
Messages 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.

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.
Catalog Displays the name of the form the server uses to resolve error messages when Localize Server is selected.
Form Name For more information about the BMC Remedy AR System Message Catalog form, see Localizing BMC
Remedy AR System applications.
Filters Maximum Specifies the number of filters that can be performed in an operation. The default and recommended
Filters for an number is 10000. Increase this number at your own risk only if you reach a limit in your system and you
Operation have verified that your workflow is valid.
Maximum Specifies the maximum number of nested filters and filter guides that execute to prevent recursive actions
Stack of on the server. The default and recommended number is 25. Increase this number at your own risk only if
Filters you reach a limit in your system and you have verified that your workflow is valid.
Server Group Server If the server belongs to a server group, specifies the name of the group. All servers in the server group share
Group this setting.
Names
Check Specifies how often the server communicates with other servers in the group. Each server can register its
Interval 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 Preference Specifies where user preferences are read from. The options are
Server Server User Defined — Users can select whether to use a preference server, and this server might or might
Option 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 Preload If the number of preload threads is not zero, specifies whether the threads are used only at server startup or
Tables Tables At for all cache reloads from the database. See Setting the Preload Tables Configuration option. Values are
Configuration Init Only Yes — If preload threads are configured, use them only at server startup.
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 Specifies the number of preload threads used when information is loaded from the database into the server
Preload cache. The maximum value is 30 or twice the number of preload segments, whichever is lower. The server
Threads

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 Specifies the total number of preload segments handled by the preload threads. Vary this setting to balance
Preload the load between preload threads and to optimize cache load time. A good initial setting for this option is
Segments 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.
12.4.20 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
Server Information.
2. Click the Connection Settings tab.
AR System Administration: Server Information form — Connection Settings tab

3. Edit the options on the tab as needed:

3.
Connection Settings tab fields
Tab Field name Description
name
Application Specifies the password that the Email Engine and Flashboards server use to access the AR System server.
Service Asterisks in the field indicate that a password is defined. If you change this password on the AR System server,
Password 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 the EmailDaemon.properties file (see
EmailDaemon.properties file). To change the Application Service Password for the Flashboards server, update
the server.conf file (see Resetting the Application Service password).
Mid-Tier Specifies the password used by the mid tier to access the AR System server. If you change this password on the
Administrator AR System server, you must also change it in the Mid Tier Configuration Tool, which updates the
Password config.properties file (see Configuring the Change Password page). In the Mid Tier Configuration Tool, this
password is called the Admin Password.
Proxy server Obsolete as of release 7.5.00.

settings for
Java VM
Plug-In Local Sets a password for other BMC Remedy AR System servers to use when they connect to this server's plug-in
Server Password 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 Specifies the number of seconds in which the plug-in server must respond to the AR System server before an
Default error is returned.
Timeout
Plugin Specifies the default port for the plug-in server.

Default Port
Server Name Specifies the name of the AR System server associated with the target plug-in server.
Note
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 Specifies the password that a DSO server uses to access this AR System server. If you change DSO Server
Server Password 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.
DSO Local Specifies a dedicated (private) RPC program number that a DSO server uses for all communication with the AR
RPC Program System server. If you leave this field blank, the fast and list queues process all distributed operations.
Number

Target Specifies RPC program numbers, TCP/IP ports, and DSO passwords that a DSO server uses when accessing
connection remote AR System servers. See Configuring BMC Remedy Distributed Server Option.
settings
tables
Remote Local Specifies the password that another AR System server uses to access this server through workflow. If you
Workflow Password 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
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.
12.4.21 Setting administrative options

Use the Configuration tab to set administrative options.
To set configuration options
Server Information.
AR System Administration: Server Information form — Configuration tab


2.
Configuration tab fields

Users Prompted Specifies whether users are prompted for their log on credentials.
For Login 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 Limits how many database entries are returned from a search. For example, setting the maximum entries to 50 would
Returned by return a maximum of 50 entries, even if more entries satisfied the search qualification. BMC Remedy AR System warns
GetList 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 For server-side table fields, determines the number of entries (or size of the chunk) that the server retrieves at one
Chunk Size 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, 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 Identifies the sender of email notifications. The default sender for email notifications is ARSystem. To specify another
From 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
Version BMC Remedy AR System versions are as follows:
API 20 and AR System 8.1.00
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 Specifies the path to a home page form to be used system-wide as the default home page for this server when a user
Form 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 Specifies the maximum number of consecutive bad password attempts a user is allowed. If you enter 3, the user has 3
Password Attempts 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 Specifies whether to allocate Next-IDs in blocks rather than one at a time. Allocating in blocks increases performance
Block Size 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.
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 Defines whether guest users receive a restricted read license when they log on to BMC Remedy AR System. If this
Restricted Read option is not selected, guest users receive a read license.
Allow Unqualified Defines whether the server accepts unqualified searches (searches for which no search criteria are specified). If the
Searches 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 Enables only administrators and sub-administrators to access BMC Remedy AR System. Users who are not
Mode 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
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 Turns on a cache mode optimized for application development. If the check box is not selected (the default), the
Cache Mode 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.
See Configuring server groups.
Server Group Indicates whether the server is a member of a server group. By default, this option is not selected.
Member
Disable Admin Disables certain operations performed only by administrators and sub-administrators, which enable you to control
Operations 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 configured in the BMC
Remedy AR System Server Group Operation Ranking form to make sure 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 configured in the BMC Remedy AR System Server Group Operation Ranking form to
make sure 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 Group field (ID 112) and
Assign Groups 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 When selected, restricts server access to Unicode-safe clients. This option applies to all non-Unicode clients. This
Unicode Clients 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 Determines whether the AR System server records the relationships between workflow objects. If the check box is
Relationships 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
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 Specifies whether system messages appear in the prompt bar or a pop-up box. The options are:
For 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 appear in a pop-up box.
Recache Delay The number of seconds that the recache is delayed.
Required Field Specifies the character to add to the label of a field whose entry mode is Required.
Identifier 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 This option can be set to restrict the number of form display properties the server loads into memory at startup. The
Caching 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 By default, this option is set to Diabled.
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
Changed Fields only those fields whose values have changed during a transaction are audited.
12.4.22 Defining queues and configuring threads
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
Server Information.
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:
Fast 390620
List 390635
Escalation 390603
Alert 390601
Full Text Indexer 390602
Private An RPC program number in the following ranges:

390621-390634
390636-390669
390680-390694
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.
Note
To improve the performance of the full text search (FTS) indexer, set the value of Max Threads for
the FTS indexer queue between 3 and 5.
7. Select the Yes check box to create a debug queue to work with the workflow debugger.
See Configuring the server for debugging workflow.
8. Click OK to close the form.
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.
12.4.23 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:
Use Description
case
Use 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
case the production server. The database might contain references to the production server, which might not be applicable to the staging
1 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 new BMC Remedy
case AR System environment (this is called an accelerated installation). In this case, you need to change only the form data.
2
Use The Server name is changing due to a policy or host name change. In this case, you must change the Registry (on Windows), the
case configuration files, and the form data.
3
Use 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),
case the configuration files, and the form data.
4
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)
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.
pluginsvr_config.xml
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>
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
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 newserver
name, and save the record.
Product Form Field name Field ID
BMC Remedy AR System Searches Preference Server 51004

AR System
BMC Remedy AR System User Preference Server Login List 20100

AR System
BMC Remedy Report Server 2000018

AR System
BMC Atrium BMC.CORE.CONFIG:BMC_FederatedDataInterface ARServerName 530003200

CMDB
Atrium Impact AIS:GlobalPreferences charAISCellHost 530046754

Simulator
Atrium Impact AIS:GlobalPreferences iAISCellPort 530046756

Simulator
BMC Remedy AR Login Info Server 301286600

IT Service
Management
BMC Remedy AST:ComplianceARBased_Advanced AR Server Name 303000501

IT Service
Management

Product Form Field name Field ID
BMC Remedy SYS:Escalation Record Server 230000011

IT Service
Management
BMC Remedy SYS:Attachments (If the out-of-box data for Survey is modified by replacing the URL 1000002261
IT Service <arserver> or <midtierserver> placeholders with the host names, only then change
Management these values to the correct server host name.)
BMC Service SRM:AppInstanceBridge AppInstanceServer 301368400

Request
Management
BMC Service SRM:AppInstanceBridge SRServer 301368500

Request
Management
BMC Service SLM:Config Preferences MidTier

Level (enter new URL)
Management
Service SYS:Integration Management MidTier Port

Management
Process Model
Service SYS:Integration Management MidTier Host

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

Limitations to using the Maintenance Tool to replace server references in database forms include the following:
Command line execution only is supported.

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

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 midTierInstallationFolder
/cachetemp folder (if it exists).
3. Delete the viewStats.dat and viewStats.dat.bak files if they exist under midTierInstallationFolder
/WEB-INF/classes folder.
4. 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.
5. Start the JVM mid tier.
6. Delete the browser's temporary internet files.
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.
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+Tzdb9Ag3SdrbBgfgQ
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/Defaul
.
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.
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.

1.
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
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.
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).
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. In the Server field, enter the oldServerName, and perform a search.

c. Replace the oldServerName with the newServerName.
5.
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:
1.
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.

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.
12.4.24 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.
The following sections are provided:
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
2. Click the Attachment Security tab as shown in the following figure:
AR System Administration: Server Information form — Attachment Security tab
3. Enter the attachment options that you need, and click Apply.
The following table describes the available options:
Field name Description
Attachment
criteria 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 Attachment extensions that are allowed or not allowed, based on the Attachment criteria selected.
separated list
of limit
extensions
Attachment The list of Form names (field ID) for which attachment limitations do not apply—for example, Data Visualization Module(3450298).
exception list
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 Name of the custom validation plug-in that you developed for verifying attachments
validation
The custom validation can perform any function per your requirements. You can develop the plug-in for performing functions like
plugin name
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:
Parameter Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 5 Scenario 6
Attachment criteria Include all Allow attachment Allow Allow Disallow Disallow
attachments with the attachment attachments attachments attachments
following with the with the with the following with the following
extensions following following extensions extensions
extensions extensions
Comma separated doc doc doc doc

list of limit extensions xls xls xls xls

Parameter Scenario 1 Scenario 2 Scenario 3 Scenario 4 Scenario 5 Scenario 6
jpg jpg jpg jpg exe exe

gif gif gif gif dll dll
db db
Attachment exception - Data - - - -

list Visualization
Module(41006),
Report
(2000012)
Attached File example.dll, example.jar example.doc, example.exe, example.doc, example.exe,

examples example.gif (JAR File field example.jpg example.db example.txt example.dll
on Data
Visualization
Module form)
Status File is attached. File is attached. File is attached. File is not File is attached. File is not
All attachment The JAR File field Its extension is attached. Its extension is attached.
options ID on the list of Its extension is not on the list of Its extension is on
are permitted. is added to the permitted not disallowed the list of
attachment extensions. on the list of extensions. disallowed
exception list. permitted extensions.
extensions.
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.
2. Click the Attachment Security tab, shown in the following figure
AR System Administration: Server Information form — Attachment Security tab
3. Enter the display options that you need, and click Apply.

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 Lists the attachment extensions that you want to allow or not, based on Display criteria
of display extensions
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.
12.4.25 Setting server statistics options

Before Service Pack 1, AR System server enabled you to gather performance statistics on the server. With Service
Pack 1, you can also gather statistics about the longest running SQL and API calls. Finding out which calls are
causing delays can help you troubleshoot performance issues.
To gather statistics on 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 When selected, displays API and SQL events in the console when an automatic save is triggered (by the time specified in the Auto
Console Save and Purge Interval (min) field) and when you click one of the Save buttons:
Display

Field Description
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).
Number of Defines the maximum number of completed longest operations that can be saved in memory. The number applies to both API and
Saved SQL lists of operations.
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 Defines the interval (in minutes) for when the longest operations saved in memory are flushed to the corresponding forms in the
Purge Interval database and then purged
(min)
The default is 0 (no interval), and no automatic save and purge is performed. If you change the interval, the new interval is used if it
is less than the time remaining on the old interval. Otherwise, the new interval is used after the current interval expires.
Minimum Sets the minimum duration of the longest API and SQL events saved in the memory buffer in milliseconds. Any event shorter than
Elapsed Time this value is discarded.
(mSec)
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 5000 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. The 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 in memory are cleared.
3. To view the statistics:
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.
Parameters (API only) Additional details about the API call (for example, the form name on entry-related calls)
SQL (SQL only) First 1000 characters of the SQL command issued to the database.
Command
Extended If the API parameters or SQL command exceed 1000 characters, the entire string is contained in the field.
Data
Elapsed Time Time (in milliseconds) required to complete the event. For SQL events, this time represents the statement execution only. It does not
(mSec) include any subsequent record retrieval time.
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 Mode Origin of the event recording:
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 (API only) Time (in milliseconds) in the thread queue before processing started
(mSec)
Data (SQL only) Reserved for future use

Retrieval
(mSec)
Create Date Date and time the entry was added to the form (not the event time)
12.5 Configuring server groups

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

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 Remedy Flashboards
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.
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:
12.5.1 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

Setting the check interval on the Advanced tab
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.
12.5.2 Setting failover rankings for servers and operations

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

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.
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.
4. Modify entries as required to construct a fail-over hierarchy for ownership of operations.
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.
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.
12.5.3 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

type
Database Reduces server activity when object definition changes are communicated Server definition changes – such as changes to
posting between servers and reduces the number of cache reloads when a series of forms, active links, filters, and escalations – and
changes is made. A delay occurs before other members of the server group pick user group changes.
up the changes.
Signaling

Notification Description By default, handles these changes

type
Other servers are notified of changes immediately. No delay occurs in All other changes, such as Alert registration and
resynchronization or updating definitions. DSO activity.
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.
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.
12.5.4 Configuring full text search for a server group
Note
Starting from BMC Remedy AR System 8.1 Service Pack 1, the following new terms are used for FTS
plug-ins:
FTS Writer is called FTS Indexer

FTS Reader is called FTS Searcher

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

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.

Starting with Service Pack 1, 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.
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.
Configuring FTS for a server group

If you use FTS in a server group, only one server in the group can index data at a time.
Starting with Service Pack 1, 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.
2.
2. In a browser, open the BMC Remedy AR System Administration Console, and click System > General > FTS
Configuration.
3. Complete the form as per FTS Configuration form in the AR System Administration Console.
12.5.5 Configuring DSO for a server group

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

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

2.
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
12.5.6 Configuring the Email Engine for a server group

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.
12.5.7 Configuring flashboards for server groups

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.

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.
12.5.8 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

If BMC Remedy Developer Studio used either of these server names to log in, that server is recognized as the
current server in workflow.
12.5.9 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.
12.5.10 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.

12.5.11 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.
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.
12.5.12 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.
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
12.6 BMC Remedy AR System cache management

The following topics provide detailed information about BMC Remedy AR System cache management:
12.6.1 Configuring the server cache

The following topics provide information about configuring the server cache:
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
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.
To set the cache mode
2. In the AR System Administration: Server Information form, click the Configuration tab.
3.
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.
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.
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.
Note
For more information about 32-bit server issues, see Default memory limits for 32-bit
processes.
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
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 .

Option Description
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.
12.6.2 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

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
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:
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.
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.
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.
12.6.3 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 BMC Remedy AR
System server.
3.
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.
12.6.4 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

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).
Actions that trigger cache or re-cache events
Note
For details about mid-tier caching, see Actions that affect mid tier caching.
Actions that trigger cache or re-cache events
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
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 every field) 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
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.
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.
12.6.5 Mid Tier cache configuration

The following topics provide information about configuring the BMC Remedy Mid Tier cache:
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.
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.
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
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:


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

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?

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.
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
Starting with BMC Remedy AR System Service Pack 1, 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.
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 Checking system requirements and supported configurations.
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.
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.

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

12.6.6 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 load Admin copy 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
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.
12.7 BMC Remedy Mid Tier configuration

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:

12.7.1 Configuring the mid tier through a firewall

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:
Note
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 Configuring AR
System servers.
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.
12.7.2 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
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.

1.
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
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.
12.7.3 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 > BMCRemedy 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:
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.

12.7.4 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
To verify that the new configuration password is in effect, log out of the Mid Tier Configuration Tool and log on
again.
12.7.5 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:
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 The version of the BMC Remedy Mid Tier that is installed.
Version
Installation The directory path being used for your BMC Remedy Mid Tier installation.
Directory
Web Server The product name of the web server being used with this installation of the BMC Remedy Mid Tier (for example, Microsoft IIS) and the
Information product name of the Java servlet engine being used with this installation of BMC Remedy Mid Tier (for example, Apache Tomcat).
Note
In some web configurations, only the servlet engine details are shown.
Operating The operating system used on your computer (for example, Oracle Solaris 10 or Windows 2003 Server).
System
Name
Java The version of the Java Software Development Kit (SDK) that is installed on your computer (for example, 1.5.0).
Version
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 Settings page. See
Setting user preferences.
Data Visualization The AR System server that contains the data visualization module.
Module Server(s)
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 The interval (in seconds) at which information in the cache is updated. The default value is 86400 seconds. You can change
Check Interval this value on the Cache Settings page.
(Seconds)
Session Timeout The number of minutes after which a session expires. When the system has exceeded this amount without any activity, the
(Minutes) user must log on again. The default value is 90 minutes. You can change this value on the General Settings page.

12.7.6 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
General Settings parameters

The following table lists the parameters on the General Settings page.
Setting Description
Session Timeout The number of minutes after which the current session will expire. When the system has exceeded this amount without any
(Minutes)* 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.
Note
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 The number of seconds before BMC Remedy Mid Tier releases an AR System user license associated with a user if that user
Timeout ([30 - does not log out of BMC Remedy Mid Tier properly. To log out properly, the user must close the last browser window
300] Seconds)* 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.
Note
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.
Data Visualization The name of the BMC Remedy AR System server designated as a data visualization module server. You can specify more than
Module Servers 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.
Note
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 Server The server that contains the home page that you want to open in the browser when the user logs on. The home 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 Settings page. 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 The server that BMC Remedy Mid Tier uses to authenticate the user. If an authentication server is specified, BMC Remedy Mid
Server 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 One of the settings evaluated when the system is progressing through the view selection algorithm; it indicates whether you
Standard/Windows 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:
Views
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.
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.
12.7.7 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

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 list, click Clear All.
AR Server 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.
Name BMC Remedy Mid Tier must be able to resolve this server name to an IP address. BMC Remedy 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.
Domain The domain name portion of the fully qualified server name for the AR System server.
Name
Use Short Specifies whether the BMC Remedy Mid Tier always uses the short name of the AR System server. For example, serverName. This value
Name is set by the Use Short Name check box when adding or editing an AR System server.
AR Server The specified password for an AR System account with administrator privileges. Set the BMC Remedy Mid Tier Administration Password
Admin under the Connection Settings tab in the AR System Administration: Server Information form. (If a password has been entered for a
Password server, asterisks appear in this column instead of the actual password characters.) Version 7.0 and later AR System servers require a
password.
AR Server The port number you previously configured to access the AR System server. If you have not configured a port number, this field is
TPC Port blank.
Number
AR Server The Remote Procedure Call (RPC) protocol number that the server will use. This number can be used for connecting to a private
RPC 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
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

4.
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.
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.
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. 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 Save AR Server.
12.7.8 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
The following sections provide detailed information about configuring the Cache Settings page:
Cache Settings parameters

The following table lists the parameters for the Cache Settings page.
Cache settings
Setting Description
Definition The interval (in seconds) at which cache information is automatically updated. The default value is 86400 seconds. To change the
Change Check interval, enter the new number of seconds in this field. For Development cache mode, the value must be 0. For Production cache
Interval mode, the value must be greater than 0. If you do not want the cache to be updated, clear the Perform Check check box.
(Seconds)
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.
Perform Indicates whether you want the cache to be updated automatically. You can still update the cache manually by clicking Flush
Check 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.
Update The interval (in seconds) at which the server updates the Flashboards cache information. Set this value to 0 to disable caching. The
Flashboard default value is 0.
Definition
Interval
(Seconds)
Resource The time limit (in seconds) for which resources (such as images, .css files, and JavaScript files) can be used. The default value is
Check Interval 86400 seconds. If a user closes a form and opens it again within the specified expiry time, the image is cached and is not
(Seconds) downloaded again. This helps increase the performance of BMC Remedy Mid Tier.
Enable Cache Specifies whether forms cached in memory are written to files for faster retrieval. If the check box is:
Persistence
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.
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 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
Configuration WEB-INF/classes subdirectory. For more information, see Editing 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. 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:
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.
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.
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.
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
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. The default value is 0.
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. The default value is 0.
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).
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.

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

You can specify the number of prefetch threads in the config.properties file by editing the
arsystem.max_number_of_pretch_threads flag.
User and group permissions for prefetching

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.

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.

<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.
12.7.9 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.
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 How you are deploying your BOXI or Crystal Reports report engine:
Engine Deployment
(Mid Tier No Report Engine — Select this if you are not using Crystal reports.
Configuration Tool BOXI/Crystal Report Server on this machine — This selection appears only when BMC Remedy Mid Tier is installed on
only) 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.
Reporting Working The working directory where BMC Remedy Mid Tier deposits report definitions to be picked up by the relevant report engine
Directory (Web, BMC Remedy 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 server's root document directory, configure your web
server with a virtual directory to point to this directory.
BOXI/Crystal The URL prefix, including the host name and port number, if any, used to access the mid tier or AR Web ReportViewer on the
Reports Server BOXI or Crystal Reports server. For example, if the URL for BMC Remedy Mid Tier on the BOXI or Crystal Reports server
Location (Mid Tier machine is http://<hostName>:8080/arsys/, enter http://<hostName>:8080
Configuration Tool
If the context path is not arsys, then include the context path: http://<hostName>/<contextPath> or
only)
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.
CMS Machine The Crystal reports product you are using:

Connection Details
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.

12.7.10 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
For more information, see Using Crystal reports with BMC Remedy AR System.
12.7.11 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:
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 Specifies whether to enable the rebalancing of connection loads between BMC Remedy Mid Tier group and the server group. If the
Lifespan 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 balancing on the
Lifespan connection, keep this parameter at its default value of 0. Whether the Connection Lifespan or Connection Timeout setting is met first
(Minutes) 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 The maximum number of proxy connections that a connection pool can contain per server. If the number of existing connections for
Connections the requested server does not exceed this value, a connection is allocated to that server. The default value is 80.
per 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.
Connection The amount of time (in minutes) that the pooled connections exceeding the Idle Connections per Server can be idle before being
Timeout terminated. This time limit makes sure that active pools routinely clean up their excess idle connections. To prevent any idle pooled
(Minutes) 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 The maximum number of idle connections per server that are not subject to the Connection Timeout. These connections are always
Connections 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
per Server 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.

Setting Description
Created The datetime stamp when the pool was created.
12.7.12 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
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.

Home b. BMC Software Confidential
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.
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

1.
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.
12.7.13 Cookies used by BMC Remedy Mid Tier

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.
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
G IP-Restriction GUID — A persistent cookie used to track the user so that the same user Persists for a day
cannot log on from multiple computers
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 Deleted when the session times out or
the encrypted data of the user session the browser is closed
P Pop-up Blocker — Indicates whether a pop-up blocker is to be shown or not Deleted when the session times out or
T Session Tracker — Used to track the total number of open windows Deleted when the session times out or
w Window — Used to display the name of the window Deleted when the session times out or
XXXXXXXXX the browser is closed
FC Flash Cookie — Used to hold the cookie data in a Flash or shared object Deleted when the session times out or
GF Global Fields — Used to track the values of global fields when the fields are used across Deleted when the session times out or
forms the browser is closed
LT License Timeout — Used to track when the license times out Deleted when the session times out or
ST Session Timeout — Used to track when the active session times out Deleted when the session times out or

Related topic
Configuring the mid tier through a firewall
12.8 Configuring a hardware load balancer with BMC Remedy

AR System
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.
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:
12.8.1 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.
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.
12.8.2 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.
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.
12.8.3 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 Configuring AR
System servers.
12.8.4 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
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
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.
12.8.5 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.
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.
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.
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.
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 .
without setting a "sticky" bit 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 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
12.8.6 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
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.s
"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/configuratio
Note
Website addresses change frequently. If you have difficulty finding these documents, go to
http://www.cisco.com and navigate to the Documentation pages.

12.8.7 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

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.
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
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.
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
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 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 without setting a sticky bit
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
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 (the following figure). 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 (the following figure).
Limiting idle session connections

In BMC Remedy AR System versions earlier than 7.6.04 (the following figure), 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.
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

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 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.
12.8.8 Load balancing with Email Engine

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. Ensure that all of the email engines refer to the same AR System server.
12.9 Configuring a Unicode server

The following topics provide information about Unicode configuration:
12.9.1 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

Use the --unicode flag when you invoke any of the following programs:
arcache
archgid
archgsel
ardisabled
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.
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.
12.9.2 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
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.
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).
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 1 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 Chinese and Korean encodings use 2 bytes for each character; the same characters in UTF-8 occupy 3 bytes. The actual
Korean 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.
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:
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.
12.9.3 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"?>
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
12.9.4 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.
12.10 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:
12.10.1 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)
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 Checking system requirements and supported configurations.
12.10.2 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

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:
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
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
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.
12.10.3 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.
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 Distributed Server Option (DSO)
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.
12.10.4 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 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.

12.10.5 SNMP configuration files
Note
For information about configuring BMC Remedy SNMP Agent during installation, see the Installing and
Upgrading sections.
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) (UNIX) /usr/ar/ARSystemName

arsnmpd.conf /conf
(Windows) (Windows) Stores engine ID, number of BMC Remedy SNMP Agent reboots, and SNMP v3 user
snmpd.conf ARSystemServerInstallDir\conf account information.
(UNIX) snmpd.conf (UNIX) /usr/ar/ARSystemName

/conf
(Windows) (Windows) Enables BMC Remedy SNMP Agent to monitor BMC Remedy AR System and to be
armonitor.cfg ARSystemServerInstallDir\conf started by armonitor.
(UNIX) (UNIX) /etc/arsystem/serverName

armonitor.conf
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.

12.10.6 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)

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

12.10.8 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.
12.10.9 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):
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).
12.10.10 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.
12.10.11 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.
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
Enable SNMP Agent in

armonitor.conf Click Yes to enable the SNMP Agent.
Click No to disable the SNMP Agent.
System Location Enter the system location information.

Information
Administrator Contact Enter the administrator contact information.

Information
SNMP Agent Port Number Enter the SNMP Agent port number.
Authentication Mode for

SNMP Requests 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.
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.
12.11 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 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:
12.11.1 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.
12.11.2 Enabling DSO on an AR System server
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
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.
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
12.11.3 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.
12.11.4 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 Remedy AR System
server.
2. Click the Ports and Queues tab.
3.
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.
12.11.5 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.
12.11.6 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. 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.
The corresponding entry in the BMC Remedy AR System server configuration file is 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.
The corresponding entry in the BMC Remedy AR System server configuration file is 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.
12.11.7 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.
12.11.8 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 Remedy AR System
server.
2.

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.
12.11.9 DSO for load balancing

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
Related topics
Enabling DSO on an AR System server
12.11.10 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 Specifies the BMC Remedy AR System server for a DSO server to support when that BMC Remedy AR System server is different from
Server the one installed with the DSO server.
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 Specifies the interval at which the DSO server queries the distributed pending queue for pending distributed items.
Interval
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 Specifies the interval (in seconds) at which the DSO server checks the distributed pending queue for pending distributed items.
Polling
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
Interval
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 Specifies the timeout (in seconds) that the DSO server applies during communication with the BMC Remedy AR System server.
Timeout
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
Normal
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 Specifies the number of seconds between occurrences of these operations:

Check
Interval 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 Specifies how the DSO server responds to errors.

Option
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 Specifies the maximum number of records in the Distributed Pending form that DSO reads in a single database query.
Pending
Valid values are
Records
Per Query
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
Mark Specifies whether to set the status of items in the DSO distributed pending queue to Retry after an attempt to perform the associated
Pending operation fails.
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 When selected, disables the DSO server that was installed on the same host as the BMC Remedy AR System server. Use this when
Mode 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.
Specifies whether to log failed pending distributed operations to the Distributed Pending Errors form.

Log Errors The corresponding BMC Remedy AR System server configuration file entry is Log-DSO-Errors-To-Form. See Logging failed pending
to DSO items.
Pending
Errors Form
Suppress Specifies whether to log BMC Remedy AR System server error 302 (entry does not exist in database) in the arerror.log file when
No Such performing distributed delete operations.
Entry Error
for When this option is selected, ARERR 302 is never logged during distributed deletes.
Distributed (Default) When this option is not selected, ARERR 302 is always logged during distributed deletes except when the Error Retry
Delete 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.
12.12 Configuring full text search

This section contains information about configuring FTS in BMC Remedy AR System.
12.12.1 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
Disable Full Controls whether the server uses the full text search engine for searching. When disabled, the server uses the search capability of
Text the underlying database. This setting does not apply to multi-form searching.
Searching

FTS The location in the file system where search engine index files are stored.
Collection
Directory
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 The location in the file system where search engine configuration files are stored.
Configuration
Directory
Full Text The maximum number of search results returned from the search engine. The default value is 10,000. To limit the number of search
Search results (because of constraints on the computer where the search engine is running), reduce the threshold. If you change this
Threshold option, you must restart the AR System server for the change to take effect.
Indexing Defines the number of minutes the server waits between periodic attempts to index entries that failed to index for an unexpected
Failure reason in a prior attempt. The default value is 60 minutes.
Recovery
Interval
Temporary During the processing of search results, the server creates a temporary table if the number of FTS matches reaches this value. If the
Table number of FTS matches is less than this value, the server uses the SQL IN operator for a query on an existing table. The default value
Threshold is 200.
Complex During the processing of search results, the server combines results from subqueries to arrive at the final result set. If the number of
Search rows created during processing exceeds this value, the server returns an error message indicating that the search is too complex.
Threshold The default value is 1,000,000.
Indexer Number of seconds before a signal is sent to the server that owns the full text indexing operation (if no signal is pending). When a
Server Group server is not the owner of the full text indexing operation and generates indexing work, that server signals the server that is the
Signal Delay 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 Defines how the server modifies qualifications received from the client. The choices are
Options
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 Controls whether the server processes pending indexing tasks. When disabled, indexing tasks are still recorded for processing at a
Text Indexer later time when indexing is enabled.
Use FTS in Controls whether the server uses full text searches when executing queries during workflow that have full text indexed fields in the
Workflow qualification. By default, this option is selected. If you clear this check box, the server uses the search capability of the database.
Ignore Words Defines which words are ignored during indexing.

List
Title Field Defines the relevancy weight for the Title field of a form in a multiple-form search. (See Configuring forms for multiple-form FTS.) A
Weight 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.
Environment Defines the relevancy weight for the Environment field of a form in a multiple-form search. (See Configuring forms for
Field Weight 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 Defines the relevancy weight for the Keywords field of a form in a multiple-form search. (See Configuring forms for multiple-form
Field Weight 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.
12.12.2 High-availability architecture for FTS

Before Service Pack 1, BMC Remedy Full Text Search (FTS) required that one server in a server group act as the
FTS server. With version 8.1.00 Service Pack 1, 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.
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
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.
A slight load on the database can occur if you are performing re-indexing and your database server is running on
low memory. Avoid performing a full re-index at the same time on two FTS index servers running in your
production environment. Additionally, 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
Configuring full text search for a server group
Upgrading with FTS installed
12.12.3 FTS Configuration form in the AR System Administration Console
Note
Starting from BMC Remedy AR System 8.1 Service Pack 1, the following new terms are used for FTS
plug-ins:
FTS Writer is called FTS Indexer

FTS Reader is called FTS Searcher
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 8.1.00

If you select the Upgrade option to upgrade an existing version of FTS to version 8.1.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

AR System Administration FTS Configuration form fields
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.
Server Select any one of the options and perform the following:
Configuration
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 Enter the JVM heap size (in megabytes) for secondary server.
Memory2
FTS Enter the full path of the FTS Collection directory.

Collection
Directory
FTS Enter the full path of the FTS Configuration directory.

Configuration
Directory
Notes

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 .
Applicable for Service Pack 1
12.12.4 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: Server
Information form.
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.
12.12.5 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.
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.
12.12.6 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.
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.
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.

12.12.7 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.
12.12.8 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
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.
12.12.9 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_ 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
<locale>.txt each locale or language. You can update this file through the Ignore Words List field on the AR System Administration: Server
Information form.
rootwords_ Lists words and their corresponding root word. You create a file for each locale or language. By default, FTS uses stemmers
<locale>.txt 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_ Contains synonyms used to perform thesaurus expansion during indexing. You create a file for each locale or language. If the
<locale>.txt 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
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.
12.12.10 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 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>
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>

12.12.11 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.
12.12.12 Upgrading with FTS installed

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.
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.
12.13 Configuring reporting

The following topics provide information about how to configure reports:
12.13.1 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.
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.
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.
12.13.2 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

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

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:

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

Keyword Description
$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.
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
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=$ARSE
BOCurrentMidtierURL=$CRTXILOC$/arsys/$RPTLOC$?init=$CRTVWR$&User0=$USR$;ARServer=$ARS
BORemoteMidtierURL=$CRTXILOC$/arsys/$RPTLOC$?init=$CRTVWR$&User0=$USR$;ARServer=$ARSE
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 following information:
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
The following sections provide information about how to work with 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.
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.
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.
Monitoring reports by using flashboards

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:
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.
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

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

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. Run a web report from the Report Console.
2. In the report viewer, click Print Report.
3.
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 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:
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 More information
Window Report
Type
Target New Selecting New causes a new window to open for each report generated. If you select
Location Current, the active link uses the existing open window from where the active link is
initiated.
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

Name
Report Type The type of report The menu's data is read from the ReportType form on the AR System server being used for
the Open Window action.
Report Report Form (or Embedded)

Location
Report Name of the report as stored

Name in the Report form (not the file
name of the attachment)
Report Screen or File

Destination
Qualification A query string that determines If you want to use a string from a local field, use the EXTERNAL keyword, for example,
which entries from the form to EXTERNAL($QueryStringField$). If this string and the Entry IDs string are both left empty,
include in the report all entries of the form being reported on are included in the report.
If No Do Not Show Any Message

Requests
Match
4. Click Show Advanced, and complete the fields as described in the following table.
Advanced fields
Entry IDs A comma-separated list Only these entries are displayed in the report. If this string is filled and contains fewer than 256
of entry IDs from the entry IDs, it overrides the Qualification String. Otherwise, the Qualification String takes precedence.
form being reported on If both are left empty, all entries in the form are included in the report.

Query Yes or No Some report engines allow the Qualification String (or Entry IDs) to override a query that might be
Override stored as part of the report definition. This value specifies whether the report engine should do so.
Report Create — Used to If you select Crystal Report in the Report Type field, then Edit and Create are not valid options for
Operation create a new the Operation field.
report definition
file
Edit — Used to
edit an existing
report definition
file
Run — Used to
run a report
Character The character set to be Select Use Server to apply the same character set encoding used by the server.
Encoding used for the report
5. Save the active link.
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 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.
12.13.3 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 Checking system requirements and supported
configurations.
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
Important
In the BMC Remedy AR System installer, the AR Web ReportViewer is called the AR Crystal Web
Application.
The installer presents the AR Crystal Web Application option 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 Crystal Web Application installer selection installs the AR Web ReportViewer and BMC Remedy AR System
ODBC Driver
You can select:
Both Mid-Tier and AR Crystal Web Application — This installs the mid tier with the AR Web ReportViewer.
AR Crystal Web Application only — This installs the AR Web ReportViewer only.

Mid-Tier only — This installs the mid tier only. This selection is appropriate when you are installing the mid
tier on a different computer from the CMS.
When you select 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 8.0.00, the BMC Remedy AR System ODBC driver is named arapi80.dll or
arapi80_build xxx.dll.
If you select AR Crystal Web Application, the installer prompts you for further 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.

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:

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:
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. 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

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.
Enabling the Guest account

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

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.
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 BMC Remedy
AR System.
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.

4.
Create New Data Source dialog box

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

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.
12.13.4 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

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.

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

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:
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. 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
12.14 Configuring the BMC Remedy Approval Server

The following topics provide information about how to configure the BMC Remedy Approval Server:

12.14.1 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
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
12.14.2 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.
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
12.14.3 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

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.
Creating a process administrator

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. Open the Administrator tab, and click Create to open the AP:Process Administrator form.
Creating a process administrator

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.
12.14.4 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.
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
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.
12.14.5 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 2.
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)
#/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/ar
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=true

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
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 entry for the ARSYS.ARDBC.PREVIEW plugin:

<plugin>
<name>ARSYS.ARDBC.PREVIEW</name>
Software/ARSystem/approval/bin/arasj80_build001.jar</pathelement>
<classname>com.bmc.arsys.approval.main.ApprovalPlugin</classname>


Software/ARSystem/arserver/api/lib/arcmnapp80_build001.jar</pathelement>
Software/ARSystem/arserver/api/lib/arutil80_build001.jar</pathelement>
</plugin>
</plugins>
<maskingImplementation>com.bmc.arsys.approval.signal.SignalMaskForASJ
</maskingImplementation>
</pluginsvr_config>
b. Save and close the file.

5. Restart the BMC remedy AR System server for the changes to take effect.
12.14.6 Starting and stopping the Approval Server

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
2. To start the Approval Server, remove the comment markers from the files discussed in steps 1a and 1b.

12.15 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:
12.15.1 Configuring outgoing mailboxes

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

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.
Polling Interval — Select a polling interval for the Email Engine to check for 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.
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
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.
12.15.2 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
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.
Email Engine startup parameters
-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.

12.15.3 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.
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 Related

Functionality
com.bmc.arsys.emaildaemon.AdditionalMailHeaders Specifies additional email headers. Separate the Default value: Outgoing
additional email headers with commas. See Adding X-Loop-Detect
extra custom headers to outgoing SMTP emails.
com.bmc.arsys.emaildaemon.ARDATE Specifies the date and time format that the BMC Incoming
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 Incoming
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 Incoming
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 Outgoing

property in the Content-Type header of an outgoing True (
message. If you do not want the charset string to be Default)
present in the Content-Type header, set this property False
to False.
com.bmc.arsys.emaildaemon.ChunkSize Specifies the number of entries to return when the Default value: Outgoing
BMC Remedy Email Engine makes a call to the AR 100
System server.
Note: The
maximum
value is also
100.
com.bmc.arsys.emaildaemon.CommaValidAddressSeparator Specifies whether you can use a comma as a separator Incoming

when entering multiple addresses in the To and CC True ( and
fields. If user names in the mail server contain Default) Outgoing


Functionality
commas, set this property to false (usually needed only False

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
com.bmc.arsys.emaildaemon.Exchange-Wait-Time Specifies the amount of time in milliseconds for which Default value: Incoming
the BMC Remedy Email Engine waits before 1
processing the next incoming message, when there
are more messages residing on the Exchange Server.
com.bmc.arsys.emaildaemon.FetchUserGroupInfoOnDemand Specifies whether to fetch the user and group Incoming

information about demand as opposed to loading all True and
users and groups at startup. If there are many users or False ( Outgoing
groups, you might want to set this property to true to Default)
reduce the startup time for email.
com.bmc.arsys.emaildaemon.getReplyToWithFromAddress Determines whether the outgoing message header Outgoing

should contain the Reply To field and what its value True (
should be.getReplyToWithFromAddress is not used by Default)
default. If you want the email engine to use this False
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 Default value: Incoming
email engine receives before the connection is closed 100
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


Functionality
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). Default value: Incoming
The Receiver module writes messages to the queue, 100
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 stored in the Default value: Incoming
cache, which is used to improve performance. If the 20
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.
com.bmc.arsys.emaildaemon.Mailboxes If you run multiple instances of the email engine on a Incoming

single server, this property specifies which mailboxes and
should the email engine process. The value of this Outgoing
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 Incoming

considered in minutes (as configured in AR System True ( and
Email Configuration) or seconds. The email engine Default) Outgoing
interprets the value of this property as follows: False
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.
com.bmc.arsys.emaildaemon.MaxAttachSize and Specifies the attachment types that you want to permit Incoming
com.bmc.arsys.emaildaemon.MaxAttachSizeFileExtensions in an email message and the maximum size of each True
attachment.MaxAttachSize specifies the maximum size False (
limit for attachments, whereas Default)
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


Functionality
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 Incoming
as follows: True and
False ( Outgoing
true — BMC Remedy Email Engine fetches only default)
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 checks to see Default value: Incoming
if all the threads are functioning properly. 30 minutes and
Outgoing
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 Permissible Outgoing
daemon uses for each outgoing mailbox. The optimum range of
number of threads depends on many factors including values: 1
the number of mailboxes, the hardware configuration, through 20
and so on. Default value:
4
com.bmc.arsys.emaildaemon.OutgoingMessagesQueueSize Specifies the size of the queue that the email daemon Default value: Outgoing
maintains for outgoing messages. The optimum 100
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.
com.bmc.arsys.emaildaemon.RMIPORT = 1100 Specifies the port number for remote method Default value: Incoming
invocation (RMI). This feature is used with the 1100 and
EmailAdminAgent.jar file to stop, suspend, resume, or Outgoing
change logging level of the email engine at runtime.
com.bmc.arsys.emaildaemon.SaveSentItem Specifies whether to retain messages in the Email Outgoing

Messages form after sending. To delete sent messages True (
from the Email Messages form, set this property to Default)
False. False
com.bmc.arsys.emaildaemon.securityCacheSize Specifies the number of security keys to be stored in Default value:

the cache. If the value of this property is set to 15, the 20


Functionality
cache already contains 15 security keys, and another Incoming

key is to be added, then the oldest key is removed to and
accommodate the newest one. Outgoing

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 query at a Default value: Outgoing
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 check Default value:
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 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 Outgoing

to connect to the mail server and generating an error. True
In case of an SMTP timeout, the email engine waits for False (
the timeout interval and then marks the queued Default)
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.


Functionality
com.bmc.arsys.emaildaemon.SMTPTimeoutPeriod Specifies the duration in number of seconds to wait Outgoing

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 Outgoing

priority setting first. True
False (
Default)
com.bmc.arsys.emaildaemon.StoreInstructions Specifies whether to store instructions and instruction Incoming

parameters in the AR System server. If set to true, the True
email engine retains data in the Email Instructions and False (
Instruction Parameters forms for troubleshooting. Default)
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 Incoming
if required. If this property is not present in True and
EmailDaemon.properties, or if it is present but set to False ( Outgoing
false, the bulk API logging mode is used. If this Default)
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 stored Default value: Incoming
in the cache to improve the performance. If the value 20
of this property is set to 15, the cache already contains


Functionality
15 templates, and another template is to be added,

then the oldest template is removed to accommodate
the newest one.

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 Outgoing

URL in an HTML message. If the setting is true, the <a True (
href> tag is used. If the setting is false, the URL is not Default)
enclosed in an <a href> tag. False
com.bmc.arsys.emaildaemon.UseNameIfNoEmailAddress Specifies whether to retain display names that do not Outgoing

have email addresses associated with them in the To, True (
CC, or BCC fields. If the setting is true, the display Default)
names are not removed from the To, CC, or BCC False
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.
com.bmc.arsys.emaildaemon.UserChunkSize Specifies the number of users (records from the User Default value: Outgoing
form) to retrieve from the AR System server at one 5000
time. This setting can be used to tune the email
engine's performance.
com.bmc.arsys.emaildaemon.AdminAddresses Specifies the email address of the administrator. If a Default value is Incoming
database transaction fails while storing an incoming set to the
message, the email engine forwards the original mail administrator
to this email address, so that it is retained. An example address
of a transaction failure could be when the database is specified
full and cannot save anymore incoming email during
messages. You can specify multiple addresses installation.
separated by commas.
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.
12.15.4 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.
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.
12.15.5 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.
12.15.6 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
12.15.7 Testing your mailbox configuration

You must test your mailbox configurations to make sure that your mailbox communicates with your mail server
correctly.
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.
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.
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
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.
12.15.8 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

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

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.
Polling Interval — Select a polling interval for the Email Engine to check for 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.

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

(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. 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.
12.15.9 Stopping and starting the Email Engine

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

3.
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
12.16 Configuring BMC Remedy Flashboards

The following topics provide information about configuring BMC Remedy Flashboards:
12.16.1 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

1.
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. 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.
12.16.2 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>
12.16.3 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

1.
-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.
12.16.4 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
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

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

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
Axis
Show X Axis + + +

Show X Axis as Time + +
Show X Axis Ticks + +
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 + +
Y Axis Ticks Color + +
Y Axis Ticks Label Color + +
Y Axis Ticks Label Font + +
Chart
Advanced Color Palette + + +
Chart Border Width + +
Chart Outline Width + +
Custom Time Format + + +
Customizable Parameters +
Display 3D +
Display Table + + +
Foreground Color + +
Foreground Transparency + +

Graph Background Color + +
Graph Background Transparency + +
Legend Border Width + +
Max Bar Width + +
Outline Color + +
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
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
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 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 visible. By default, the
Axis line value is set to 0.

Show Y 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 visible. By default, the
Axis line value is set to 0.
Show Option to display labels above each horizontal bar of the capacity flashboard. If the value is set to 0, the vertical axis labels are displayed
Label 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.
Inside
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
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.
12.16.5 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 config.properties file.
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.
Settings used to change the flashboards format
Setting Description
flashboards.showgraphinflash=[0 Defines which default format to use when displaying flashboards. The options are:
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 technology. The
default is 260.
flashboards.min_flex_height=200 The minimum flashboard height below which a flashboard is rendered by using image-based technology. The
default is 200.
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
12.16.6 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.
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.

12.17 Configuring BMC Remedy Migrator

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
12.17.1 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.
12.17.2 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.
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 Select the server, click Modify, and make the appropriate changes.
server
Delete a server Select the server, and click Delete.
Add or modify the Users Click User Manager. Click Add to add a new user, or select a name in the Users list and click Modify to modify the
list 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 Select Advanced Server Properties. Select a server and click a column and type a port number or private server
firewall support 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
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.
12.17.3 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.
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.
12.17.4 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.
12.17.5 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.
12.17.6 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?

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.
12.18 Configuring the Assignment Engine

The following topics provide information about configuring the Assignment Engine:
12.18.1 Configuring Assignment Engine properties

You can configure the following properties in the ar.cfg file:
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 server for the changes
to take effect.
AE-Poll-Interval The time interval (in minutes) after which the Assignment Engine checks for any pending entries for Assignment.
AE-Poll-Interval: <time>
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.
12.18.2 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.
To stop the Assignment Engine manually on Windows and UNIX
Press Ctrl+C or kill the aejstartup process.
12.19 Securing BMC Remedy AR System

The following topics provide information about how to secure BMC Remedy AR System:
12.19.1 Configuring SSL for the email engine

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

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

e.
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. 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. 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/trialcain
.
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.
12.19.2 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.
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.
12.19.3 Securing incoming and outgoing email

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:
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. Click the Advanced Configuration tab of the outgoing mailbox from which you want the modify instruction
sent.
10. Set the Delete Outgoing Notification Messages field to No.
11.
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 modify
instruction sent.
8. Set the following fields as indicated:
Email Action: Parse
Use Original Template Format: No
Reply With Result: Yes
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

9.
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.
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.
12.20 Configuring BMC Remedy Encryption Security

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:
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:
12.20.1 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 Server configuration file setting
DES 56-bit Data Encryption Standard (DES) using Cipher Block Chaining (CBC) mode.
Encrypt-Data-Encryption-Algorithm: 1
RC4-128 128-bit RC4 key.

Available for Performance Security that does not comply with FIPS. Encrypt-Data-Encryption-Algorithm: 2
RC4-2048 2048-bit RC4 key.

Available for Premium Security that does not comply with FIPS. Encrypt-Data-Encryption-Algorithm: 3

AES-128 128-bit AES CBC key. FIPS noncompliant:

Required for Performance Security that complies with FIPS,
but can be used by servers that do not comply with FIPS. Encrypt-Data-Encryption-Algorithm: 6
See FIPS encryption options for more FIPS information.

FIPS compliant:
AES-256 256-bit AES CBC key. FIPS noncompliant:

Required for Premium Security that complies with FIPS,
but can be used by servers that do not comply with FIPS. Encrypt-Data-Encryption-Algorithm: 7
See FIPS encryption options for more FIPS information.

FIPS compliant:
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.

12.20.2 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.
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:
RSA 512 512-bit RSA key. Default for standard security.

Encrypt-Public-Key-Algorithm: 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.
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*
7. Click Apply.
12.20.3 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 Value Description Server configuration file
state setting
Activated Optional This is the default for BMC Remedy Encryption Performance Security and BMC Encrypt-Security-Policy:
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 Encrypt-Security-Policy:
Remedy Encryption Premium Security FIPS compliance. 1
Only clients with encryption installed can communicate with the server.
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 Encrypt-Security-Policy:

2

Encryption Value Description Server configuration file

state setting
This is the default for standard encryption.

Whether encryption is installed on a client or not, communication with the
server is not encrypted. Network traffic is exchanged in plain text.
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.
12.20.4 Deactivating encryption

To deactivate encryption, select the deactivation options according to the procedure in Configuring the data key.
12.20.5 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 Security Policy value Is server FIPS Description

option compliant?
Selected Required Yes

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, or No Clients communicating with the server cannot communicate with FIPS-compliant
Disabled servers.
For an overview of FIPS, see FIPS encryption options.

Note
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.
8. In the Data Key Details area, select an AES algorithm.

Note
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.
12.21 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:
12.21.1 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.)
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.
12.21.2 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.
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
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.
12.21.3 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

When a BMC Remedy AR System entry is requested, all column values are obtained, including 0length 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.
12.21.4 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:
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',

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 )
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
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 them in exec p_change_LOB_storage(p_in_row =>'Yes', p_dest_tablespace
tablespace ARSYSTEM. =>'ARSYSTEM');

Task SQL statement
Change all LOBs from out-row to in-row, and move them to exec p_change_LOB_storage(p_in_row =>'Yes',p_dest_tablespace
tablespace AR_LOB. =>'AR_LOB');
Move LOBs to tablespace AR_LOB without changing the storage exec p_change_LOB_storage(p_in_row =>Null,p_dest_tablespace
option. =>'AR_LOB');
Change all LOBs from in-row to out-row, and keep them in exec p_change_LOB_storage(p_in_row =>'No',p_dest_tablespace
tablespace ARSYSTEM. =>'ARSYSTEM');
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 in-row, and exec p_change_LOB_storage(p_in_row =>'Yes',p_dest_tablespace
keep them in tablespace ARSYSTEM. =>'ARSYSTEM', p_table_name =>'T1866');
Change the LOBs in table T1866 from out-row to in-row, and exec p_change_LOB_storage(p_in_row =>'Yes',p_dest_tablespace
move them to tablespace AR_LOB. =>'AR_LOB', p_table_name =>'T1866');
Move LOBs in table T1866 to tablespace AR_LOB without exec p_change_LOB_storage(p_in_row =>Null,p_dest_tablespace
changing the storage option. =>'AR_LOB', p_table_name =>'T1866');
Change LOBs in table T1866 from in-row to out-row, and keep exec p_change_LOB_storage(p_in_row =>'No',p_dest_tablespace
them in tablespace ARSYSTEM. =>'ARSYSTEM', p_table_name =>'T1866');
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 will execute to Set serveroutput on
change the LOBs in table T1866 from out-row to in-row. exec p_change_LOB_storage(p_in_row
=>'Yes',p_dest_tablespace =>'ARSYSTEM', p_table_name
=>'T1866', p_generate_SQL_only='Yes');
Display the SQL statements that the stored procedure will execute to Set serveroutput on
change all LOBs from out-row to in-row and move them to exec p_change_LOB_storage(p_in_row
tablespace AR_LOB. =>'Yes',p_dest_tablespace =>'AR_LOB',
p_generate_SQL_only='Yes');

13 Upgrading
Use the following topics to guide you through upgrading BMC Remedy AR System or the BMC Remedy ITSM
Suite.
Goal Instructions
Prepare your environment to upgrade BMC Remedy AR System and the BMC Remedy IT Service Management Suite. Preparing for upgrade
Upgrade with overlays already created. This is a three-stage upgrade for customers who have previously installed BMC Upgrading with overlays
Remedy AR System 7.6.04 and have already implemented overlays. already present
To understand the difference between the two upgrade paths, see Planning to upgrade BMC Remedy AR System.
Upgrade with one-time conversion to overlays. This is a seven-stage upgrade for customers who do not already have Upgrading without
overlays implemented and want to keep all customizations. overlays already present
To understand the difference between the two upgrade paths, see Planning to upgrade BMC Remedy AR System.
Understand how upgrading affects encryption security Upgrading encryption

security
Perform the necessary procedures to complete an upgrade. Post-upgrade procedures
Note
Before upgrading, see the BMC Developer Network for new tools that can help you adapt features from
your prior version to features in the latest version.
13.1 Preparing for upgrade

Review or perform the following sections before you start upgrading.

13.1.1 Reviewing the compatibility matrix before upgrading


Java support
Language offerings
Remedy.

Note



Reviewing the upgrade requirements
13.1.2 Reviewing the upgrade requirements

This section includes information about the hardware and software requirements for installing BMC Remedy AR
System. It also includes information about 32-bit and 64-bit requirements.
This information is critical when you are installing other BMC applications (for example, BMC Atrium Core and
BMC IT Service Management).
AR System hardware requirements for upgrades

Medium 2000 100 10 10,000 or fewer
Large 5000 250 50 30,000 or fewer


Note
2 CPU 4 CPU 4 CPU

Core Core Core
8 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
2 CPU 4 CPU

Core Core 4 CPU

8 GB 8 GB Core
RAM RAM 8 GB
60 GB 60 GB RAM
disk disk 60 GB
disk
BSM) CMS server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk

RAM RAM RAM
disk disk disk

RAM RAM RAM
System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 4 GB 8 GB
RAM RAM RAM
100 GB 100 GB 100 GB
disk disk disk
System server
2 CPU 4 CPU 4 CPU
Core Core Core
4 GB 8 GB 12 GB
RAM RAM RAM
100 GB 100 GB 200 GB
disk disk disk


RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
4 CPU Core
4 GB 8 GB 8 GB
RAM RAM RAM
60 GB 60 GB 60 GB
disk disk disk
AR System software requirements for upgrades

IBM DB2
Oracle
Sybase
Note

server* Environment
(JRE)


server* Environment
(JRE)
Clients Yes Yes
Developer Studio
Note
configurations.
32-bit and 64-bit requirements for upgrading your OS

releases.
Note
Important


Note
Plug-ins
Java requirement
the MAPI protocol.
Note
64-bit computer.

13.1.3 Preparing your database for an upgrade

Before you upgrade the BMC Remedy AR System server, prepare your database correctly, as described in the
following topics:
Recommendation
If you are upgrading, review the compatibility matrix for any required change in the database clients for
the latest version of the AR System server. If an updated version of the database client is required but not
installed before you upgrade, the new environment will not be a supported configuration, and the
upgrade might fail.
Test the new database client’s connection to the existing AR System server database. The new client is
used as part of the installation process to connect to the database. At the end of the installation, the
installation process binds AR System server with the client so that the product can work correctly under
normal operation.
To avoid a decline in the BMC Remedy AR System server performance, BMC recommends the following:
Do not use a firewall between the AR System server and database tiers. This can impact performance
significantly.
When possible, set up a high-speed backbone between the AR System server and the database server.
If using Ethernet, install the BMC Remedy AR System server and the database server on a separate switched
network that is isolated from other network traffic.
Avoid putting a wide-area network between the AR System server and the database server.
Make sure that each network device between the AR System server and the database server is
communicating at the maximum bandwidth.
If you are planning to install CMDB or ITSM applications in addition to BMC Remedy AR System, the
following minimum space is required:
2 GB for the data file
1 GB for log and temp files
When installing more than one ITSM application, add 2 GB to the data file and 100 MB to the log file
size for each additional application. BMC recommends at least 2 GB of disk space for the database.
Depending on the number of records your system handles and the specific type of database you are
using, however, you might need more than this. If you do not have 2 GB or more before beginning
the installation, you might run out of free space during installation. As the transaction log fills up, the
BMC Remedy AR System suspends operation. When the transaction log is completely full, the BMC
Remedy AR System writes a message to the BMC Remedy AR System error log and the installation
terminates.
Note

In BMC Remedy AR System 8.1, the installer displays a warning message indicating
the required space for additional installation of CMDB or ITSM applications.
If the transaction log fills during the installation and the installation fails, clear the
transaction log, and then increase the size of the transaction log before reinstalling
the product.
Note
A common issue is that a router's Auto Negotiate option can incorrectly set the router to 10 MB Half
Duplex. NICs, routers, and other network devices then agree on the fastest speed to communicate
together, but that speed is usually too slow. To remove this variable, if all the network devices can
communicate at 1 GB Full Duplex, set them as such, and disable the Auto Negotiate option on the router.
For technical assistance on installing your database, contact the database vendor.
Preparing your Microsoft SQL Server database before you upgrade the AR System
server
This section describes the steps you should perform with your Microsoft SQL Server database when you install
BMC Remedy AR System or any application in the BMC Remedy IT Service Management Suite.
Tips to remember
To optimize Microsoft SQL Server 2005 (or later) after you finish installing or upgrading the AR System
server
Tips to remember
Purge the transaction log frequently to prevent it from filling up during installation.
Back up the SQL Server log files, and then change the SQL Server Transaction Logging mode from FULL to
SIMPLE.
If the database is not configured to extend automatically, make sure that you have set the following:
Set the BMC Remedy AR System data file size to 1 GB or greater; BMC Software recommends at least
2 GB. If you are planning to install CMDB or ITSM applications in addition to BMC Remedy AR
System, add 2048 MB to the data file for each additional application.
Set the log file size to 1 GB or greater. If you plan to install CMDB or ITSM applications in addition to
BMC Remedy AR System, add 2048 MB to the data file for each additional application.

Note
BMC recommends that you set the value of the Next-ID-Block-Size: Server option in the
ar.cfg or ar.conf file to 100.
1. Install the Microsoft SQL Server database.

You can install the SQL Server database on the same computer where BMC Remedy AR System is installed,
System.
2. Install SQL Server clients (that is, the drivers).
For remote installations, install the SQL Server clients on the same computer as the BMC Remedy AR
System server.
3. Create an instance of the database.
4. Set your SQL Server connections to allow TCP/IP:
a. Open the SQL Server Configuration Manager.
b. Click Network Configuration for your SQL Server instance.
c. Make sure that TCP/IP Protocol is enabled.
d. View the TCP/IP Properties dialog box for your database instance, and make sure that the IP
Addresses tab has a TCP Port number specified. (The default port is 1433.)
e. Restart all SQL Server services to effect this change.
5. Determine data file and log file sizes for your SQL Server database.
Note
During the installation, you are required to declare table sizes. This enables you to pre-size the
data files to improve application performance.
installation.
To optimize Microsoft SQL Server 2005 (or later) after you finish installing or upgrading the AR
System server
Important
Perform these tasks immediately after you complete the AR System server installation or upgrade and
before you install any other BMC applications (for example, BMC Atrium Core).

If you are using Microsoft SQL Server 2005, make sure you have installed the most current Service Pack.
2. (For a server group or a shared database) Stop all the AR System instances.
3. Set the following SQL Server forced parameterization and SNAPSHOT isolation parameters:
For example:
alter database ARSystem set recovery simple;

alter database ARSystem set single_user with Rollback immediate;
alter database ARSystem set READ_COMMITTED_SNAPSHOT ON;
alter database ARSystem set multi_user;
alter database ARSystem set PARAMETERIZATION FORCED;
4. Verify the values by issuing the following command:


Microsoft SQL Server installation can support two authentication modes:
Windows authentication mode

Mixed authentication mode
To find the supported authentication mode in your SQL Server environment, connect to the SQL Server instance
from Management Studio > Server Properties > Security.
If only Windows authentication mode is supported, choose Windows authentication when you install the BMC
If mixed authentication mode is supported, choose Windows authentication or SQL Server authentication when
you install the BMC Remedy AR System server.

Note
Create the folder (for example, c:\data, before you pre-create the database. Otherwise, the database
creation fails.
1.
1. In a Query Window, run the following command:
use tempdb
2. Create a database, for example:
CREATE DATABASE "ARSystem" ON (NAME = "ARSystem_data", FILENAME = 'c:\data\ARSys.mdf', SIZ
CREATE LOGIN "ARAdmin"WITH PASSWORD = 'AR#Admin#', DEFAULT_DATABASE = ARSystem
3. Use the created database, for example:
use ARSystem
4. Create a user name and login, for example:
CREATE USER "ARAdmin" FOR LOGIN "ARAdmin"
5. Make the user the db_owner, for example:
sp_addrolemember 'db_owner', 'ARAdmin'
Related topics

Completing the planning spreadsheet for an upgrade
Preparing your Oracle database before you upgrade the AR System server
This section describes the steps you should perform with your Oracle database before you install BMC Remedy

Typically, Oracle database administrators create instances, directories, and groups, and they install the Oracle
database and Oracle client before proceeding with the BMC Remedy AR System installation.
BMC highly recommends that you review Performance tuning for BSM for other recommendations
about tuning your Oracle database in preparation for performing this upgrade. This section includes
recommendations for:
Small, medium, or large Oracle databases

Cursor sharing

CLOB storage
Case-insensitivity
Diagnostics
1. Install at least one instance of the Oracle database. (Only your database administrator can create database
instances.)
You can install it on the same computer where the BMC Remedy AR System is installed, or on a remote
server that is networked to the computer where you plan to install BMC Remedy AR System.
2. Install Oracle clients on the AR System server.
When you are using a remote Oracle database, make sure that you install the Oracle client type as
Administrator on the AR System server. Additionally, make sure that the installation includes Oracle utilities
such as import tools (imp).
3. (UNIX only) Make sure that the administrator who is installing BMC Remedy AR System is a part of the
database group.
4. Enable the TCP/IP Protocol for the database.
5. Confirm connection to your Oracle database.
Contact your database administrator for more information.
6. For remote installations, install and configure the Oracle client on the same system where you will install
7. Set the BMC Remedy AR System data file size to at least 2 GB.
Note
For each additional product, add at least 2 GB to the data file size.
8. Confirm that these database parameters are set.

9. Set the tablespace CanGrow parameter to YES.
10. To prevent BMC Remedy AR System from reaching the size limit of the database, set your tablespaces to
auto-extend by executing the following SQL statement as the system user:
ALTER DATABASE DATAFILE '<OracleHome>/DATABASE/ARSYS' AUTOEXTEND ON NEXT 100M MAXSIZE UNLI
11. Set the table space and temporary table space to at least the following minimum settings:
Parameter Suggested value
arsys 2000
artmpf 500

These tablespace names may be different depending on your environment.

12. To avoid time-out errors during installation, set the System Global Area (SGA) minimum size to at least 1 GB
(small database), 3 GB (medium database), or 6 GB (large database).
For Oracle 10g or 11g, BMC Software recommends setting the maximum SGA size and enabling the
database to automatically manage the internal memory structures of the SGA.
For example, to change the SGA size to 1 GB, use the alter system set sga_target=1G scope=both
command.
13. Verify or set the following environment variables.
variable
NLS_LANG Specifies globalization settings. For information about NLS_LANG and its usage, see the following notes from Oracle:
(Windows) 144808.1, 227330.1, 260192.1. If you are using the Oracle Instant Client, see step 14.
LANG (UNIX) Specifies globalization settings.
ORACLE_HOME Points to the directory where the Oracle client is installed. Use this value: $<ORACLEHOMEDirectoryPath>
Note
The installer accepts the ORACLE_HOME path as a user input on UNIX.
If you are using the Oracle Instant Client, see step 14.
PATH (For Windows) Points to the bin directory of the Oracle client. For example, C:\oracle\product\10.2.0\client_1\bin. The
bin directory contains the path to the Oracle binary files. Add the following value to the PATH:$ORACLE_HOME/bin
Note
If you are using multiple versions of Oracle, make sure that the entry for the version you want to use appears
before the others.
14. When using the Oracle Instant Client, complete the following steps:
a. When installing the Oracle Instant Client, choose Administrator as the installation type. (For more
information, see your Oracle database documentation.)
b. Set the system path to the folder where the Oracle Instant Client is located on the local computer.
c. Set the ORACLE_HOME system variable to point to the folder where the Oracle Instant Client is
located on the local computer.
d. Set the TNS_ADMIN system variable to point to the folder where the correct tnsnames.ora file is
located.
Note
By default, the Oracle Net Services configuration files are located in the
OracleHome\network\admin directory. To change the default location, you can set the
TNS_ADMIN environment variable to the appropriate value (for example,

OracleBase\OracleHome\test\admin). The AR System suite installer accepts the value of the

Database Client Home Path field only for UNIX installations. If the installer does not find the
tnsnames.ora file in dbClientHomePath\network\admin or in the directory specified in
TNS_ADMIN, it prompts you to enter the path in the AR System Server Database
Information panel. If you provide a valid path, the installer sets the TNS_ADMIN
environment variable in the arsystem.sh script. The installer accepts your input and sets the
value for TNS_ADMIN only if you have Read permissions on the tnsnames.ora file.
e. Set the NLS_LANG system variable value for non-unicode or unicode.

f. Create the following soft links that point to libclntsh.so.11.1:
libclntsh.so
libclntsh.so.10.1
g. Create the directory structure as follows: ORACLE_HOME/bin and ORACLE_HOME/lib.
15. Configure the tnsnames.ora file to make sure that the service name is the same as the entry name for the
server on which you are installing BMC Remedy AR System. For example:
COMPUTER1 =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = computer1.xyzcompany.com)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = COMPUTER1)
)
)
During the installation, you are asked for the database instance name, and it should match the entry in the
tnsnames.ora file (for example, MACHINEA).
For more information about tnsnames.ora, see your Oracle documentation.
16. Find the Connection Identifier in the tnsnames.ora file (located in $ORACLE_HOME/network/admin folder).
If multiple listeners are configured, locate the correct tnsnames.ora file in the correct $TNS_ADMIN value
path.
Following is an example entry in tnsnames.ora:
MyConnectionIdentifier =
(DESCRIPTION =
(ADDRESS_LIST =
(ADDRESS = (PROTOCOL = TCP)(HOST = hostname)(PORT = 1521))
)
(CONNECT_DATA =
(SERVICE_NAME = ORCL.MYWORLD)
)
)

17. Make sure that the Oracle listener is running and is configured correctly for the database.
18. After you finish installing the AR System server:
Add the following line to the ar.cfg file (Windows) or ar.conf file (UNIX) if cursor_sharing is set to
FORCE:
Oracle-Cursor-Sharing: FORCE
Add the following line to the Oracle initialization file:
CURSOR_SHARING: FORCE
For more information, see the Oracle's Cursor Sharing for BMC Remedy Products white paper on the
Customer Support website at: http://www.bmc.com/support.
19. Oracle has a limitation with cursor sharing and case insensitivity. With the Db-Case-Insensitive and
Db-Functional-Index parameters,
Oracle does not properly use the indexes if cursor sharing is set to FORCE. Therefore, even though FORCE
is recommended with normal case sensitivity, if you want to use case insensitivity, use EXACT. For more
information, see the descriptions for Db-Case-Insensitive and Db-Functional-Index in ar.cfg or ar.conf
options: C-D.

For a BMC Remedy AR System server, you can use a tablespace that you previously created in Oracle.
Note
If you are using a RAC or ASM Oracle database, you must create tablespaces before installing BMC
Remedy AR System. For more information about creating tablespaces in RAC or ASM databases, refer to
your Oracle documentation.
1. In a SQL*Plus window, create the tablespace and temporary tablespace. For example:
create tablespace ARSYSTEM

datafile 'C:\DB-DATA\SSIORA12\DATA\ARSYS.dbf ' size 7000M reuse;
create temporary tablespace ARSTMPSPC tempfile 'C:\DB-DATA\SSIORA12\DATA\ARTEMP.dbf' size
2. Create a user. For example:
create user aradmin identified by AR#Admin#

default tablespace ARSYSTEM
temporary tablespace ARSTMPSPC
quota unlimited on ARSYSTEM;
3.
3. Create a role for the user you created in step 2 ab ove. For example:
create role ARole_arsys not identified;
4. Set the privileges for the role. For example:
grant alter session, create cluster, create database link, create sequence, create session
5. Grant the role to the user. For example:
grant ARole_arsys to aradmin;

go
Related topics
Preparing to upgrade on a Unicode database

Preparing your DB2 database before you upgrade the AR System server
This section describes the steps you should perform with your DB2 database before you install BMC Remedy AR
System or any application in the BMC Remedy IT Service Management Suite.
Before you begin

Some forms have entries that exceed the default BMC Remedy AR System size limit for each record. The
following steps help optimize the way DB2 determines which forms it places in larger containers. Perform these
steps to provide a balanced performance standard across all the forms.
Before you begin
If the BMC Remedy AR System server and the IBM DB2 database are running on the same environment on a
single server (not a remote DB2 database), and you are installing BMC Remedy AR System on a DB2
database, change the Local Security Policy settings before you install the BMC Remedy AR System server.
Go to Start > Administrative Tools > Local Security Policy > Local Policies > User Rights Assignment > Act as

part of the operating policy and add the user (administrator) who is running the BMC Remedy AR System
process. Then, select Local Policies > User Rights Assignment > Log on as a service policy, and add the user
(administrator) who is running the BMC Remedy AR System process .
Verify that the following DB2 values have been set during the installation of BMC Atrium CMDB:
APP_CTL_HEAP_SZ 40480 (DB2 version 9.4 or earlier)
APPL_MEMORY AUTOMATIC (DB2 version 9.5 or later)
INSTANCE_MEMORY AUTOMATIC (DB2 version 9.5 or later)
UTIL_HEAP_SZ 95000
STMTHEAP 60000
LOGFILSIZ 4000
To perform the following steps, make sure you are logged in as the DB2 instance owner. For example:
su - db2 instance
If the database is not configured to extend automatically, set the BMC Remedy AR System data file size to
at least 2 GB for one BMC Remedy application, or to at least 8 GB if you are also installing all BMC Remedy
ITSM applications.
Note
As of version 8.1 of the BMC Remedy IT Service Management Suite, your DB2 database server must be at
version 9.7 or later to upgrade the BMC Remedy ITSM Suite. If you are unable to upgrade your DB2
database server, refer to the instructions provided in the BMC Remedy ITSM documentation.
1. Install the DB2 database server.

You can install the DB2 database server on the same computer where the AR System server is installed or
on a remote server that is networked to the computer where you plan to install BMC Remedy AR System.
2. Install DB2 clients.
For remote installations, install the DB2 clients on the same computer as the AR System server.
3. (Solaris only) Install the DB2 libdb2.so library.
The AR System server is dynamically linked to the DB2 library on Solaris. If this library was not installed with
the DB2 client, install the library on the same computer where you plan to install the AR System server.
Note
For information on the supported DB2 client library versions, see the compatibility matrix (
Checking system requirements and supported configurations).
4.
4. Create and name a DB2 instance.

For local database servers, create a DB2 instance on the local computer.
For remote database servers, create a DB2 instance on the remote computer.
Note
For naming restrictions, check your database vendor documentation.
5. Set the port configuration:
db2 update dbm cfg using SVCENAME 60007
6. Restart the DB2 instance:
db2stop
db2start
7. Verify the port configuration:
db2 get dbm cfg | grep SVCENAME
Be sure to use the correct DB2 port during the installation.

8. Make sure the TCP/IP Protocol for the database is enabled, and set a TCP/IP port for the database instance.
installation. (For the list of parameters, see your planning spreadsheet.)
11. If you are using DB2 9.7, grant permissions to the DBADM role:
grant DBADM, BINDADD ,CONNECT, CREATETAB, CREATE_EXTERNAL_ROUTINE,

CREATE_NOT_FENCED_ROUTINE, IMPLICIT_SCHEMA, QUIESCE_CONNECT, LOAD
on database to user <userName>
Make sure the DBADM user exists as a local Windows account, and make sure that the passwords of the
local Windows account and the DB2 account are identical.
12. Make sure that the database's local catalog name matches the database's name on the database server.
If the names do not match, the installer will not display the Upgrade/Overwrite dialog box, and a warning
will appear: Warning! You have entered an existing database login.
13. For a Unicode DB2 installation, make sure that the DB2CODEPAGE variable is set to 1208.
On Microsoft Windows, for example, enter the following command from the DB2 command window:
db2set DB2CODEPAGE=1208
Note

The DB2CODEPAGE setting is part of the database client libraries. Make sure that this setting is
correct on the computer where the BMC Remedy AR System is running, which might be different
from the computer where the database is located.
For more information about the syntax and usage of DB2 commands, see the IBM DB2 documentation.
1. Create an operating system user account (for example, bmcuser1) on the same computer where you
installed the DB2 database and where you will install the AR System server.
Note
The new operating system user account must have the Log on as Service rights.
2. For BMC Remedy AR System root installations or BMC Remedy AR System installations performed by a user
who is not a database instance administrator, make the user a member of the following groups, which are
created during the DB2 database installation:
db2iadm1
db2fadm1
db2asgrp
3. Give the user privileges to the following folders:
/etc/arsystem (Write permission)
/tmp (Write permission)
/opt/bmc/ (Write permission)
User-defined installation directory (Write permission)
/usr/sbin/slibclean (Execute permission on AIX platforms)
/tmp or /var/tmp or /usr/tmp (Write permission, depending on the operating system)
If the IATEMPDIR variable is set during the installation, make sure that the user has permission to the
appropriate file.
a. If you are migrating the DB2 database or instance to a different computer or environment, provide
For example:
GRANT USE OF TABLESPACE <Tablespace> TO USER

<DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
database user.
b.
b. Log in as the user (for example, bmcuser1 ), and start the installation.
Make sure that the user provided during installation is the owner of the pre-created 32K tablespace.
You can verify the owner of the tablespace using the following SQL query.
select TBSPACE, OWNER from SYSCAT.tablespaces where datatype='A' and

tbspace!='SYSCATSPACE' and PAGESIZE=32768
During the installation, enter the same user name (for example, bmcuser1) in the AR Database Login
1. On the remote computer, complete the following steps:

a. Create an operating system user account with the same user name that was u sed in step a (f or
example, bmcuser1) on the same computer where you will install the AR System server.
Important
This DB2 user must have database creation privileges. Database access privileges are not
sufficient.
b. For BMC Remedy AR System root installations or BMC Remedy AR System installations performed by
a user who is not a database instance administrator, make the user a member of the following
groups, which were created during the DB2 database installation:
db2iadm1
db2fadm1
db2asgrp
c. If you are migrating the DB2 database or instance to a different computer or environment, provide
For example:
GRANT USE OF TABLESPACE <Tablespace> TO USER <DB2DatabaseUserLoginProvidedDuringARSys
database user.
d. Catalog the database from the DB2 client using a command-line processor.
The catalog command syntax is:
db2 catalog tcpip node <instanceNameAlias> remote <hostName> server <tcpPort>
For example:
db2 catalog tcpip node arsdbname remote servername.abc.com server 50000

For more information, see your DB2 documentation.

e. Confirm that the remote DB2 connections are correct.
After the remote connection is configured, create a DB2 database on the remote database server
and from the client computer DB2 prompt. Then, enter:
db2 connect to <databaseName>
<databaseName> is the name of the underlying database (for example, arsystem).

f. Log in as the user (for example, bmcuser1) on the remote computer, and start the installation.
During the installation, enter the same user name (for example, bmcuser1 in the AR Database Login
On a DB2 database, a 32 KB tablespace is created as a System Managed Storage (SMS) on new and overwrite
installations of the BMC Remedy AR System server.
The 32 KB tablespace is added during a BMC Remedy AR System installation as follows:
During a new installation, a 32 KB tablespace is created in the background with the name given for the
regular tablespace but concatenated with _32kb.
For example, if the tablespace name is ARSystem for the BMC Remedy AR System server, an additional
tablespace with a 32 KB page size is created and named ARSystem_32KB.
During an overwrite installation, the underlying database is dropped and a new database and tablespace
are created as they are for a new installation.
During an upgrade from version 7.1.00 to 8.1, the installer checks for the Form: AP:Rule Definition form
entry and, on the underlying database, validates the availability of the 32 KB tablespace that is listed in the
clause. If the 32 KB tablespace is present, the upgrade continues successfully. If it is not present, the
installer creates a 32 KB tablespace similar to the one described for a new installation and continues the
installation.
Note
pagesize are automatically created as they are required by the installer.
If you select to install the Approval Server, the installer adds the Approval Server Form: AP:Rule Definition form
entry and its clause with the newly created 32 KB tablespace to the ardb.cfg (ardb.conf) file. (The existence of this
file is validated, and if it is not present when you install the Approval Server, the file is created. The Form: AP:Rule
Definition form entry is also validated to make sure that the clause contains the correct 32 KB page size
tablespace name.)

Note
You must pre-create the database with the same Database Login ID that is used as a value for the BMC
Remedy AR System Server DB Login ID installation parameter during the database installation. (For
example, ARAdmin).
To pre-create a DB2 database:
1. Create a database.
Create a Unicode database:
DB2 CREATE DATABASE ARSYSTEM USING CODESET UTF-8 TERRITORY US
Create a non-Unicode database:
DB2 CREATE DATABASE ARSYSTEM
2. Connect to the created database, for example:
CONNECT TO ARSYSTEM
3. Drop the default tablespace.
drop tablespaces userspace1
4. Create two bufferpools: one with a 16K pagesize and another with a 32K pagesize.
Bufferpool names are user-defined (for example: arbp1, arbp2).

5. Create one of the following tablespaces:

Create Database Managed Storage (DMS) tablespaces using the 16K pagesize bufferpool created in
step 4.
For example:
CREATE TEMPORARY TABLESPACE ARTMP_PT01 pagesize 16k MANAGED BY DATABASE USING (FILE '
CREATE REGULAR TABLESPACE ARSystem pagesize 16k MANAGED BY DATABASE USING (FILE '/dat

Create System Managed Storage (SMS) tablespaces using the 16K pagesize bufferpool created in
step 4.
For example:
CREATE TEMPORARY TABLESPACE ARTMP_PT01 pagesize 16k MANAGED BY SYSTEM USING ('artmp')
CREATE REGULAR TABLESPACE ARSystem pagesize 16k MANAGED BY SYSTEM USING ('ardata') ex
[dropped table recovery off]
The container (artmp or ardata) can be an absolute or relative directory name.

6. Create SMS tablespaces using the 32K pagesize bufferpool created in step 4.
For example:
CREATE TEMPORARY TABLESPACE ARTMP_PT01_32KB pagesize 32k MANAGED BY SYSTEM USING ('artmp_3
CREATE REGULAR TABLESPACE ARSystem_32KB pagesize 32k MANAGED BY SYSTEM USING ('ARSys_32KB'
Note
pagesize need to be created as they are required by the installer.
Optional parameters are enclosed in square brackets, for example:

[ dropped table recovery off]
Note
The Dropped Table Recovery Off option can improve performance but it means that you cannot
recover a table if it is accidentally dropped.
7. Grant the created tablespaces permissions for the database user.

For example:

ARSystem TO USER <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
with grant option
ARSystem_32KB TO USER <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
WITH GRANT OPTION
8.
8. (For UNIX) Start the DB2 instance as the

<DB2DatabaseUserLoginProvidedDuringARSystemInstallation>.
If you are using the default database user and password:
db2 connect to ARSystem user aradmin using AR#Admin#
If you are using a different database user and password:
db2 connect to ARSystem user <DB2DatabaseUserLoginProvidedDuringARSystemInstallation>
Alternatively, you can also use the su command to change the owner of the DB2 instance.
For example:
su - <DB2DatabaseUserLoginProvidedDuringARSystemInstallation> and then starting the D
9. If the following values for the following commands are not already set during the installation of BMC
Atrium CMDB, run the following commands:
DB2=> UPDATE DB CFG for databaseName using APP_CTL_HEAP_SZ 40480 (version 9.4 or earlier)
DB2=> UPDATE DB CFG for databaseName using APPL_MEMORY AUTOMATIC (version 9.5 or later)
DB2=> UPDATE DB CFG using INSTANCE_MEMORY AUTOMATIC (version 9.5 or later)

DB2=> UPDATE DB CFG for databaseName using UTIL_HEAP_SZ 95000
DB2=> UPDATE DB CFG for databaseName using STMTHEAP 60000
DB2=> UPDATE DB CFG for databaseName using LOGFILSIZ 4000
Note
The default database name is ARSYSTEM.
10. If the database is on a remote computer, grant the tablespace permission to the ARAdmin user by running
the following command:
DB2=> grant use of tablespace tablespaceName to user aradminUser with grant option;
11. When you finish, perform the following steps:

a. Enable the database you created.
b. Set the transactional logs.
BMC recommends the following settings:
Log file size (4KB) (LOGFILSIZ) 20000
Number of primary log files (LOGPRIMARY) 8
Number of secondary log files (LOGSECOND) 10

Log retain for recovery enabled (LOGRETAIN) OFF
User exit for logging enabled (USEREXIT) OFF
c. Check that the options are consistent with HADR mode.

For IBM DB2 databases, the installer creates the following BMC Remedy AR System database components:
Database components created for DB2
BMC Remedy AR Database tables that the BMC Remedy AR System installer creates on the DB2 server. The tables store all the data related to
System Database the BMC Remedy AR System database.
Tablespaces Logical layer between the database and the database objects that are stored in the database. The installer creates the
following tablespaces:
User (USER-DEFINED-TABLESPACE, for example, ARSystem) — Stores user-defined tables. The user tablespace is
where the BMC Remedy AR System tables will reside.
Temporary (USER-DEFINED-TEMP-TABLESPACE, for example, ARTMPSPC) — Stores temporary tables that are used
for short-term activities, such as sorting and displaying search results.
Catalog (SYSCATSPACE) — Stores system metatables.
SMS tablespaces In system-managed tablespaces:
The DB2 system manages the container space when the user specifies the container location.
The system increases the tablespace size dynamically when the number of records increases.
Data is stored in a directory container.
DMS tablespaces In database-managed spaces:
The database administrator (DBA) manages the container size.

Data is stored in a file container.
Space is allocated when the tablespace is created. You can also increase the size manually, as needed.
If the DMS space is not sufficient when you want to upgrade the BMC Remedy AR System server, double the pages of
the syscatspace.
Note
BMC recommends that you use SMS instead of DMS.
Containers Store physical data and tables corresponding to BMC Remedy AR System. There are three types of containers: file, directory,
and disk.
The AR System installer adds the following lines to the BMC Remedy AR System database configuration file
(ardb.cfg or ardb.conf):

Form: NTE:SYS-NT Process Control

Form: NTE:SYS-NTUnProcessedRecords
Form: SRM:Request
Form: NTE:SYS-Individual NT Control
Form: NTE:SYS-Group NT Control
configuration file if you are installing BMC Asset Management.
Form: AST:PurchaseRequisition-Detail-Signature
configuration file if you are installing BMC Change Management.
Form: CHG:Infrastructure Change

configuration file if you are installing BMC Service Desk: Incident Management.
Form: HPD:Help Desk

Form: HPD:Search-Assignment Logs
Form: HPD:Search-Worklog
Form: HPD:IncidentInterface_Create
In the preceding clause, tablespacename is the name of the tablespace you created earlier.

When you upgrade a BMC Remedy AR System 8.1 server that uses a DB2 database in an environment supporting
BMC Remedy ITSM applications, BMC recommends a minimum database transaction log file size of 1.3 GB.

Before starting the upgrade, adjust the following DB2 Universal Database configuration parameters to ensure that
logfilesize >= 1.3 GB:
LOGFILSIZ
LOGPRIMARY
LOGSECOND
For example:
Log file size (4KB) (LOGFILSIZ) = 20000
Number of primary log files (LOGPRIMARY) = 8
Number of secondary log files (LOGSECOND) = 10
Log retain for recovery enabled (LOGRETAIN) = OFF
User exit for logging enabled (USEREXIT) = OFF
Warning
This example is from a test environment and represents a minimum transaction log file size. To
determine the log file requirements for your environment, consult your database administrator before
beginning the upgrade.
For more information about determining your transaction log file size, go to
http://publib.boulder.ibm.com/tividd/td/tec/SC32-1233-00/en_US/HTML/ecoimst65.htm.

If you are using any version of BMC Service Level Management prior to version 7.6.04 and you want to upgrade to
version 8.1, then you must upgrade your BMC SLM DB2 database by running the DB2 database script.
Note
If you are performing a new installation of BMC Service Level Management 8.1, you do not need to
complete these steps.
1. Do one of the following tasks:

a. During the installation, if the ardb.cfg (ardb.conf) file is not detected, you receive an error message
that you must first create the ardb.conf file.
b. During the installation, if the ardb.cfg (ardb.conf) file exists but there is no SLM:ServiceTarget form
entry with clause of 32KB tablespace, you receive an error message that you must execute the
rundb2upgrade.sh script.
2.
2. Run either of the following:

a. (AIX) Run ./rundb2upgrade.sh.
b. (Windows) Run rundb2upgrade.bat.
3. At the User Name prompt, type the AR administrator user name.
4. At the Password prompt, type the AR administrator user password.
5. At the AR Server Port prompt, type the AR port number.
6. Do either of the following tasks:
a. (AIX) At the AR Database Name prompt, type the AR table space name (case sensitive).
b. (Windows) at the DB2 Table Space name prompt, type the AR 32KB table space name.
7. At the AR Installation Directory prompt, type the AR installation path.
Note
For Windows, the AR installation path must be in 8.3 format.
8. At the SLM Installation Directory prompt, type the SLM installation path.
9. At the Export Target Directory prompt, type the path for the exported data.
10. After running the script, re-install BMC Service Level Management 8.1.
Note
The script file is in the utility directory of DISK 1.
Related topics
ar.cfg or ar.conf
Preparing your Sybase database before you upgrade the AR System server (See the "Forms with more than 254
fields" section for information about creating the ardb.conf file.)

Preparing your Sybase database before you upgrade the AR System server
This section describes the steps you should perform with your Sybase database before you install BMC Remedy


These steps are usually performed by a user who has database administrator privileges.
Note
If you try to install the BMC Remedy AR System server on top of 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'.
1. Install the Sybase database.

You can install the Sybase database on the same computer where the BMC Remedy AR System is installed,
System.
Note
A warning message with the names and paths of the dummy devices is displayed during the
installation procedure (after the Database File Input Panel is displayed). You must manually delete
these dummy devices after the installation procedure is complete.
2. Install Sybase clients.

For remote installations, install the Sybase clients on the same computer as the BMC Remedy AR System
server.
3. From the directory where the 64-bit Sybase client is installed, source the database.
../SYBASE.sh
4. Make sure that the TCP/IP Protocol for the database is enabled.
5. Verify or set the DSQUERY and SYBASE environment variables as follows:
DSQUERY=SybaseServer; export DSQUERY
SYBASE=SybaseInstallDirectory; export SYBASE
These examples use the syntax for Bourne shell.
7. If you are upgrading from BMC Remedy AR System 7.1.00 to 8.1, set the Select into database option for
the database that you are upgrading.
installation.

8.
Tip
Refer to the planning spreadsheet for AR System installation parameters.
9. Change the minimum page size to 8 KB. For information about increasing the page size, see your Sybase
documentation.
10. Increase the default tempdb size to 600 MB.
11. If you created a device in addition to a master device, designate the database device as a default database
device. This is required because BMC Remedy AR System is always created on the default device.
12. If the database is configured to extend automatically, specify the following values:
a. Set the BMC Remedy AR System data file size = 3 GB or larger.
Note
If the database is not configured to extend automatically, set the BMC Remedy AR System
data file size to at least 2 GB for one BMC Remedy ITSM application, or to at least 8 GB if
you are also installing all BMC Remedy ITSM applications.
b. Set the log file size to 2 GB or larger.

c. Change the Sybase configuration file to the following recommended minimal values, and restart the
Sybase server:
\[Meta-Data Caches\]
number of open objects = 1310072
number of open indexes = 512000
number of open partitions = 6000
\[Physical Memory\]
max memory = 128000
\[SQL Server Administration\]
procedure cache size = 7000
\[Lock Manager\]
lock scheme=datarows
\[User Connections\]
number of user connections=50
13. Set the following Sybase database configuration parameters:

Max Memory = 128000
Number of Locks = 15000

Number of Open Partitions = 15000

The BMC Remedy AR System 8.1 suite installer optimizes SQL calls for installation on Sybase.
Therefore, a larger number of LOCKS must be configured for the database.
14. To prevent the transaction log from filling up during installation, set the trunc log on chkpt database
option on the following databases:
BMC Remedy AR System database
tempdb
Use the following commands: sp_dboption databaseName, 'trunc log on chkpt', true
go
Note
Disable the trunc log on chkpt option for all databases after the successful installation
and before any production activity.
15. If you are using Sybase 15, make sure that the number of open partitions parameter is set
appropriately.
For more information, see your Sybase documentation.
16. If you plan to install the BMC Atrium CMDB Product Catalog or any ITSM application, make the following
changes:
Set the Number of Open Objects to 30000.
Set the Number of Open Indexes to 15000.
Increase the size of tempdb. (You might have to create another device to increase the size of
tempdb.)
For more information about the LOCKS setting, see your Sybase documentation.
1. Create a device.
For example:
use master
go
disk init name='ARSystem_data', physname='/data1/ardata/ ARSys', size='1024M'

go

disk init name=' ARSystem_log', physname='/data1/ardata/ARSysLog', size='500M'

go
2. Create the database.

For example:
create database ARSystem on ARSystem_data=1024 log on ARSystem_log=500 with override
go
use master
go
3. Create the login with a password.

For example:
sp_addlogin 'ARAdmin', 'AR#Admin#'

go
4. Create the db_owner group.

For example:
sp_addgroup db_owner
go
grant all to db_owner

go
5. Create the user pointing to the created login and group.

For example:
sp_adduser 'ARAdmin', 'ARAdmin', db_owner

go
use master
go
6. Modify the login to make its default database, the earlier created database.
For example:
sp_modifylogin ARAdmin, defdb, ' ARSystem'

go
use ARSystem
go

7. Change the owner of the database to be the created user.

For example:
sp_changedbowner 'ARAdmin'
go
use master
go
8. Add the select into option to the created database.

For example:
sp_dboption 'ARSystem','select into',true

go
9. Use the created database.
use ARSystem
go

By default, Sybase does not work with forms that have more than 254 fields. This topic describes how to respond
to error messages that might result from forms with more than 254 fields.
Because some forms have more than 254 fields at installation time, or can be expanded to have more than 254
fields during an integration with another application, you might receive an error message similar to the following
example when installing the application on Sybase:
552 Failure during SQL operation to the database Number of variable length columns
exceeds limit of 254 forallpage locked tables. ALTER TABLE for 'T566' failed
If this happens during an integration, you might also receive a message similar to the following example:
303 Form does not exist on server SIT:Site Group
This occurs when the integration process adds fields to a form (using the ALTER TABLE command) that increase
the number of fields to more than 254. When this happens, Sybase rolls back the change and drops the original
table.
This generates further installation errors because additional dependencies fail to import.
Workaround
Form:NTE:SYS-Group NT Control
Clause: lock datarowsForm:NTE:SYS-NTUnProcessedRecords
Clause: lock datarowsForm:NTE:SYS-NT Process Control
Clause: lock datarowsForm:CHG:Infrastructure Change

Clause: lock datarowsForm:SRM:Request

Clause: lock datarowsForm:SRM:RequestApDetailsSignature
Clause: lock datarowsForm:SRM:RequestInterface
Clause: lock datarowsForm:HPD:Help Desk
Clause: lock datarows
Related topics
error message 552


This topic contains the following material:
Before you begin

To upgrade BMC Remedy AR System 6.3 and later servers with a Unicode database to BMC Remedy AR
System 7.0.01 and later
Upgrading serialized data from version 6.3 (if you have customized applications)
Before you begin

If you are upgrading to a Unicode-enabled BMC Remedy AR System server, you must prepare your host computer
before installing BMC Remedy AR System, and make sure that the database is Unicode-enabled.
BMC supports the following upgrade: You had installed and were running a BMC Remedy AR System 6.x server on
a Unicode database. Now, you want to run a Unicode BMC Remedy AR System 7.x server on the same Unicode
database.
To upgrade BMC Remedy AR System 6.3 and later servers with a Unicode database to BMC
Remedy AR System 7.0.01 and later
1. Back up the database components, objects, forms, and data.

2. On Windows systems, run the installer in the same locale that you ran the original BMC Remedy AR System
server.
For example, if the original server ran in a Japanese locale, run the upgrade installer in the same Japanese
locale.
3. On UNIX systems, run the installer in the Unicode version of the locale in which you ran the original AR
System server.
For example, if the server ran in the ja_JP.eucJP locale, run the installer in the ja_JP.UTF-8 locale. Locale
names vary across UNIX variants and versions.

Upgrading serialized data from version 6.3 (if you have customized applications)
The AR System server stores certain data (such as filter and active link run conditions and table qualifiers) in a
serialized format that embeds character lengths. This data occurs in:
The server's internal tables

Tables managed by BMC Remedy AR System services such as the Approval Server and Assignment Engine
User data
The upgrade process automatically rewrites internal and BMC Remedy AR System service data. If you have this
type of data, you can fix it with the arufix63 utility, which is included with the server installation.
The following qualifier is an example of a serialized format:
...\12\Hello, world\...
This denotes that the Hello, world string occupies 12 bytes.
In the single-byte character encodings used by the 6.3 AR System server, the French string:
âllo, monde
occupies 11 bytes and would be encoded as:
...\11\âllo, monde\...
In the UTF-8 encoding used by the Unicode AR System server, the same string occupies 12 bytes (because each
accented Latin letter requires 2 bytes, rather than 1) and is encoded as:
...\12\âllo, monde\...
to be decoded and used correctly by the system.
In version 7.x and later, the database upgrade program recalculates these lengths so that the new Unicode BMC
Remedy AR System server can read back the serialized data. The installer performs the following actions:
Runs the 6.3-to-7.x database upgrade program, which repairs tables maintained by the AR System server to
store definitions of objects such as forms and active links.
Generates SQL and error logs, and logs the rows that it changes for Unicode repair in a separate file. The
name of this file is at the beginning of the SQL log, in a message. The following example shows the file
name:

See writeMemoLog in /usr/tmp/aaaaa5231
Repairs all length-encoded strings in the BMC Remedy AR System tables. Repairs any tables (such as
arschema) that contain a column called safeGuard, which detects data corruption and whose value is
sensitive to the character encoding.
After the installer starts the server, the installer runs several programs to install localized views for system
forms and to add initial data to the User and Group forms. During this phase, it runs the arufix63 utility to
repair the DSO and Approval Server forms, which store serialized qualifier and assignment strings as normal
column data. The arufix63 utility reads a script in the <ARSystemServerInstallDir>
/arserverconf/arufix63c.txt file to know which tables to repair, and writes error messages to the
<ARSystemServerInstallDir>/Logs/arufix63.log file.
If you have your own applications that store qualifiers or assignments in serialized form, these might also need to
be repaired. To do so, run the arufix63 utility and specify the affected forms, fields, and field types. For more
information, see the arufix63.txt file in the server installation directory.
Note
Run the arufix63 utility only if a user application stores serialized strings (qualifiers and assignments)
owned by BMC Remedy AR System, such as those created by the Application-Parse-Qual-SField
and Application-Parse-Val-SField commands, and only if those strings contain non-ASCII
characters.

13.1.4 Completing the planning spreadsheet for an upgrade

Before you start installing or upgrading the products, you must gather information about the required parameters
that the installer prompts for each product. The planning spreadsheet provided in this section helps you to gather
these parameter values. To avoid installation errors, refer to this spreadsheet when you run the installation.
Note
You must know the actual login credentials to a server or database to complete installations. BMC
installers are not integrated with Atrium Single Sign-On, SSL, or other authentication methods to
authenticate users. For example, you cannot use a smart card scan to authenticate a user to perform
installations of BMC products.

To plan for your installation by using the spreadsheet
1. Download and open the 8.1 planning spreadsheet.

2. Enter your selections and parameter values into the Value column with the help of your DBA or system
administrator.
For example, after installing BMC Remedy AR System server, you use the values that you entered in the
spreadsheet when you install BMC applications.
3. Launch the installer.
4. Copy the parameter values from the spreadsheet and paste them into the product fields in the installer.
Tip
The columns and rows in the Microsoft Excel spreadsheet are formatted so that each sheet prints
cleanly in landscape format.

Downloading the installation files to upgrade
13.1.5 Downloading the installation files to upgrade

For information about obtaining the files that you need for upgrade, see Downloading the installation files.

Preparing your components and applications for an upgrade
13.1.6 Preparing your components and applications for an upgrade

The BMC Remedy AR System suite installer prompts you to enter information about the BMC Remedy AR System
database, which the installer creates during the upgrade. This database contains the BMC Remedy AR System
server forms and field definitions, and also stores workflow data, structures, and permissions.
Note
If you are upgrading both BMC Remedy IT Service Management and BMC Service Management, BMC
recommends that you upgrade BMC Remedy IT Service Management first so that the foundation
components are upgraded only once.

To prepare your system to upgrade the BMC Remedy AR System server and
database
1. Back up your database and file system before you upgrade.

When you are upgrading, back up your data, object definitions, and applications.
2. Review the pre-installation considerations specific to UNIX and Microsoft Windows (for example, setting
environmental variables).
3. Make sure that the server can be resolved to a server alias. If you are installing more than one server on a
computer, make sure that each server has a unique server alias.
4. Determine the ports that you will use.
5. Check if you have installed Microsoft Visual C++ 2008 SP1 Redistributable Package (64-bit).
Note
If Microsoft Visual C++ 2008 SP1 Redistributable Package (64-bit) is not installed, the installer
checks for this version. If this version is not present, the installer installs the required version.
6. Verify that a previous version of the BMC Remedy AR System server is on the machine.
7. Review the following pre-upgrade procedures:

Upgrading with overlays already present
OR
Upgrading without overlays already present
Upgrading tips
Review the following tips before upgrading BMC Remedy AR System.
You can upgrade from version 6.3.00 and later versions only.
To upgrade from a version earlier than 6.3.00, upgrade to 6.3.00 by using the 6.3.00 installer first, then run
the current installer.
If you are upgrading from 6.3.00 or 7.0.01, you must upgrade to 7.1.00 first and then upgrade to 8.1.00.
Before upgrading, back up the existing installation (including the database) in case you need to restore the
original installation.
If you are only upgrading the database, select the fresh installation option.
When you select the Upgrade option, the BMC Remedy AR System server upgrades all the components
such as Approval Server, Assignment Engine, etc. automatically. Make sure that you backup any
customizations that you have made to these components before you select the Upgrade option, else you
will loose the customizations.

Before you upgrade the BMC Remedy AR System server, make sure you have a valid AR Server license, that
is, the BMC Remedy AR System server must be licensed.
If you are upgrading from a version earlier than 7.1.00, export the licenses from your existing BMC Remedy
AR System server before you begin the upgrade process. (If you import the licenses from a different
computer, you might need to provide the BMC Remedy AR System server host ID to obtain the license key.)
When upgrading from a version earlier than 7.5.00, you must provide the same installation directory that
was used in the installation, for example:
If you installed BMC Remedy AR System 7.1.00 in /usr/ar, enter /usr/ar during the upgrade process.
If you installed BMC Remedy AR System 7.1.00 in /usr/ar/<hostName>, enter /usr/ar/<hostName>
during the upgrade process.
(For 64-bit BMC Remedy AR System server on 64-bit operating system) Before upgrading a 32-bit BMC
Remedy AR System server to a 64-bit server, make sure that you install a 64-bit database client on the
same computer where you are upgrading the BMC Remedy AR System server.
If you are upgrading from a 32-bit version to a 64-bit version of BMC Remedy AR System, you have a 32-bit
version of BMC Atrium CMBD Suite. You must also upgrade the BMC Atrium CMDB Suite to the version that
is x64 compatible. (On all platforms except Microsoft Windows, the first 64-bit version was 7.5.00, and
there are no 32-bit versions as of that release. For Windows, the first 64-bit version was 7.6.x, and there are
both 32-bit and 64-bit versions of that and subsequent releases.)
While upgrading the BMC Remedy AR System server, you might receive ARERR 9130. If you do, you can
ignore it. This error occurs when Java 1.5 or 1.6 is used in both the old and new versions of the server.
When you restart the BMC Remedy AR System server after the upgrade is complete, this error message will
not reappear.
To add a 7.5.00 or later BMC Remedy AR System server to an environment in which a 7.1.00 or earlier BMC
Remedy AR System server is already installed, you must first change the value of the
Multiple-ARSystem-Servers option in the 7.1.00 or earlier server's configuration file from F to T. Otherwise,
the 7.5.00 or later server installation will fail. (In UNIX, the configuration file is ar.conf. In Windows, it is
ar.cfg.)
Preparing to upgrade the Approval Server
If you are performing an upgrade, BMC recommends that you perform the following activities to preserve
customizations:
Export your Approval Server customizations to .def and .arx files.
Back up your customizations to Approval Server form views.
Document the Approval Server workflow you have disabled.
When upgrading from version 7.1.00 of the Approval Server on a non-root location, explicitly set the write
permissions to the installation folder so that the definition files are updated successfully.
Preparing to upgrade FTS from a version earlier than 7.6.03

If you are upgrading the Full Text Search (FTS) feature from a version earlier than 7.6.03, complete the following
steps.
1.
1. Back up existing directories and files before removing them.

2. Uninstall the Open Text or Hummingbird SearchServer software if it was installed as part of the previous
BMC Remedy AR System FTS installation.
3. Select the FTS feature when you upgrade BMC Remedy AR System.
4. Delete the following directories if they are not used with other programs:
collection
conf
temp (versions 7.1.00 and 7.0.01 only)
By default, these directories are installed in the BMC Remedy AR System server location, and they are
deleted when you uninstall SearchServer. If you created these directories in another location, you
must delete them manually.
5. To generate full text indexes in the new format, perform a re-index operation. (Select the Reindex check
box on the FTS tab of the Server Information form.)
Tip
Be aware that re-indexing can take a long time and might impact other operations, so avoid re-indexing
at peak hours.
Making sure you have enough transactional log space for an upgrade
Before upgrading, you need to make sure you have enough transactional log space for the upgrade. During the
upgrade, production dataset record data is copied from the BMC Atrium CMDB BMC.CORE:BMC_BaseElement
form to a new AST:Attributes form. Because of this, make sure you have enough transactional log space as
outlined in the following procedure.
Note
Data update jobs are run for all applications, so complete the following procedure even if you do not
plan to use the multi-tenancy feature.
To make sure you have enough transactional log space for an upgrade
1. Determine the largest BMC Remedy AR System database table based on the application forms on your
system.
2. Calculate the transaction log space required to support the largest table (plus a 20% buffer), and make sure
you have sufficient space before starting the upgrade.
Use the new value to set the size of the database transaction log or undo tablespace. (Hint: Update the
UNDOTBLSP setting.)

13.2 Upgrading with overlays already present

This topic describes the basic steps required to upgrade BMC Remedy AR System, BMC Atrium Core, and other
BMC products with overlays already present. This is a four-stage upgrade if you have previously installed BMC
Remedy AR System 7.6.04 and have already implemented overlays.
Important
If you are upgrading from pre-7.6.04 versions of BMC Remedy AR System to version 8.1, first take
a backup of the customizations (system forms of Approval Server, Assignment Engine, Email
Engine, and Flashboards), upgrade to version 8.1, and then manually add the customizations for
version 8.1.
Before beginning your upgrade, review the Planning topics. To understand the difference
between the two upgrade paths, see Planning to upgrade BMC Remedy AR System.
To upgrade the AR System server in a directory that already has the ar.conf file, select the Upgrade
option, else select the Install option. If you select the Upgrade option, the installation program
skips some of the server installation screens and refers to the configuration values in the ar.conf
file.
13.2.1 Prepare to upgrade

Step Task
Note

a. Review the the hardware requirements for your computer platform.
3 Prepare your database before you start the upgrade.
Warning
Back up the BMC Remedy AR System database. This enables you to restore BMC Remedy AR System to its pre-installation state if you
encounter problems.

Step Task
6 Prepare your components and applications for an upgrade.
7 Review Understanding how upgrading with overlays works, including the subsections. This information will help you understand the
importance of overlays during the upgrade process.
13.2.2 Complete the upgrade stages

Step Task
8 Complete Stage 1 - Setting up a staging server for upgrades with overlays already present if you need to set up a staging server.
9 Complete Stage 2 - Upgrade AR System server with overlays present.
10 Complete Stage 3 - Upgrade applications and adjust customizations with overlays present.
11 Complete Stage 4 - Test and promote staging server with overlays to production.
13.2.3 Migrate your data

Step Task
12 Migrate your data using the Delta Data Migration utility. (This is documented in the BMC Remedy IT Service Management documentation.)
13.2.4 Understanding how upgrading with overlays works
Note
If you are performing an in-place-upgrade without using a staging server, perform all of the stages and
steps listed in this section, but skip the staging server setup. Whenever the documentation refers to the
staging server (or StagingServer), use your production or development server instead. The rest of the
in-place-upgrade process is the same as the staged-upgrade process.
This is a four-stage upgrade BMC Remedy AR System and BMC Remedy ITSM Suite for customers who have
previously installed AR System 7.6.04 and have already implemented overlays. 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.
BMC recommends that you back up your staging server database before performing each stage of the upgrade
process. BMC also recommends that you run a database consistency check after each stage.

Stage 1 - 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. There are two possible ways to set this up:
Accelerated staging server setup

Duplicated staging server setup
Stage 2 - Upgrade AR System server

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 stage 2, you can upgrade and run your applications, or install new applications. If you
lost.
Stage 3 - Upgrade applications and adjust customizations

Upgrade all of your applications and AR System components to version 8.1. 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 stage 3, 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.
Stage 4 - Test and promote staging server to production

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
Planning to upgrade BMC Remedy AR System
Running the database consistency checker

The role of overlays in an upgrade
The role of overlays in an upgrade

In BMC Remedy Action Request System version 7.6.04, the overlays feature was introduced to preserve
application customizations during the upgrade process. During an upgrade, the upgrade installers ignore
application overlays and change only the objects that were originally installed with the application or server. After
the upgrade, the application or server continues to use the overlays instead of the origin objects for runtime
operations so that the customizations are preserved.

The following terms are used in the upgrade process:
Term Definition
Custom A customer-created object that is not distributed by BMC.

object
Origin An original, unmodified object that is included with a released BMC product.
object
Overlaid An origin object that has an overlay associated with it.

object
Overlay A customized version of an origin object that is used in place of the origin object. In this case, the origin object becomes an overlaid
object object.
Staged A method that makes use of a staging server, which eventually becomes the new production server. This method has the least amount
upgrade of server downtime when completing the upgrade.
Related topics

Servers used in the staged upgrade process with overlays
Servers used in the staged upgrade process with overlays
Note
in-place-upgrade process is exactly the same as the staged-upgrade process.
The staged-upgrade process allows you to upgrade your application and create overlays or otherwise address
pre-existing customizations to your BMC Remedy AR System server objects while your production server remains
available to users. The following diagram shows the set of servers that might be required to perform the upgrade.

The server listed on the right side of the diagram at the top is a staging server for staged upgrades. Completing
the optional upgrade stages 3, 4, and 5 requires a reference server, and might require another server (referred to
as the upgrade comparison server) to host upgraded applications. These additional servers do not have to be
production quality, but they must have compatible software and a compatible database to hold referenced copies
of the BMC software and database objects. The reference server and upgrade comparison server are temporary
servers and are not needed after the entire upgrade process is complete.

Required tools for upgrades with overlays
Required tools for upgrades with overlays

If you are upgrading BMC Remedy AR System, familiarize yourself with the following BMC tools to help accelerate
the upgrade process.
The following tools are required if overlays are not implemented in your system:
Best Practices Conversion Utility (BPCU) — The BPCU helps identify platform and application
customizations and convert them to overlays.
BMC Remedy Migrator tool — The BMC Remedy Migrator tool helps you synchronize data among your AR
System development, staging, and production systems.
The following tool is needed to perform the staged-upgrade, whether or not overlays are implemented:
Delta Data Migration tool — The Delta Data Migration tool allows you to upload the data that changed on a
production server during the time that a staging server was being upgraded.
The following tool is required for all upgrades:
BMC Remedy Developer Studio — BMC Remedy Developer Studio is an integrated development
environment (IDE) for BMC Remedy AR System applications.
Note

The upgrade process described here uses the BPCU and the BMC Remedy Migrator tool in working with
overlays and custom objects. If you are very familiar with your application, you can use BMC Remedy
Developer Studio to accomplish the same tasks.
Related topics
Creating overlays with the Best Practice Conversion Utility
Application development with BMC Remedy Developer Studio
Migrating delta data after an upgrade in the IT Service Management documentation

Review Stage 1 - Setting up a staging server for upgrades with overlays already present to understand if you need
to set up a staging server.
13.2.5 Stage 1 - Setting up a staging server for upgrades with overlays

already present
The following topics explain the implementation of staging environment for upgrade:
The following topics provide the steps for setting up a staging server for upgrade:
Note
If you are performing upgrade without using a staging server, skip the staging server setup stage.
Whenever the documentation refers to the staging server (or StagingServer), use the production or
development server instead. The rest of the upgrade process is the same as the staged-upgrade process.
Understanding staging environment implementation for upgrade

available to users. The following illustrations shows the set of servers that might be required to perform the
upgrade.

Understanding staging server implementation

For setting up a staging environment, you can use one of the following method:
Accelerated Staging server: You need copy the production server database to the staging server > Upgrade
See, Setting up accelerated staging server for upgrades with overlays.
Duplicated Staging server: You need to duplicate the production server > Copy the production server
database to the staging server > Upgrade BMC Remedy AR System.
See, Setting up duplicated staging server for upgrades with overlays.
When upgrading using staging server, consider the following:
Whether you use the accelerated staging server setup or the duplicated staging server setup, you must
copy your entire production database to the staging server.
At the end of the process, the staging server becomes the new production server.
Make sure that the staging server you will use, meets the specifications required for the upgrade. See,
System requirements.

When you create the staging server, use the same server name to avoid naming issues when you promote the
staging server to production. If you change the name, follow the process outlined in Changing a server name
when using a duplicated or migrated environment. Also, if you are using the same server name, you need to be
careful that the users are not pointed to the staging server during the upgrade process.
Understanding reference server implementation

If you are implementing the reference environment, you might require another server (referred to as the upgrade
comparison server) to host upgraded applications. These additional servers do not have to be production quality,
but they must have compatible software and a compatible database to hold referenced copies of the BMC
software and database objects. The reference server and upgrade comparison server are temporary servers and
are not needed after the entire upgrade process is complete.
Accelerated staging server setup for upgrades with overlays

Accelerated staging server method is also referred to as DB only upgrade. When upgrading using accelerated
staging server, you only need to create a copy of the production server database in the staging environment. The
AR System server installation then must be done on the staging server against the copy of the production server
database.
You can use this method only if you are upgrading all of the products installed on your server, or if you do not
have BMC Service Impact Manager, Integration for BMC Remedy Service Desk, or BMC ProactiveNet Performance
Management installed on your production system.
To set up the accelerated staging sever for upgrade with overlays

The following diagram and the steps explain how you can set up an accelerated staging server.

1. Take a backup of the production database.

2. Restore the production database copy on the staging database. See, Duplicating the production server
database backup for upgrades with overlays.
3. Review the restrictions after restoring the database on the staging server with overlays. See, Restrictions
after restoring the database on the staging server with overlays.
4. Upgrade the AR System server. You must run the installer in Install mode such that, the AR System server is
upgraded and not installed fresh.
To ensure that the AR System server is upgraded and is not installed fresh, Database Name, Database User,
and Database Password must be same as the production server.
Database Host Name, and Database Port must point to the new database i.e. staging database.
5. Proceed with next stages.
Duplicated staging server setup for upgrades with overlays

To create a duplicated staging server, you need to create an exact duplicate of your production server, including
installing the AR System server and all of the ITSM applications and components, as well as any other applications
such as BMC Service Impact Manager, Integration for BMC Remedy Service Desk, or BMC ProactiveNet

Performance Management before starting the upgrade. If you set up the staging server this way, you can test your
system after each upgrade step, because you have a working system at the end of each stage. You can also test
the system after upgrading each ITSM application and its components.
To set up duplicated staging environment for upgrades with overlays

1. On the staging server, duplicate the installations as on the production server. See, Duplicating the
production server installations for upgrades with overlays.
database for upgrades with overlays.
5. Upgrade the AR System server. You must run the installer in Upgrade mode.
Duplicating the production server installations for upgrades with overlays

This page has not been approved for publication.

Duplicating the production server database for upgrades with overlays

The following topics provide instructions for copying the backup of the current production server database
schema and data to the new staging server and duplicating it on the staging server:
To duplicate the production database backup on the accelerated staging server
1. Work with your database administrator responsible for the production environment to create a full backup
of the current production BMC Remedy AR System database.
Note
The date and time of the backup for future reference. You will use this information in the delta
data migration step to determine which data needs to be migrated to the staging server at the end
of the upgrade process.
2. Work with the database administrator responsible for the production environment to restore the database
onto the staging server database.
3. If you are running SQL Server, run the following command in your database:
sp_changedbowner "ARAdmin"
Substitute ARAdmin with the appropriate BMC Remedy AR Database Administrator Account.
To duplicate the production database backup on the duplicated staging server
1. On the staging server, shut down AR System server.

Substitute ARAdmin with the appropriate BMC Remedy AR Database Administrator Account
4. Change the AR System server name to match the new host. For more information, see Changing a server
name when using a duplicated or migrated environment.
5. Restart the BMC Remedy AR System server and verify that the system is functional.
6. Work with the database administrator responsible for the production environment to back up the staging
server database.
7. Run the AR System database consistency checker. For more information, see Running the database
consistency checker.
8. Run the health check in the BMC Atrium Core maintenance tool to verify that your system is running
correctly before the upgrade. For more information, see Getting started with BMC Atrium Core
Maintenance Tool.

Note
The CMDB health check was introduced in version 7.5. If your staging server runs an earlier
version, you can skip this step.
a. Launch the BMC Atrium Core Maintenance Tool:

On Microsoft Windows, go to the <AtriumCoreInstallDir>\atriumcore folder, and double-click
theAtriumCoreMaintenanceTool.cmd file.
On UNIX, go to the <AtriumCoreInstallDir>/atriumcore/ directory, and launch the
AtriumCoreMaintenanceTool.sh file.
a. Click the Health Check tab, and follow the instructions there.
Restrictions after restoring the database on the staging server with overlays
Warning
Do not perform the following activities in your production server until the upgrade and delta data
migration are completed successfully.
Tasks that should not be performed after backup
Product Restrictions
BMC Remedy AR System Do not create or modify any objects, including:

(General)
Forms
Workflow
Fields
BMC Atrium Core (all versions) Do not:
Create or modify classes

Create or modify any federation sources
BMC Service Level Management Do not:
Create, modify, or delete contracts, agreements and the data source section of configuration data
Make changes to any collector related configuration data
BMC Remedy ITSM Suite (when Do not create or update any of the following contracts:
upgrading from 7.0.3 to higher
versions) Support
Warranty
Lease
Maintenance
Software License

License Management Exceptions
Do not create or update any of the following forms:

APR:Approver Lookup (approval mappings)
APR:SYS-Approval Definition (approval process definition)
BMC Service Request Do not:

Management
Make changes to any of the BMC Service Request Management configurations in the Application
Administration Console, including changes to categories, approval mappings, or entitlements.
Create or modify approval chains for service requests.
Make changes to the Request Catalog entries including service request definitions, process definition
templates and application object templates.
If you are upgrading BMC Service Request Management from a 2.2 version to a 7.6.02 or earlier
version, then all service requests in the Waiting Approval state must be approved or rejected
before you run the Delta Data Migration tool.
Field Customizations
If any custom field or selection values are added to an out-of-the box or custom field on the production server
after the database is copied to the staging server (delta period), then those changes must also be manually
applied on the staging server. If that is not done, then records with values on those fields will not migrate and you
will see an error similar this:
10/17/2011 23:14:12 2336 *ERROR* Migrations 23:14:12 : [4]-[306]-[Value does not fall within th
13.2.6 Stage 2 - Upgrade AR System server with overlays present

Completing stage 2 produces an upgraded BMC Remedy AR System server with your current applications and
data. This enables you to upgrade the other applications and AR System components in subsequent stages.
The following diagram shows the components that are upgraded in stage 2 (in green).

To upgrade the AR System server

Select the Install option in the installation program if you are using the accelerated upgrade method to upgrade
the primary server in a directory where the previous ar.conf file is not present. During the installation process, the
installation program then displays a screen to confirm whether the database upgrade can be continued. Select
Yes to continue the installation procedure.
To upgrade BMC Remedy Mid Tier

Install the latest version of BMC Remedy Mid Tier on the identified mid tier host.
Note
If you are using locales other than English, select the target locales when upgrading each product.
After each product is upgraded:
1. Examine the installation logs to validate that upgrade was successful for each application.
2. Ensure that the Share Application properties are updated successfully.
Related topics
Accelerated staging server setup for upgrades with overlays

Upgrading AR System with overlays
Upgrading AR System with overlays

The BMC Remedy AR System installer enables you to upgrade BMC products in your IT environment.
In this topic:
Choosing products
To upgrade BMC Remedy AR System
The suite installer guides you step-by-step through the upgrade process. When you start the installer, you can
choose one or more features to upgrade at one time. Because certain applications depend on a specific set of
features, you need to run the installer multiple times to upgrade all of the features in the solution. For example,
you first upgrade the AR System server on one computer and then run the installer a second time to upgrade the
mid tier on a different computer.
Recommendations
Complete the planning spreadsheet before you start the upgrade.

(WAN).
System server.
Choosing products
Engine, and Flashboards.
AR System Mid-Tier — Installs the Mid Tier only.
AR System Clients — BMC Developer Studio (and the Localization Toolkit), BMC Remedy Data Import, and
BMC Atrium Integrator Spoon.
The Clients option is Windows only; it is not available for Linux or UNIX.
Mininum set of features when installing BMC products

BMC Application AR System features to choose
BMC Atrium Core

AR System Server
Approval Server
Assignment Engine
BMC ITSM
AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine
DVD.
a. To upgrade the AR System server in a directory that already has the ar.conf file, select the Upgrade
option, else select the Install option. If you select the Upgrade option, the installation program skips
some of the server installation screens and refers to the configuration values in the ar.conf file.
b. Select specific products to upgrade.
For example, select AR System Servers.
c. (optional) Add a new language.
You can later select additional localized views to install.
d.
d. Navigate to the directory in which you want to install the BMC Remedy AR System application.
The default locations are C:\Program Files\BMC Software\ARSystem and /opt/bmc/ARSystem (UNIX
and Linux).
e. Click Next.
The installer validates your system resources.
8. Use the planning spreadsheet to enter the correct values in the AR System Server User and Database
Information pane, and then click Next.
9. Enter the correct JRE path, and then click Next.
preview panel appears, listing the product and product features that will be upgrade.
Note
10. Click Next.

14. Re-configure Full Text Search.
The installer disables FTS during the upgrade. Do not enable FTS until you re-configure it.
15. Convert your existing overlays into granular overlays through the Object Granularity Level option.
System server.
2. Open the ARSuiteKitWindow folder.
4. Start the installer and double-click setup.cmd.
a. Select Upgrade.
b. Navigate to the directory in which you want to install the Mid Tier.
and Linux).
c.
6.
c. Select AR System Mid-Tier.

d. Click Next.
8. Enter the values from the planning spreadsheet for the Mid Tier.
9. Click Next.
).
15. Log out.
16. (optional) Restart the Mid Tier web service.
Related topics

Configuring full text search
Granular overlays
Adjusting customizations when upgrading

Stage 3 - Upgrade applications and adjust customizations with overlays present
Adjusting customizations when upgrading

When you upgrade the AR System server, BMC Software highly recommends that you adjust your customizations
and assign the appropriate overlay type to the objects' granular sections before proceeding with the BMC
Remedy AR System application upgrade.
Developer Studio provides two utilities to help you:
Object Granularity Level — Helps you to easily identify the overlay objects and the customizations made to
them. Use this utility to identify and adjust your existing (version 8.0 and earlier of BMC Remedy AR System)

customizations to adopt the overlay behavior in version 8.1 and later. For information about the overlays
for granular sections of an AR System object, see Granular overlays.
Use the Object Granularity Level utility after you upgrade the AR System server and before you reconcile
the existing customizations. After your confirmation, the appropriate overlay type is applied to the granular
sections of the selected overlay objects.
Warning
To use this utility, you must have the original unmodified origin objects on your server. If you have only
run the BPCU and have not replaced your origin objects, the Object Granularity Level option will convert
all of your granular components to “No Overlay.” This means your changes will not be protected and will
be lost in a subsequent upgrade that changes your origin objects.
The utility compares overlay objects to origin objects to determine what has changed. If it detects no
changes in a granular component, the utility offers to convert the component to “No Overlay.”
This will cause a problem if an origin object has been customized and is the same as its overlay object,
because the overlay will be converted to “No Overlay” and will just expose the origin object. The
changes will still be present because they are in the origin object.
However, a subsequent upgrade that replaces the origin object will remove the customizations because
they are not captured in the overlay.
For information about fixing existing customizations, see To adjust the object overlay type.
Unmodified Fields in View — Identifies and removes unmodified fields from a view overlay. For a selected
form, the Unmodified Fields in View utility lists the unmodified fields that are added to the form's view
overlay. You can remove these fields from the overlay of a single view or multiple views where the field is
present. The unmodified fields removed from the view overlay inherit the base properties. The fields that
are added to the view overlay continue to retain their customizations.
See To fix form view overlays.
To adjust the object overlay type

Perform the following steps after you upgrade the AR System server:
1. Open Developer Studio in the Best Practice Customization mode.

For information about changing the development mode, see Changing the development mode.
2. Open the object list and select the overlay object for which you need to fix customizations. You can select
multiple objects to analyze.
3.
3. From the object's context menu, select the Analyze Overlay > Object Granularity Level option.
Analyze Overlay options
A report, similar to the following figure, is displayed in the Analyzer Results tab:
Analyzer Results tab
The Analyzer Results tab provides details about the granular components that are overlaid in each selected
object and the overlay type that it maps to for version 8.1 and later of BMC Remedy AR System.
For each overlay object, an entry shows the current and new granular section values:

Current — Displays the current granularity level for the granular component. For example, the
default value set the first time.
New— Displays the analyzed granularity level for the granular component.
Note
If the current and new values are the same, then they are not listed in the results.
4. Select the customization to be set.

5. From the object's context menu, click the Fix Object Granularity Level option.
Fix Object Granularity Level option
Developer Studio applies the appropriate overlay type to all granular components of the selected object.
The status of completion is indicated in the Progress tab.
Progress tab
Any errors or exceptions are reported as Not Completed and logged.

After you complete the process, you can continue with the remaining reconciliation steps.
To fix form view overlays
1. Open Developer Studio in the Best Practice Customization mode.

For information about changing the development mode, see Changing the development mode.
2. Open the appropriate object list.
3.
3. Select the form for which the form view customizations need adjustments.
4. From the form's context menu, select the Analyze Overlay > Unmodified Fields in View option.
Unmodified Fields in View option
All fields that are added to the form's view overlay (single view and multiple view) are listed in the Analyzer
Results tab of the form editor.
5. Right-click the field, and select one of the following options:

Fix Fields in Current View — Fixes the selected field for the view to which the field belongs. The
current view is the view to which the field belongs.

5.
Fix All Fields in All Views — Fixes all of the fields listed in the Analyzer Results View for their
respective views.
The fields that you remove from the view overlay inherit the base properties.
The following figure shows how the results of the analysis — Unmodified Fields in Overlay — are
displayed. The name of the view to which the fields belongs is now part of the message.
13.2.7 Stage 3 - Upgrade applications and adjust customizations with

overlays present
When you upgrade applications or system components, some objects that you have overlaid might be deleted,
which means that your overlay is deleted as well. To preserve any such overlays, you must create a copy of your
current staging server. This copy is called the upgrade comparison server (UpgradeComparisonServer).
Similarly, some of your customizations might interfere with upgraded behavior. You must adjust these
customizations before using the application.
This figure shows the components that are upgraded in stage 3 (in green).

To upgrade applications and adjust customizations
1. Create an upgrade comparison server (UpgradeComparisonServer).
a. On the system that you are going to use as the upgrade comparison server, install BMC Remedy AR
System.
b. Create a copy of the StagingServer database, which is already at the latest version.
c. Restore the copy of the StagingServer database over the existing database on
UpgradeComparisonServer.
2. On StagingServer, upgrade the applications (BMC Atrium CMDB, BMC Remedy ITSM, and so on).
This might modify and possibly delete some of your overlaid objects. Modifications to these objects
performed by the upgrade do not affect your overlays and custom objects, but deletions do.
Tip
Use the Microsoft Excel planning spreadsheet to help you installing these BMC products.

3. Review the upgraded functionality, and restore deleted objects (if necessary).
Normally, an overlay that is deleted should not be replaced by a custom object because it will not be used
by the upgraded application. If you have overlaid objects you want to preserve, you can save them as
custom objects. If any of your customizations were deleted during the upgrade of StagingServer, use
Developer Studio to restore them by creating custom objects on StagingServer by using the overlays still
present on UpgradeComparisonServer.
Note
A custom field on a deleted form is not preserved because there is no form to contain the field.
Perform steps a and b below to create custom objects for any overlaid objects that were deleted during the
upgrade but that you want to preserve.
a. Compare the overlaid objects on StagingServer against the same objects on
Note
Ensure that you have set your BMC Remedy Migrator configuration options before
performing the following procedures.
i. In BMC Remedy Migrator, choose Tools > Options.

ii. In the BMC Remedy Migrator Options dialog box, expand Differences and select Display.
iii. Select the Display all missing objects option, and make sure that all the other options are
deselected.
iv. Open a new server window for StagingServer.
v. In the navigation pane, click StagingServer to list all the objects on this server.
vi. Sort the object list on the Customization Type column, and select all objects with the value
Overlay or Custom.
vii. Right-click and select Differences > UpgradeComparisonServer.
BMC Remedy Migrator generates a difference report.
b. For every overlaid object that exists on UpgradeComparisonServer, but not on StagingServer, decide
whether you need the object. If you need it, use BMC Remedy Developer Studio to duplicate the
overlay manually by saving it as a custom object on StagingServer.
4. If you have overlaid objects that were changed during the upgrade, examine your overlays and add the
functionality that was added to the overlaid objects, or remove overlays containing customizations that
you no longer want.
Removing an overlay exposes the upgraded object's functionality. To examine the overlays, compare each
upgraded origin object that is overlaid on StagingServer to the same origin object on
UpgradeComparisonServer, and compare each overlay and its overlaid origin object. You can then adjust

the overlay to achieve the behavior that you want.

Perform the needed comparisons as follows:
a. Enable the required masking options if you have not already done so in stage 4.
b. Use BMC Remedy Migrator to compare overlaid objects on StagingServer and
UpgradeComparisonServer to identify which objects were changed and what changes BMC made
between the versions, as follows:
i. Open a new server window for StagingServer.
ii. In the navigation pane, click StagingServer to display all the objects on this server.
iii. Sort the object list on the Customization Type column, and select all objects with the value
Overlaid.
iv. Right-click and select Differences > UpgradeComparisonServer.
BMC Remedy Migrator generates a differences report.
The differences report provides a list of objects that have changed.
c. Keep this first instance of BMC Remedy Migrator open to examine objects in this report.
d. Use a second instance of BMC Remedy Migrator to compare overlays to overlaid objects on
UpgradeComparisonServer:
Note
You need to have BMC Remedy Migrator installed on a different computer to do this
because you can only run one instance of Migrator on a single system.
i. Open a new instance of BMC Remedy Migrator.

ii. Open a new server window for UpgradeComparisonServer.
iii. In the navigation pane, click nameOfUpgradeComparisonServer to display all the objects on
this server.
iv. Sort the object list on the Customization Type column and select objects (in the previously
created list) with the value Overlay in this column.
v. Right-click and choose Differences > UpgradeComparisonServer.

vi. In the Source-Destination Mapping window, click Map Overlay To Base to populate the
Destination Object Name column with the corresponding overlaid object for each overlay
object.
vii. Click OK to generate the difference report.

e. For each object in the difference report from step 4b, use the first Migrator instance to identify
differences resulting from the upgrade. Use the second instance to see differences between the
overlay and the overlaid object.
f. Based on these differences, use BMC Remedy Developer Studio to delete the overlay or modify it on
StagingServer:
If you want to use the new features in the latest release, delete the overlay.
If you want to retain the customizations in your current production system when you upgrade
to the latest release, merge the differences from the origin object into its overlay.

Related topics

Setting BMC Migrator options before migration
Using BPCU to generate difference reports
Comparing overlays to overlaid objects on the same server

Stage 4 - Test and promote staging server (with overlays) to production
13.2.8 Stage 4 - Test and promote staging server with overlays to

production
Performing the steps in stage 4 promotes your staging server to an upgraded production server. Validate the
upgrade on the staging server with user acceptance testing (UAT).
To validate the staging server with UAT
1. Make a backup of the upgraded staging server database.

This backup is called the pre-UAT backup.
2. Conduct your UAT using your test cases.
3. If an issue arises:
a. Identify a solution, or work with BMC Support to identify a solution.
b. Apply any fixes to the server, and then validate the fixes.
c. Make a copy of the fixes for use later.
4. Complete all UAT tasks and obtain sign-off.
5. Revert to the pre-UAT backup.
6. Apply any fixes that were required during UAT.
7. Work with the database administrator responsible for the staging server to back up the database.
This backup is called the UAT-Verified-Clean backup.
8. If desired, run an additional test to validate that fixes have been applied correctly.
Note
If no issues arise, the pre-UAT backup becomes the UAT-Verified-Clean backup.
9. Restore the staging server to the UAT-Verified-Clean backup.

After the upgrade is validated on the staging server, restore the system to the UAT-Verified-Clean backup.
This ensures that any testing data used during the validation is removed and that the staging server is in a
clean state for the delta data migration.
10.
10. Prepare the destination server for delta data migration.

After the upgrade is complete and customizations are re-applied, the environment is ready for delta data
migration.

Migrating delta data after an upgrade
13.2.9 Setting up a staging server for upgrades with overlays already present
(new)
Duplicating the production server database backup for upgrades with overlays (new)
Restrictions after restoring the database on the staging server with overlays (new)
Setting up accelerated staging server for upgrades with overlays

Setting up duplicated staging server for upgrades with overlays

Duplicating production server installations on staging server

13.3 Upgrading without overlays already present

This topic describes the basic steps required to upgrade BMC Remedy AR System, BMC Atrium Core, and other
BMC products without overlays already present. This is an upgrade for customers who do not already have
overlays implemented and want to keep all customizations.
Important
Before beginning your installation, review the Planning topics. To understand the difference
between the two upgrade paths, see Planning to upgrade BMC Remedy AR System.
option, else select the Install option. If you select the Upgrade option, the installation program

skips some of the server installation screens and refers to the configuration values in the ar.conf
file.
13.3.1 Prepare to upgrade

Step Task
Note

a. Review the the hardware requirements for your computer platform.
3 Prepare your database before you start the upgrade.
Warning
Back up the BMC Remedy AR System database. This enables you to restore BMC Remedy AR System to its pre-installation state if you
encounter problems.
6 Prepare your components and applications for an upgrade.
7 Review Understanding how upgrading without overlays works, including the subsections. This information will help you understand the
importance of overlays during the upgrade process.
13.3.2 Complete the upgrade stages

Step Task
8 Complete Stage 1 - Setting up a staging server for upgrades without overlays if you need to set up a staging server.
9 Review Stage 2 - Upgrade AR System server without overlays present and then upgrade BMC Remedy AR System.
Note
Choose Upgrade in the installation wizard.

Step Task
10 Review Stage 3 - Create overlays for existing customizations.
11 Review Stage 4 - Acquire origin objects: optional.
12 Review Stage 5 - Restore origin objects to the staging server: optional.
13 Review Stage 6 - Minimize overlays: optional.
14 Review Stage 7 - Upgrade applications and adjust customizations with new overlays.
15 Review Stage 8 - Test and promote staging server to production with new overlays.
13.3.3 Migrate your data

Step Task
16 Migrate your data using the Delta Data Migration utility. (This is documented in the BMC Remedy IT Service Management documentation.)
13.3.4 Understanding how upgrading without overlays works
Note
in-place-upgrade process is the same as the staged-upgrade process.
This upgrade process is an eight-stage upgrade for customers who do not already have overlays implemented
and want to keep all their customizations. It includes a one-time conversion to overlays.
Note
Customers have not previously installed BMC Remedy AR System 7.6.04 or 7.6.04 SP1/SP2 and have not
already implemented overlays.
When upgrading from a previous release that was customized without overlays, you will perform stages 3
through 6 once. If you already captured customizations in overlays, you need not perform stages 3 through 6.
BMC recommends that you back up your staging server database before performing each stage of the upgrade
process. BMC also recommends that you run a database consistency check after each stage.

Stage 1 - 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. There are two possible ways to set this up:
Accelerated staging server setup

Duplicated staging server setup
Stage 2 - Upgrade AR System server

In stage 2, upgrade the AR System server to 8.1. This stage must be performed before you can upgrade to newer
versions of any BMC applications or other platform components.
After completing stage 2, you can upgrade and run your applications, or install new applications. If you
lost.
Stage 3 - Create overlays for existing customizations (optional but recommended)

In stage 3, 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 stage 3, all customizations are captured in overlays and custom objects. This includes AR System
customizations as well as all other applications and components.
Stage 4 - Acquire origin objects (optional)

In stage 4, which is optional, acquire unmodified origin objects onto a reference server. The origin objects are
used to compare with your overlay objects.
After completing stage 4, 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.
Stage 5 - Restore origin objects on staging server (optional)

In stage 5, which is optional, move the 8.1 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 stage 5, you have acquired copies of all of your origin objects in their original state. This does
not affect any overlays that you created.
Stage 6 - Minimize overlays (optional)

In stage 6, 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 stage 6, you have removed any unnecessary overlays on your system.
Stage 7 - Upgrade applications and adjust customizations

In stage 7, upgrade all of your applications and AR System components to version 8.1. 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 stage 7, 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.
Stage 8 - Test and promote staging server to production

In stage 8, test and promote the staging server to production. Copy all modified data on your current production
system to the staging server by using the Delta Data Migration tool. Promote the staging server to be the new
production server.
Related topics
Running the database consistency checker

The role of overlays in an upgrade (without overlays)
The role of overlays in an upgrade without existing overlays

In BMC Remedy Action Request System version 7.6.04, the overlays feature was introduced to preserve
application customizations during the upgrade process. During an upgrade, the upgrade installers ignore
application overlays and change only the objects that were originally installed with the application or server. After
the upgrade, the application or server continues to use the overlays instead of the origin objects for runtime
operations so that the customizations are preserved.
The following terms are used in the upgrade process:

Term Definition
Custom A customer-created object that is not distributed by BMC.

object
Origin An original, unmodified object that is included with a released BMC product.
object
Overlaid An origin object that has an overlay associated with it.

object
Overlay A customized version of an origin object that is used in place of the origin object. In this case, the origin object becomes an overlaid
object object.
Staged A method that makes use of a staging server, which eventually becomes the new production server. This method has the least amount
upgrade of server downtime when completing the upgrade.
Related topics

Servers used in the staged upgrade process without overlays
Servers used in the staged upgrade process without overlays
Note
in-place-upgrade process is exactly the same as the staged-upgrade process.
available to users. The following diagram shows the set of servers that might be required to perform the upgrade.

The server listed on the right side of the diagram at the top is a staging server for staged upgrades. Completing
the optional upgrade stages 3, 4, and 5 requires a reference server, and might require another server (referred to
as the upgrade comparison server) to host upgraded applications. These additional servers do not have to be
production quality, but they must have compatible software and a compatible database to hold referenced copies
of the BMC software and database objects. The reference server and upgrade comparison server are temporary
servers and are not needed after the entire upgrade process is complete.

Required tools for upgrades without overlays
Required tools for upgrades without overlays

Note

Related topics
Application development with BMC Remedy Developer Studio
Migrating delta data after an upgrade in the IT Service Management documentation

Review Stage 1 - Setting up a staging server for upgrades without overlays to understand if you need to set up a
staging server.
13.3.5 Stage 1 - Setting up a staging server for upgrades without overlays

The following topics explain the implementation of staging environment for upgrade:
The following topics provide the steps for setting up a staging server for upgrade:
Note
If you are performing upgrade without using a staging server, skip the staging server setup stage.
Whenever the documentation refers to the staging server (or StagingServer), use the production or
development server instead. The rest of the upgrade process is the same as the staged-upgrade process.
Understanding staging environment implementation for upgrade

available to users. The following illustrations shows the set of servers that might be required to perform the
upgrade.

Understanding staging server implementation

For setting up a staging environment, you can use one of the following method:
Accelerated Staging server: You need copy the production server database to the staging server > Upgrade
See, Setting up accelerated staging server for upgrades without overlays.
Duplicated Staging server: You need to duplicate the production server > Copy the production server
database to the staging server > Upgrade BMC Remedy AR System.
See, Setting up duplicated staging server for upgrades without overlays.
When upgrading using staging server, consider the following:
Whether you use the accelerated staging server setup or the duplicated staging server setup, you must
copy your entire production database to the staging server.
At the end of the process, the staging server becomes the new production server.
Make sure that the staging server you will use, meets the specifications required for the upgrade. See,
System requirements.

When you create the staging server, use the same server name to avoid naming issues when you promote the
staging server to production. If you change the name, follow the process outlined in Changing a server name
when using a duplicated or migrated environment. Also, if you are using the same server name, you need to be
careful that the users are not pointed to the staging server during the upgrade process.
Understanding reference server implementation

If you are implementing the reference environment, you might require another server (referred to as the upgrade
comparison server) to host upgraded applications. These additional servers do not have to be production quality,
but they must have compatible software and a compatible database to hold referenced copies of the BMC
software and database objects. The reference server and upgrade comparison server are temporary servers and
are not needed after the entire upgrade process is complete.

Stage 2 - Upgrade AR System server without overlays present
Restrictions after restoring the database on the staging server without overlays
Warning
Do not perform the following activities in your production server until the upgrade and delta data
migration are completed successfully.
Tasks that should not be performed after backup
BMC Remedy AR System Do not create or modify any objects, including:

(General)
Forms
Workflow
Fields
BMC Atrium Core (all versions) Do not:
Create or modify classes

Create or modify any federation sources
BMC Service Level Management Do not:
Create, modify, or delete contracts, agreements and the data source section of configuration data
Make changes to any collector related configuration data
BMC Remedy ITSM Suite (when Do not create or update any of the following contracts:
upgrading from 7.0.3 to higher
versions) Support
Warranty

Lease
Maintenance
Software License
License Management Exceptions
Do not create or update any of the following forms:

APR:Approver Lookup (approval mappings)
APR:SYS-Approval Definition (approval process definition)
BMC Service Request Do not:

Management
Make changes to any of the BMC Service Request Management configurations in the Application
Administration Console, including changes to categories, approval mappings, or entitlements.
Create or modify approval chains for service requests.
Make changes to the Request Catalog entries including service request definitions, process definition
templates and application object templates.
If you are upgrading BMC Service Request Management from a 2.2 version to a 7.6.02 or earlier
version, then all service requests in the Waiting Approval state must be approved or rejected
before you run the Delta Data Migration tool.
Field Customizations
If any custom field or selection values are added to an out-of-the box or custom field on the production server
after the database is copied to the staging server (delta period), then those changes must also be manually
applied on the staging server. If that is not done, then records with values on those fields will not migrate and you
will see an error similar this:
10/17/2011 23:14:12 2336 *ERROR* Migrations 23:14:12 : [4]-[306]-[Value does not fall within th

Accelerated staging server setup for upgrades without overlays

Accelerated staging server method is also referred to as DB only upgrade. When upgrading using accelerated
staging server, you only need to create a copy of the production server database in the staging environment. The
AR System server installation then must be done on the staging server against the copy of the production server
database.
You can use this method only if you are upgrading all of the products installed on your server, or if you do not
have BMC Service Impact Manager, Integration for BMC Remedy Service Desk, or BMC ProactiveNet Performance
Management installed on your production system.

To set up the accelerated staging sever for upgrade with overlays


database backup for upgrades with overlays.
4. Upgrade the AR System server. You must run the installer in Install mode such that, the AR System server is
upgraded and not installed fresh.
To ensure that the AR System server is upgraded and is not installed fresh, Database Name, Database User,
and Database Password must be same as the production server.
Database Host Name, and Database Port must point to the new database i.e. staging database.


Duplicated staging server setup for upgrades without overlays

To create a duplicated staging server, you need to create an exact duplicate of your production server, including
installing the AR System server and all of the ITSM applications and components, as well as any other applications
such as BMC Service Impact Manager, Integration for BMC Remedy Service Desk, or BMC ProactiveNet
Performance Management before starting the upgrade. If you set up the staging server this way, you can test your
system after each upgrade step, because you have a working system at the end of each stage. You can also test
the system after upgrading each ITSM application and its components.
To set up duplicated staging environment for upgrades with overlays

1. On the staging server, duplicate the installations as on the production server. See, Duplicating the
production server installations for upgrades without overlays.
database for upgrades without overlays.
after restoring the database on the staging server without overlays.
5. Upgrade the AR System server. You must run the installer in Upgrade mode.
6.
Duplicating the production server installations for upgrades without overlays

Use the following tables, and note the exact version and patch level of the software that is installed on your
production server.
AR System and ITSM Product versions for your environment
Product Version Patch Level
BMC Remedy AR System and associated components
BMC Atrium Core
BMC Remedy Knowledge Management
Non-ITSM Product versions for your environment
Product Version Patch Level
BMC Service Impact Manager
Integration for BMC Remedy Service Desk
BMC ProactiveNet Performance Management
Ensure that you have backups of all versions listed. Download the product files from the Licensed Products tab of
the BMC Software EPD web site ( http://webapps.bmc.com/epd).
Note
This might require multiple downloads per product. For example, to upgrade to BMC Remedy ITSM Suite
7.03 Patch 009, you also need to download 7.03, 7.03 Patch 007, and 7.03 Patch 009. Version and
product information can be found in the Shared Application Properties form.
To install the required software

Complete the following procedures to install each product and application listed in the previous tables.
Note
If you have a version of BMC Remedy ITSM Suite that is earlier than 7.0.03, or a version of BMC Remedy
Knowledge Management that is earlier than 7.6.04 in your stack, then BMC Remedy ITSM Suite requires

a full installation. You cannot use LOADAPP_SKIP mode. These product versions do not support that
mode, as described in step 3 in the following procedure.
1. Install all BMC Remedy AR System components that match the versions previously identified on the
production server. If you are using different locales, select your target locales to install applicable language
packs.
Ensure you use the same AR System instance name, AR System database administrator name (usually
ARAdmin) and password, and table space names, including temp space.
2. Install all required BMC Atrium Core components.
3. Set the following environment variables to true: BMC_AR_LOADAPP_SKIP=true and
BMC_LOADAPP_SKIP=true (true value must be lowercase).
This enables the application installers to conduct only the operating system level installation without
loading the application into the database.
Note
For the remaining staging preparation steps, conducting English only installations is sufficient for
BMC Remedy applications such as BMC Remedy ITSM, BMC Service Request Management, BMC
Service Level Management, and BMC Remedy Knowledge Management.
4. Install all applicable BMC Remedy ITSM Suite components and the required version patch.
5. If applicable, install BMC Service Level Management and the required version patch.
6. If applicable, install BMC Service Request Management. For 2.2.x, you do not need to install the subsequent
patches. Installing the base version is sufficient.
7. If applicable, install BMC Remedy Knowledge Management and the required version patch.
8. If applicable, install BMC Service Impact Manager and the required version patch.
9. If applicable, install the integration for BMC Remedy Service Desk and the required version patch.
10. If applicable, install BMC ProactiveNet Performance Management and the required version patch.
11. Remove the BMC_AR_LOADAPP_SKIP=true and BMC_LOADAPP_SKIP=true environment variables.

This section describes how to copy the current production server database schema and data to the new staging
server.
Back up the production server database

Work with your database administrator responsible for the production environment to create a full backup of the
current production BMC Remedy AR System database.
Note

Note the date and time of the backup for future reference. You will use this information in the delta data
migration step to determine which data needs to be migrated to the staging server at the end of the
upgrade process.
To duplicate production database backup on the staging server
1. On the staging server, shut down AR System server.

Substitute ARAdmin with the appropriate BMC Remedy AR Database Administrator Account.
4. Change the AR System server name to match the new host. For details, see Changing a server name when
using a duplicated or migrated environment.
5. If you are using the duplicated staging server method, restart the BMC Remedy AR System server and verify
that the system is functional.
6. If you are using the duplicated staging server method, work with the database administrator responsible for
the production environment to back up the staging server database.
7. Run the AR System database consistency checker, and run the health check in the BMC Atrium Core
maintenance tool (see below) to verify that your system is running correctly before the upgrade.
To run the CMDB Check
Note
The CMDB health check was introduced in version 7.5. If your staging server runs an earlier version, you
can skip this step.
1. Launch the BMC Atrium Core Maintenance Tool:

On Microsoft Windows, go to the <AtriumCoreInstallDir>\atriumcore folder, and double-click the
AtriumCoreMaintenanceTool.cmd file.
On UNIX, go to the <AtriumCoreInstallDir>/atriumcore/ directory, and launch the
AtriumCoreMaintenanceTool.sh file.
2. Click the Health Check tab, and follow the instructions there.

After you set up your staging server, review Stage 2 - Upgrade AR System server without overlays present,
including the subsections.

13.3.6 Stage 2 - Upgrade AR System server without overlays present

Performing the steps in this stage produces an upgraded BMC Remedy AR System server with your current
applications and data. This enables you to upgrade the other applications and AR System components in
subsequent stages.
This figure shows the components that are upgraded in stage 2.
To upgrade the AR System server
1. If you have modified any system forms, export them to a .def file so that your changes can be migrated
onto the upgraded forms.
2. Specify the option to export the related objects.
3. Select the Install option in the installation program if you are using the accelerated upgrade method to
upgrade the primary server in a directory where the previous ar.conf file is not present. During the
installation process, the installation program then displays a screen to confirm whether the database
upgrade can be continued. Select Yes to continue the installation procedure.
4. Restore any customizations to the system forms that might have been removed by the server upgrade
process.
a. Use BMC Remedy Migrator to compare the system forms on StagingServer to those in the .def file
that you created in step 1.
b. Using the information obtained from 4a, use Developer Studio or BMC Remedy Migrator to restore
any customizations that were overwritten during the AR System server upgrade.

Install the latest version of BMC Remedy Mid Tier on the identified mid tier host.
Note

If you are using locales other than English, select the target locales when upgrading each product.
After each product is upgraded:
1. Examine the installation logs to validate that upgrade was successful for each application.
2. Ensure that the Share Application properties are updated successfully.
Related topics
System objects that might be overwritten during upgrade

Upgrading AR System without overlays
System objects that might be overwritten during upgrade

The following AR System server definitions might be lost or overwritten when you upgrade from earlier versions
of AR System server (assuming that you select only AREA LDAP during installation). If you have modified any of
these objects, save a copy and restore your changes after upgrading the server.
Alert Events
Alert List
Application Pending
Application Statistics
Application Statistics Configuration
AR Sample Application: Console
AR System Actor View
AR System Administration: Add Or Remove Licenses
AR System Administration: Console
AR System Administration: Display Form To Collect User Decisions
AR System Administration: License Review
AR System Administration: Manage User Licenses
AR System Administration: Prompt For Open Attachment
AR System Administration: Server Information
AR System Administration: Server Information:Save Attachment
AR System Administration: Support Form
AR System Administrator Preference
AR System Alert Delivery Registration
AR System Alert User Registration
AR System Application State
AR System Currency Codes
AR System Currency Label Catalog

AR System Currency Localized Labels

AR System Currency Ratios
AR System Current License Usage
AR System Customizable Home Page
AR System Form Field Info
AR System Historical License Usage
AR System Home Page Descriptor
AR System Home Page Layout
AR System Ignored Analyzer Results
AR System License: Save Produse Attachment
AR System Licenses
AR System Licenses Audit
AR System Licenses Console
AR System Log: Alert
AR System Log: ALL
AR System Log: API
AR System Log: Escalation
AR System Log: Filter
AR System Log: FullText Index
AR System Log: Server Group
AR System Log: SQL
AR System Log: Thread
AR System Log: User
AR System Message Catalog
AR System Multi-Form Search
AR System Object Relationships
AR System Orchestrator Configuration
AR System Report Console
AR System Report Designer
AR System Report Preview
AR System Resource Definitions
AR System Searches Preference
AR System Skins
AR System Skins Properties
AR System Skins: Color Picker
AR System Skins: Skinnable Properties
AR System Tags
AR System User Application Actor
AR System User Central File
AR System User Preference
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
AR System Web Services Category
AR System Web Services Registry
AR System Web Services Registry Pending Delete
AR System Web Services Registry Query
AR System: Generate License Usage Report
ARC:ConfirmDialog
AREA LDAP Configuration
Business Segment-Entity Association_Join
Business Time Shared Entity-Entity Association_Join_Join
CHP:ConfirmDialog
Configuration ARDBC
Data Visualization Definition
Data Visualization Module
Data Visualization System Files
Distributed Logical Mapping
Distributed Mapping
Distributed Pending
Distributed Pending Errors
Distributed Pool
FB:Alarm Events
FB:Alarm Monitor
FB:Datasource
FB:DataSourceVariables
FB:Flashboards
FB:History
FB:History Summary
FB:User Privilege
FB:Variable
FB:Variable Attributes
Group
Home Page
MFS:MultiFormSearch
RD:Save As
Report
Report Definition
ReportCreator

ReportSelection
ReportType
Roles
Sample:Cities
Sample:ClassCentral
Sample:Classes
Sample:DialogYesNo
Sample:Enrollments
Sample:GetWeather
Server Events
Server Statistics
SHARE:Application_Interface
SHARE:Application_Properties
User
User Password Change
User Password Change Redirector
User Password Management Configuration
Visualizer Module Images
Visualizer Module Registration
Visualizer Type Information
Visualizer Type Object Props
Visualizer Type Style Info
Note
If you have not maintained a record of the customizations you made in earlier versions, you might want
to create a reference server that stores your original customizations. Then, compare the changes to the
objects in the list above with the objects on the reference server.
Upgrading AR System without overlays

The BMC Remedy AR System installer enables you to upgrade BMC products in your IT environment.
In this topic:
Choosing products
The suite installer guides you step-by-step through the upgrade process. When you start the installer, you can
choose one or more features to upgrade at one time. Because certain applications depend on a specific set of

features, you need to run the installer multiple times to upgrade all of the features in the solution. For example,
you first upgrade the AR System server on one computer and then run the installer a second time to upgrade the
mid tier on a different computer.
Recommendations
Complete the planning spreadsheet before you start the upgrade.

(WAN).
System server.
Choosing products
Engine, and Flashboards.
AR System Mid-Tier — Installs the Mid Tier only.
AR System Clients — BMC Developer Studio (and the Localization Toolkit), BMC Remedy Data Import, and
BMC Atrium Integrator Spoon.
The Clients option is Windows only; it is not available for Linux or UNIX.
Mininum set of features when installing BMC products
BMC Atrium Core

AR System Server
Approval Server
Assignment Engine
BMC ITSM
AR System Server
Approval Server
Assignment Engine


AR System Server
Approval Server
Assignment Engine

AR System Server
Approval Server
Assignment Engine
DVD.
a. To upgrade the AR System server in a directory that already has the ar.conf file, select the Upgrade
b. Select specific products to upgrade.
For example, select AR System Servers.
c. (optional) Add a new language.
You can later select additional localized views to install.
d. Navigate to the directory in which you want to install the BMC Remedy AR System application.
and Linux).
e. Click Next.
The installer validates your system resources.
8. Use the planning spreadsheet to enter the correct values in the AR System Server User and Database
Information pane, and then click Next.

9.
Note
10. Click Next.

14. Re-configure Full Text Search.
The installer disables FTS during the upgrade. Do not enable FTS until you re-configure it.
15. Convert your existing overlays into granular overlays through the Object Granularity Level option.
System server.
2. Open the ARSuiteKitWindow folder.
4. Start the installer and double-click setup.cmd.
a. Select Upgrade.
b. Navigate to the directory in which you want to install the Mid Tier.
and Linux).
c. Select AR System Mid-Tier.
d. Click Next.
8. Enter the values from the planning spreadsheet for the Mid Tier.
9. Click Next.

10.
).
15. Log out.
16. (optional) Restart the Mid Tier web service.
Related topics


Stage 3 - Create overlays for existing customizations
13.3.7 Stage 3 - Create overlays for existing customizations

In stage 3, you copy your existing customizations into overlays and custom objects, allowing them to be
preserved for future upgrades. This includes customizations to BMC Remedy AR System server and all other
applications and components.
The following figure shows how the Best Practices Conversion Utility (BPCU) is used to create overlays and
custom objects from your existing objects. If you customized workflow by copying and disabling an application
object, you need to run BPCU twice. Otherwise, you need to run it only once. Object 1 is a customized version of
workflow object 2, so object 1 is converted into an overlay of object 2. Because object 3 is a modified application
object, object 7 (a new object), is created as an overlay of object 3. Object 6, which was created in the production
environment is converted into a custom object.
The upper plane shows the overlay group, which contains overlays, custom objects, and origin objects that
have not been overlaid.
The lower plane shows the base group, which contains only origin objects.

To create overlays
1. Find out what objects have been modified.

In particular, determine which objects have been modified in ways that are not permitted in overlays. For
any such objects, this can prevent an application upgrade from succeeding, if the upgrade affects that
object.
Running the BPCU in ReportDiff mode allows you to determine such modifications, and to make the
necessary corrections before upgrading any applications. It compares the current objects to a set of base
objects that are defined in an overlay hash file.
To generate a BPCU difference report:
a. At a command prompt, change directories to the BPCU installation directory,
<utilityInstallDir>/Best_Practice_Conversion_Utility.
b. Run the BPCU in ReportDiff mode, and compare objects on StagingServer with those in the overlay
hash file:
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m D -f "<hashFileLocation>
A BPCU difference report, bpcu-diff-report_date_timestamp.html, is generated and placed in the

<utilityInstallDir>\Best_Practice_Conversion_Utility\output folder. The report is an HTML-formatted
file that displays a list of the extensions and customizations in your setup, and indicates whether the
extensions and customizations are permitted or non-permitted.
The BPCU also generates some migrator .xml instruction files that are used in stage 5 of the upgrade
process.
2. If the BPCU difference report shows non-permitted customizations, resolve them.

2.
Note
Ensure that you have set your BMC Remedy Migrator configuration options before performing the
following procedures.
a. Install a reference server (ReferenceServer) that is the same version as your production AR System
server, and install copies of all applications that are running on your production server. (The installed
applications must be the same version as the applications on your production server, including
patches and hotfixes.) The reference server will have only unmodified origin objects from the BMC
released software, with no customizations.
b. On ReferenceServer and StagingServer, use the Migrator command-line interface to create a
.migrator file that contains only the objects with non-permitted customizations. Then, use Migrator
to compare the two files.
c. For each object that contains a non-permitted modification, perform the appropriate corrective
action.
d. After fixing all non-permitted modifications, delete your Migrator instruction files and the difference
report from the output folder.
e. Run the BPCU again in ReportDiff mode to generate a clean set of instruction files based on your
server after you have removed all non-permitted customizations.
Note
The clean Migrator instruction files are the instruction files that you will use in stage 5 of the
upgrade process.
These corrective actions allow BPCU to preserve an object as a custom object that does not conflict
with a BMC application object, or the corrective actions allow BPCU to create an overlay from the
object.
3. Create overlays or custom objects from your customizations so that they will be preserved across an
application upgrade.
To do this, run the BPCU again in Overlay mode to create overlays and custom objects.
In some cases, BMC application objects might have been copied and disabled, with modifications made to
the enabled copy. Generally, such copies have names that are the same as the original object name
appended with a well-known prefix or suffix. In other cases, BMC application objects might have been
modified directly, or there may be a mixture of these methods.
If at least some of your customizations are copies of original objects with names that have well-known
prefixes or suffixes, perform the following steps:
a. For each object, if its name contains both a prefix and a suffix, remove one or the other. Otherwise,
the BPCU does not convert the object.
b.
b. If you created copies of original objects but did not use prefixes or suffixes to identify them, rename
those copies to include a prefix or a suffix.
c. Run BPCU in Overlay mode with the -P and -S options.
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>
BPCU makes the following changes to active links, filters, and escalations:
If the origin object is enabled, BPCU marks the copy as a custom object.
If the origin object is disabled, BPCU converts the copy into an overlay of the origin object.
The -P and -S options allow BPCU to convert active links, filters, and escalations into overlays
when they are copies of disabled origin objects.
d. Run the BPCU in Overlay mode again without the -P and -S options.
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>
The BPCU generates overlays for directly changed origin objects.
If your customizations are only in modified origin objects that have not been copied and renamed, perform the
following step:
Run BPCU in Overlay mode without the -P or -S option.
bpcu -x localhost -t serverport -u Demo -p "DemoPassword" -m o -f "<hashFileLocation>\Over
The BPCU generates overlays for the modified objects and converts any user-created objects to custom
objects.
Related topics

Stage 4 - Acquire origin objects (optional)
Overlay hash files

An overlay hash file, also called a snapshot, is an XML file that contains keys for all the objects in a particular
version of BMC Remedy AR System or a BMC Remedy AR System application:
For fields and views, the key is the object's ID.

For all other objects, the key is the object's name.
The Best Practice Conversion Utility (BPCU) compares objects in an overlay hash file with those in a customized
BMC Remedy AR System component or application. BPCU produces a difference report that contains the results
of the comparison.

To obtain the overlay hash file
1. Download the latest version of the OverlayHashFile.zip file from the BMC Communities website.
Note
Updates to the overlay hash file between patch releases are posted to BMC Communities website:
https://communities.bmc.com/communities/community/bmcdn.
Always make sure to download the latest version from this location, and use the same version of
the hash file as that of the BPCU.
2. Uncompress the .zip file and extract the OverlayHashFile.xml file to your development server.
BMC product information

If you are upgrading from the following releases, you can use the overlay hash file ( OverlayHashFile.xml) to
compare the objects in your customized applications with the objects in the origin applications:
AR System and its components (including AR System server, BMC Remedy Approval Server, BMC Remedy
Assignment Engine, BMC Remedy Email Engine, BMC Remedy Flashboards, AREALDAP plug-in, ARDBC
plug-in, and Web Services) with version 6.3.00 through the current version:
BMC Atrium CMDB version 2.0.01 patch 004 through the current version
BMC Remedy Enterprise Integration Engine version 7.1.00 through the current version
BMC Remedy ITSM Suite version 7.0.03 patch 007 through the current version
BMC Remedy Knowledge Management version 7.2.00 through the current version
BMC Service Level Management version 7.1.00 through the current version
BMC Service Request Management version 2.2.00 through the current version
BMC Remedy OnDemand version 2010.01 through the current version
BMC integration information

The overlay hash file contains data about the following BMC integration objects:
BMC Remedy Identity Management

BMC BladeLogic Client Automation for Clients
BMC BladeLogic Client Automation for Server
BMC BladeLogic Server Automation
BMC Atrium Discovery and Dependency Mapping (versions 7.5.00 and 8.1.015)
Configuration Discovery extensions (version 7.0.00 through the current version) for CMDB
BMC Topology Discovery 7.6.00
BMC IT Business Management

BMC Service Impact Manager (Extensions of versions 7.3.00, 7.3.01, 7.3.02 for BMC Atrium CMDB 2.1.00,
and BMC Atrium CMDB 7.5.00 through the current version)
BMC Remedy Mid Tier object list definition files for AR System 7.0.01 through the current version
Server group and DSO settings for AR System 7.0.01 through the current version
Related topics


The Best Practice Conversion Utility (BPCU) helps preserve customizations when upgrading. The utility converts
objects in earlier versions of BMC Remedy AR System components and applications as follows:
BMC objects that you modified (customizations) are converted to overlays.

User-created objects that you added to your setup (extensions) are converted to custom objects.
BPCU enables you to analyze objects in your current environment with the out-of-the-box objects in 7.6.04 and
higher, and convert them into overlays or custom objects.
BPCU does not save customizations to objects that are not meant to be customized and that can be replaced
during an application installation or during the normal process of running an application. These are referred to as
non-permitted customizations (that is, customizations that are not permitted in overlays).
BPCU operates in the following modes:
ReportDiff – Generates a report of differences between the objects in an overlay hash file and the objects
on a server. See Using BPCU to generate difference reports.
Overlay – Based on a differences report, converts customized AR System objects into overlays, and
converts user-created objects into custom objects.
Before upgrading applications or creating overlays, use BPCU to determine which objects have been modified in
ways that are not permitted in overlays.
The following table lists the BMC products in which the BPCU preserves customizations and the related
exceptions.
Customizations preserved by BPCU
BMC Exceptions
products
AR System components
Filters that BMC Remedy Approval Server workflow creates at runtime, whose names begin with AP:Notify-0

BMC
Remedy
Approval
Server
BMC None
Remedy
Assignment
Engine
BMC None
Remedy
Email Engine
AREA LDAP None

plug-ins
ARDBC None
LDAP
plug-ins
BMC Atrium CMDB
BMC Atrium The BMC Atrium CMDB upgrade program takes care of preserving customizations made to forms and workflow objects. BPCU
CMDB ignores the following forms and their related workflow objects and workflow guides: Forms that belong to the BMC:Atrium CMDB
application Forms that do not belong to the BMC:Atrium CMDB application, but whose names are listed in the OBJSTR:Class form (
<namespace>:<classname> )
AR System applications
BMC Application forms that use BMC Atrium CMDB forms as self-join forms (MemberA and MemberB are the same)
Remedy
ITSM Suite
BMC Service Filters with the zSLMGen: prefix that BMC Service Level Management workflow creates at runtime Forms that BMC Service Level
Level Management creates at runtime, whose names end with _SLA, and their related workflow objects and workflow guides
Management
BMC Service Filters with the zAPR prefix that BMC Service Level Management workflow creates at runtime
Request
Management
Warning
The utility does not preserve customizations to forms and workflows installed with the AR System server
unless customizations are present when the utility is run.
You should upgrade to the current release of BMC Remedy AR System before running BPCU. This
upgrade replaces the system forms, so reapply the customizations to system forms before running
BPCU.

Related topics

Obtaining BPCU
This topic provides instructions for obtaining the Best Practice Conversion Utility (BPCU).
To obtain BPCU
1. Install only the BMC Remedy AR System server on a staging server, development testing server, or any
other server that is going to be used for upgrading or testing the upgrade process.
Warning
Do not install any BMC Remedy AR System components or applications other than the AR System
server. If you do, your customizations might be overwritten.
2. Obtain the latest version of the BPCU and the hash file from this location.
Updates to BPCU (bpcuversionNumber.zip) and the Overlay hash file (OverlayHashFile.zip) between patch
releases are posted to BMC Developer Network Community website.
3. Uncompress the OverlayHashFile.zip file and extract the OverlayHashFile.xml file to your development
server.
4. Uncompress the bpcuversionNumber.zip file, which is located in the ARSystemServerInstallDir folder.
By default, the BPCU files are extracted to the Best_Practice_Conversion_Utility folder.
After the BPCU files are uncompressed and in the Best_Practice_Conversion_Utility folder, no further installation
or configuration is needed. The utility is ready to be run from a command prompt.
Configuring your system for BPCU

Make sure that your CLASS path and Oracle Java Runtime Engine (JRE) are correctly configured to support the
Best Practice Conversion Utility (BPCU).
To configure your system to run the BPCU
1. On UNIX, grant yourself execute permission to the BPCU by typing the following command:
chmod +x bpcu.sh
2.
2. Make sure the following files are in your CLASS path:

arutilversionNumber.jar
arcmnappversionNumber.jar
bpcu.jar
commons-jxpath-1.3.jar
jaxb-api.jar
jaxb-impl.jar
jsr173_1.0_api.jar
log4j-1.2.14.jar
3. To produce the BPCU differences report in XLSX format, make sure that the following files are in your
CLASS path:
dom4j-1.6.1.jar
ooxml-schemas-1.0.jar
poi-3.5-FINAL-20090928.jar
poi-ooxml-3.5-FINAL-20090928.jar
xmlbeans-2.3.0.jar
4. To specify the JRE for the utility, add the following entry to the appropriate file:
set JAVA_HOME=<fullPathToJRE>
Tip
Run BPCU with a 64-bit JRE.
The BPCU uses the JRE specified by the JAVA_HOME environment variable in the following files:
(Windows) bpcu.bat
(UNIX) bpcu.sh
5. To avoid out-of-memory issues, set Max Heap Size option in the bpcu.bat file to 4 GB.
6. If you plan to run the BPCU on an AR System server that enforces encryption in its API, add the following
items to the JRE that BPCU will use.
Files and providers to add to BPCU JRE on encrypted servers
Add to this directory or file On Oracle Solaris, UNIX, and Windows On IBM AIX and DB2, UNIX, and Windows
jre\lib\ext jsafeJCEFIPS.jar jsafeJCEFIPS.jar
bcprov-jdk15-133.jar
jre\lib\security US_export_policy.jar US_export_policy.jar
local_policy.jar local_policy.jar
These files should be from IBM.

Add to this directory or file On Oracle Solaris, UNIX, and Windows On IBM AIX and DB2, UNIX, and Windows
jre\lib\security\java.security security.provider.<n>+1=com.rsa._ security.provider.<n>+1=org.

jsafe.provider.JsafeJCE bouncycastle.jce.provider.
BouncyCastleProvider
<n> can be the last number in the section.
security.provider.<n>+2=com.rsa.
jsafe.provider.JsafeJCE
n can be the last number in the section.
Note
If you have installed a BMC Remedy Encryption Security product on a BMC Remedy Java client, such as
BMC Remedy Developer Studio or BMC Remedy Data Import, you do not have to verify that your
configuration matches the preceding specifications. Instead, use the same Oracle Java Developer's Kit
(JDK) and JRE used by the client for BPCU.
Related topics
FIPS encryption options
Run the Best Practice Conversion Utility (BPCU) in ReportDiff mode to compare objects between the overlay hash
file and an BMC Remedy AR System server, and generate difference reports.
To generate a differences report
1. At the command prompt, go to the <utilityInstallDir>\Best_Practice_Conversion_Utility directory

2. Run BPCU in ReportDiff mode by executing the following command with the appropriate arguments (see
the following table):
(Microsoft Windows) bpcu.bat
(UNIX) bpcu.sh
Command-line options for ReportDiff mode
Option Description
-x Name of the server on which to perform the operation.
-u User name.
-p User password.
-a (optional) User authentication string.
-t (optional) TCP port of the server on which to perform the operation.

Option Description
-r (optional) RPC port of the server on which to perform the operation.
-f Absolute path to the overlay hash file (include full path and file name).
-c (optional) Full path to the XML file containing a list of objects to include in or to exclude from the operation.
This option does not apply to ReportDiff mode when two overlay hash files are compared.
-e (optional) Comma-separated list of form names whose associated fields and views are the only objects processed by the operation.
Do not use this option with the -s option.
-o (optional) File name and path of the difference report. Do not include a file extension.
If you do not provide a file name, the following name is used:

bpcu-diff-report-date_timestamp.html
If you do not provide a path, the utility places the report file in the installationDir\Best_Practice_Conversion_Utility\output folder.
-T (optional) Format of the difference report. Values are:
0 — (Default) HTML
1 — CSV
2 — XLSX
-i (optional) Flag that specifies whether to include overlay and custom objects in the "extension" section of the difference report.
This option applies only to file-to-server comparisons. Values are:
0 — (Default) Exclude from extension section.

1 — Include in extension section.
-m Utility mode. Values are D or d or diff.
-k (optional) Indicates whether to display or hide the list of objects that will be skipped in Overlay mode.
0 — (Default) Hide this list in the difference report.

1 — Display this list in the difference report.
Related topics
For an example of using the bpcu command to compare objects, see Stage 3 - Create overlays for existing
customizations.
Using BPCU to generate overlays for modified legacy objects
In Overlay mode, the Best Practice Conversion Utility (BPCU) compares objects in an overlay hash file with the
objects on a server, generates a report of their differences, and performs the following tasks based on the
contents of the report:
For permitted customizations, BPCU generates an overlay by creating a copy of each object, and sets its
Overlay property to Overlay.
For permitted extensions, BPCU generates a custom object and sets the Overlay property to Custom.

In Overlay mode, BPCU ignores all the overlay, overlaid, and custom objects on the server. Therefore, running
BPCU multiple times in Overlay mode does not cause problems for such objects, including objects that are
shared among applications.
To generate overlays for pre-7.6.04 objects
1. Generate a difference report, and fix all the non-permitted extensions and customizations that are
identified.
If non-permitted extensions and customizations are found among the set of objects to be processed,
BPCU does not run in Overlay mode.
2. At the command prompt, go to the <utilityInstallDir>\Best_Practice_Conversion_Utility folder.
3. Run BPCU in Overlay mode by executing the following command with the appropriate arguments (see the
following table):
(Microsoft Window) bpcu.bat
(UNIX) bpcu.sh
Command-line options for Overlay mode
Option Description
-x Name of the server on which to perform the operation.
-u User name.
-p User password.
-a (optional) User authentication string.
-t (optional) TCP port of the server on which to perform the operation.
-r (optional) RPC port of the server on which to perform the operation.
-f Absolute path to the overlay hash file provided by BMC (include full path and file name).
-c (optional) Full path to the XML file containing a list of objects to include in or to exclude from the operation.
This option applies to all modes except when two overlay hash files are compared in ReportDiff mode.
-e (optional) Comma-separated list of form names whose associated fields and views are the only objects processed by the operation.
Do not use this option with the -s option.
-o (optional) Name of the difference report. Do not include a file extension.
-T (optional) Format of the difference report. Values are:
0 — HTML (Default)
1 — CSV
2 — XLSX
-m Utility mode. Values are o or overlay.
-k (optional) Indicates whether to display or hide the list of objects that are skipped during conversion.
0 — (Default) Hide this list in the difference report.

Option Description
1 — Display this list in the difference report.
-P Comma-separated list of prefixes in the names of user-created objects.

All objects whose name begins with one of these prefixes are converted into overlays or custom objects.
This option applies only to active links, active link guides, filters, filter guides, escalations, menus, and all types of containers. (Per BMC
recommendations, to modify such objects in pre-7.6.04 releases, you should make a copy of the origin object and add a prefix or suffix to
its name.)
You must ensure that the corresponding out-of-the-box object exists and is the same type in the 7.6.04 release.
-S Comma-separated list of suffixes in the names of user-created objects.

All objects whose name ends with one of these suffixes are converted into overlays or custom objects.
This option applies only to active links, active link guides, filters, filter guides, escalations, menus, and all types of containers. (Per BMC
recommendations, to modify such objects in pre-7.6.04 releases, you should make a copy of the origin object and add a prefix or suffix to
its name.)
Ensure that the corresponding out-of-the-box object exists and is the same type in the 7.6.04 release.
-i (optional) Flag that specifies whether to include overlay and custom objects in the "addition" section of the difference report. Values are:
0 — (Default) Exclude from addition section.

1 — Include in addition section.
The differences report that BPCU generates

BPCU generates a report that shows differences between the unmodified objects represented in an overlay hash
file and objects on a server. It also shows which changed objects can be converted into overlays or custom
objects, and which objects have been changed in a way that makes the conversion impossible.
Difference reports are produced in HTML, comma-separated values (CSV), or Microsoft Excel (XLSX) formats. By
default, the report name uses the following format:
bpcu-diff-report_date_timestamp.extension
Difference reports are stored in the <utilityInstallDir>\Best_Practice_Conversion_Utility\output folder.
The following table describes the information that a difference report provides about objects and where you can
find the information.
Information in a difference report generated by BPCU
Information XLSX report format HTML report format
Statistical information about all types of objects found on the server where BPCU was executed: Dashboard worksheet Dashboard tab
Total count of objects

Number of new objects
Number of changed objects
Percentage customization
Number of new and changed objects with nonpermitted modifications

Information XLSX report format HTML report format
The following types of statistical information is displayed only when you use a certain
execution parameter.
Number of new objects that are not converted to custom objects when you execute BPCU in
Overlay mode
Number of changed objects that are not converted to overlays when you execute BPCU in
Overlay mode
Whether an object on the server is new Difference Report Extensions tab

worksheet, rows with
the value Extension in
the Customization
Type column
Whether an object on the server has been modified Difference Report Customizations tab
worksheet, rows with
the value
Customization
in the Customization
Type colum
Whether modified objects in the server contain permitted or nonpermitted modifications: Difference Report Customizations tab,
worksheet, rows with all panels
If an object contains non-permitted modifications, it is flagged as an object that cannot be the value
converted into an overlay. All such objects must be fixed before running BPCU in Overlay Customization in the Permitted
mode. Customization Type modifications:
If an object contains permitted modifications, its flagged as an object that can be converted column Convertible
into an overlay. to Overlay =
Permitted true
Note: When you run BPCU in ReportDiff mode with the -k option and its value as 1, the modifications: Nonpermitted
Customizations tab displays the Skipped During Conversion column. This column displays the Convertible to modifications:
value true for objects that are skipped during conversion whether they were modified in a Overlay = true Convertible
permitted or non-permitted manner. Therefore, even if the Convertible to Overlay column for Nonpermitted to Overlay =
a particular object displays the value false, you do not need to fix any non-permitted modifications: false
modifications made on it. Convertible to
Overlay = false
Execution Execution
Version of the utility that was executed to generate the Information Information tab
report worksheet
Date and time when the report was generated
Parameters supplied to the utility for the current execution
AR System applications installed in the execution environment
Note
BPCU does not include information in a difference report about objects that are unchanged.
BPCU HTML report Dashboard tab

BPCU HTML report Extensions tab

Convertible to Overlay column in Customizations tab indicates whether the customization is permitted in
overlays

BPCU HTML report--Execution Information tab

Related topics
Stage 3 - Create overlays for existing customizations for an example
of using the bpcu command to generate overlays
Permitted and non-permitted modifications on overlays
BPCU log information

When the Best Practice Conversion Utility (BPCU) is first run on a server, it creates the BPCU-Log form. The form
records information about each run of the utility, such as the run date, run mode, and return code. The form also
stores the log file and the difference report that are associated with the run as attachments.
By default, BPCU log file is <ARSystemServerInstallDir>\Best_Practice_Conversion_Utility\bpcu.log.
To change the log file name, modify the log4j.properties file.
Each time BPCU is run, the information in the bpcu.log file is overwritten. The previous version of the log is saved
in the BPCU-Log form.
BMC Remedy AR System application installation programs can use the bpcu.log file to determine whether BPCU
was run and whether overlays were successfully created.
1. Open the <migratorInstallDir>\Migrator Configuration.xml file.

2. Update the <required> section as follows:

2.
<required>
<param name="MergeSharedWorkflow" enabled="false"/>
<param name="Menus" enabled="false"/>
<param name="TableFieldForms" enabled="false"/>
<param name="JoinFormMembers" enabled="false"/>
<param name="FlashboardVariables" enabled="true"/>
<param name="FlashboardDataSources" enabled="true"/>
<param name="MenuRelatedForms" enabled="false"/>
<param name="ApplicationStates" enabled="true"/>
<param name="ApplicationForms" enabled="false"/>
</required>
3. Update the <removal...> section in one of the following ways:

Add the entire <removal... > section shown below (if it does not exist).
Add the lines for Fields and Views (listed below) to the existing section.
Change the values for Fields and Views in the existing section to enabled="false".
<removal action="delete" type="specified">

<object type="Fields" enabled="false"/>
<object type="Views" enabled="false"/>
</removal>
4. Save and close the configuration file.

Viewing differences between objects
Viewing differences between objects

The Best Practice Conversion Utility (BPCU) generates a differences report that identifies objects that differ from
the origin objects. However, the differences are not described. BPCU also automatically generates the following
instruction files for BMC Remedy Migrator when it is run in comparison (ReportDiff) mode:
migrator-instruction_<date>_<timestamp>.xml — Lists all modified objects on the server, except specific

views and fields that were modified.
migrator-npmod-instruction_<date>_<timestamp>.xml — Lists only objects with non-permitted
modifications.
These files are located in the <utilityInstallDir>\Best_Practice_Conversion_Utility\output folder.
Using these instruction files, the BMC Remedy Migrator CLI creates .migrator files that contain the new and
modified objects on a server. BMC Remedy Migrator can use these .migrator files to generate detailed differences
reports.

To view details of differences between objects
Note
Ensure that you have set your BMC Remedy Migrator configuration options before performing the
following procedure.
1. On StagingServer, use the BMC Remedy Migrator instruction file that was generated in the last execution of
the BPCU in comparison mode (see information about stage 3), to create a .migrator file:
migratorcli -m -s <serverName> -t <serverport> -u <adminUserName> -p <password> -g "Migrat
For example:
C:\Program Files (x86)\BMC Software\Migrator\Migrator>MigratorCli.exe -m -s "sj-svr-team-0
Note
The --dst_user and --dst_password parameters are necessary only if credentials for the
destination server are different from those of the source server.
2. From ReferenceServer, use the same BMC Remedy Migrator instruction file to create a second .migrator
file.
3. In BMC Remedy Migrator, open the .migrator file created in step 1, and compare it with the .migrator file
created in step 2.
4. Generate a report of the comparison and use it to view the details of differences between objects.
Related topics
Stage 3 - Create overlays for existing customizations
Migrating using command-line interface

Fixing non-permitted modifications
Fixing non-permitted modifications

This section describes how to fix non-permitted modifications that were discovered when the Best Practices
Conversion Utility (BPCU) compared objects on the staging server with an overlay hash file. Because some of the
changes described here alter the functionality of an object, you might want to copy the object as a custom object
before changing it.

The following topics assume modified objects are on StagingServer and unmodified origin objects of the same
version are on ReferenceServer:
Related topics

Stage 4 - Acquire origin objects: optional
Fixing non-permitted changes for objects

Names that include underscore + underscore + lower case o (__o) are reserved by BMC. You can rename an
object with __o in its name so that you can fix any changes to the object.
To rename an object to remove the __o string
1. On StagingServer, locate the object that contains __o in its name.

2. In the object list, select the object, and choose File > Rename.
3. Rename the object so that it does not include __o in its name, and so that its name does not conflict with
the name of any other object.
Fixing non-permitted modifications for forms

This topic contains instructions for fixing non-permitted modifications to forms.
To change the inclusion or exclusion of a form in a deployable application
1. On StagingServer, open the application in an editor.

2. On ReferenceServer, open the application.
3. On StagingServer, add or remove forms in the application to match those on ReferenceServer.
4. Save the application.
To change unique indexes
1. On StagingServer, open the Regular form.

2. Click the Definitions tab, and expand the Indexes panel.
3. On ReferenceServer, view the Indexes category for the corresponding form.
4. On StagingServer, specify the same number and order of unique indexes in the Index List with the same
number and order of indexed fields as those on ReferenceServer.
5. Remove any unique indexes that are not on ReferenceServer.
6. Save the form.
To change vendor form information for Table Name or Vendor Name
1. On StagingServer, open the Vendor form.

2. Click the Definitions tab, and expand the Other Definitions panel and then the Vendor Information panel.
3.
3. On ReferenceServer, view the Vendor Information category for the corresponding form.
4. On StagingServer, set the Vendor Name and Table Name properties to the same values as those of the
form on ReferenceServer.
5. Save the form.
To change join form information
1. On StagingServer, open the Join form.

2. Click the Definitions tab, and expand the Other Definitions panel and then the Join Information panel.
3. On ReferenceServer, view the Join Information category for the corresponding form.
4. On StagingServer, set the Join Type and Qualifier values to the same as that on ReferenceServer. If
required, swap the Primary and Secondary forms.
5. Compare every field on the StagingServer Join form with its counterpart on the ReferenceServer Join form
to verify that the values of their Form Name property match.
For each field where the values differ, perform the following tasks on the StagingServer Join form:
a. Delete the field.
b. Right-click and choose Add Fields from <formName>, where <formName> matches the value on the
ReferenceServer Join form.
6. Save the form.
To change view form information for Table Name or Key Field

For each view form where the Table Name or Key Field properties have been changed, set the values on
StagingServer to match those on ReferenceServer.
To change properties for Label, Locale, or Name of a view
1. On StagingServer, open the form and the appropriate form view.

2. On ReferenceServer, open the corresponding form view.
3. On StagingServer, set the view's Label, Locale, and Name properties to the same value as that of the field
on ReferenceServer.
4. Save the form.
Fixing non-permitted modifications for fields

This topic provides instructions for fixing non-permitted modifications to fields.
To change the data type

If your field does not contain data that should be saved, delete the field on StagingServer and copy the
corresponding field from ReferenceServer to StagingServer.
If the field does contain data that should be preserved, perform the following steps:
1. On StagingServer, rename the field.
2.
2. Use the ARCHGID utility to change the ID to the customer range.

The ARCHGID utility is not supported. For information about this utility, see
https://communities.bmc.com/communities/docs/DOC-19172.
3. Copy the corresponding field from ReferenceServer to StagingServer.
4. Copy data to this field if the data is compatible.
5. Delete the field that you renamed in Step 1.
6. Save the form.
To change the Column properties on View and Vendor forms
1. On StagingServer, open the View or Vendor form and the form view that contains the field, and select the
field.
2. On ReferenceServer, select the corresponding field.
3. On StagingServer, set the field's Column property to the same value as that of the field on ReferenceServer.
4. Save the form.
To change the Name
1. On StagingServer, open the form and the form view that contains the field, and select the field.
2. On ReferenceServer, select the corresponding field.
3. On StagingServer, set the field's Name property to the same value as that of the field on ReferenceServer.
4. Save the form.
To change the Length Units property of character fields

If your field does not contain data that should be saved, then delete the field on StagingServer and copy the
corresponding field from ReferenceServer to StagingServer. If the field does contain data that should be
preserved, perform the following steps:

6. Save the form.
To change the Column field properties for Parent field ID, Data field ID and Data Source
For each field where these properties have been changed, set the values on StagingServer to match those on
ReferenceServer.
To change the Entry Mode to Display

If the out-of-the-box field's Entry Mode is Display, and the StagingServer field is not, complete the appropriate
steps:

If the field does not contain data that must be saved:
1. Delete the field on StagingServer.

2. Copy the corresponding field from the ReferenceServer to StagingServer.
If the field does contain data that should be preserved, perform the following steps:

4. Save the form.
To change the field type

If your field does not contain data that should be saved, then delete the field on StagingServer and copy the
corresponding field from ReferenceServer to StagingServer. If the field does contain data that should be
preserved, perform the following steps:

6. Save the form.
13.3.8 Stage 4 - Acquire origin objects: optional

When you upgrade an application, its origin objects are modified. If you want to understand the effects of these
modifications, compare origin objects from the original application with origin objects from the upgraded
application. Similarly, to understand the modifications captured in your overlays, compare them with origin
objects from the software to which you want to upgrade.
In stage 4, you acquire unmodified origin objects. Then, you can compare the overlays on your server to these
unmodified origin objects, allowing you to see exactly what has changed in any object.
To acquire origin objects

Set up a current version reference server (ReferenceServer) with unmodified versions of the same BMC Remedy
AR System components and applications that exist on your production server:

If you already created a reference server in stage 3 to use when fixing any non-permitted customizations,
upgrade that reference server to the current version of BMC Remedy AR System.
If you did not create a reference server in stage 3, set up a new reference server. First, install the current
version of BMC Remedy AR System, and then install out-of-the-box versions of all the applications that are
running on your production server, including any patches and hotfixes.

Stage 5 - Restore origin objects to the staging server: optional
13.3.9 Stage 5 - Restore origin objects to the staging server: optional

If you want to view your objects in Base Development mode within BMC Remedy Developer Studio, perform the
steps in stage 5. This procedure replaces the origin objects on StagingServer with the unmodified origin objects
from ReferenceServer. If the unmodified origin objects on StagingServer are preserved, you will not have to
maintain the reference server with the objects. In addition, you can:
Observe the customizations captured in your overlays by comparing the overlays to the origin objects in
Developer Studio on a single server in Base Development mode.
Configure StagingServer so that your application uses your customizations, or so that it has only the
original unmodified functionality.
Migrate your unmodified origin objects into a migrator file, and from there, selectively migrate them to
StagingServer. Restoring the origin objects to StagingServer does not affect the overlays that you created.
This figure shows the replacement of modified application objects with their unmodified original versions.
(Overlays and custom objects are unaffected by this process.)
To restore origin objects to the staging server
1. Ensure that you have set your BMC Remedy Migrator configuration options.
2.
2. Use the migratorcli command to migrate origin objects from ReferenceServer to a .migrator file by
using the instruction file that the Best Practice Conversion Utility (BPCU) generates in stage 3.
Note
Before running this command, confirm that BMC Remedy AR System installed on your reference
server is the current version.
migratorcli.exe -m -s ReferenceServer -t <serverport>

-d "<destinationFilePath>\<fileName>.migrator"
-i "<instructionFilePath>\migrator-instruction_<date>_<timestamp>.xml"
-u Demo -p "<DemoPassword>" -g "Migrator Configuration.xml"
--level 4 --layout 1 --logfile <logFileNameAndPath>
3. Migrate objects from the .migrator file to StagingServer.

To selectively migrate your objects, use the BMC Remedy Migrator application.
a. Open the .migrator file in BMC Remedy Migrator, and double-click the .migrator file name in the
navigation pane.
b. In the object list, select AR System server objects of the same type, right-click and select Migrate
Selected Objects > StagingServer.
c. Repeat this step until all your objects have been migrated from the .migrator file to StagingServer.
To migrate all of the objects at once, use the migratorcli command.
migratorcli.exe -m -s "<sourceFilePath>\<fileName>.migrator"
-d StagingServer --dst_<tcpport> <serverport>
-i "<instructionFilePath>\migrator-instruction_<date>_<timestamp>.xml"
-u Demo -p "<DemoPassword>" -g "Migrator Configuration.xml"
--level 4 --layout 1 --logfile <logFileNameAndPath>
Related topics

Stage 6 - Minimize overlays: optional
13.3.10 Stage 6 - Minimize overlays: optional

In stage 6, you can minimize the number of overlays. You should remove all overlays that are the same as the
object that they overlay, and all overlays that contain changes that are no longer needed. This reduces the
number of customizations that must be maintained during future application upgrades.

Tip
Overlays that are identical to their overlaid objects might exist if you converted any prefixed or suffixed
objects in stage 3.
If you restored the origin objects to StagingServer (Stage 5), you can compare your overlay to the origin objects.
This figure shows the removal of an unneeded overlay, item 7. Note that removal of the overlay exposes the
origin object.
To minimize your overlays
1. If you performed the tasks in stage 5, use BMC Remedy Migrator to compare overlaid object to their
overlays directly on StagingServer, and then delete the objects that are identical.
If you did not perform the steps in stage 5, then the overlays and overlaid objects on StagingServer are
identical, except for those that previously had prefixes or suffixes. Set Migrator difference mask options,
and use BMC Remedy Migrator to compare the overlaid objects on StagingServer to the same objects on
ReferenceServer. If they are identical, you can remove the overlay on StagingServer.
Note
When removing overlays, be careful of workflow objects. Disabled workflow objects are not
identical to enabled ones, even if all other aspects are the same.
2. If you have overlays that are not identical to the origin object but that contain changes that you no longer
want to keep, delete those overlay objects.

Related topics
Comparing overlays to overlaid objects on the same server to learn about Migrator difference mask options

Stage 7 - Upgrade applications and adjust customizations with new overlays

This topic provides instructions for using BMC Remedy Migrator to compare objects on the same server if you are
minimizing overlays in stage 6.
To set Migrator difference mask options

Before comparing overlays to overlaid objects, you must set certain difference mask options in addition to the
default mask options so that BMC Remedy Migrator only compares differences that affect the operation of your
application.
1. In BMC Remedy Migrator, open a new server window for StagingServer.

2. Choose Tools > Options.
3. In the BMC Remedy Migrator Options dialog box, perform the following actions:
a. Expand Differences, expand Masks, and set the following options to Disabled:

Forms – Name, Owner, and Property List

Fields — Form Name, Owner, and Property List

Views — Form Name, Owner, and Property List
Active Links, Filters, Escalations, Containers (applications, web services, packing lists, active
link guides, filter guides), Menus, and Images — Owner and Property List
A Property List is available for Fields and Views, but you might need to scroll down to see
them. For Display Properties, there is separate mask available on same screen.
b. Click OK save the updated settings and close the dialog box.
To compare staging server objects
1. In BMC Remedy Migrator, open a new server window for StagingServer.

2. In the navigation pane, select the server name to view the list of all objects on this server in the object list
view.
If you select an object type in the navigation pane, only those types of objects appear in the object list
view.
3. In the object list view, select all the overlay objects.
Sort the object list on the Customization Type column and select objects in that column that have the
value Overlay in that column.
4. Right-click and choose Differences > StagingServer.
5.
5. In the Source - Destination Mapping dialog box, click Map Overlay to Base.
The Destination Object Name column with the overlaid objects that correspond to each overlay in the
Source Object Name column.
6. Click OK to begin the comparison and generate a difference report.
The difference report indicates whether the overlay and overlaid objects differ and highlights the
properties that differ.
Related topics

Stage 7 - Upgrade applications and adjust customizations (with new overlays)
13.3.11 Stage 7 - Upgrade applications and adjust customizations with new

overlays
If you proceeded directly from stage 2 to stage 7 and you did not have overlays before performing stage 2, you do
not have customizations captured in overlays. You can perform steps 1 and 2 of this stage, and then reapply your
customizations as needed before moving to stage 8.
When you upgrade applications or system components, some objects that you have overlaid might be deleted,
which means that your overlay is deleted as well. To preserve any such overlays, you must create a copy of your
current staging server. This copy is called the upgrade comparison server (UpgradeComparisonServer).
Similarly, some of your customizations might interfere with upgraded behavior. You must adjust these
customizations before using the application.
If you have performed stage 5 to migrate origin objects from ReferenceServer to your staging server, you no
longer need the objects on ReferenceServer created in stage 4, so you can now employ that server as
If you did not migrate your unmodified origin objects to your staging server, then you want to preserve them. In
this case, employ a different server as UpgradeComparisonServer.
The following figure shows the components that are upgraded in stage 7.

To upgrade applications and adjust customizations
1. If you completed stage 5, you can reuse ReferenceServer to be UpgradComparisonServer, as follows.
a. Create a copy of the StagingServer database, which is at version 8.1.

b. Restore the copy of the StagingServer database over the ReferenceServer database. ReferenceServer
is now UpgradeComparisonServer.
Note
If you did not complete stage 5, copy StagingServer database and install a new AR System
server configured to use the copy. The new server will be UpgradeComparisonServer.
2. On StagingServer, run the BMC Remedy AR System installer again to upgrade BMC Remedy AR System
components (such as BMC Remedy Approval Server, BMC Remedy Assignment Engine, and so on).
3.
3. On StagingServer, upgrade the applications (BMC Atrium CMDB, BMC Remedy ITSM, and so on). (See the
links at the bottom of this topic.)
This might modify and possibly delete some of your overlaid objects. Modifications to these objects
performed by the upgrade do not affect your overlays and custom objects, but deletions do.
4. If any of your customizations were deleted during the upgrade of StagingServer, use BMC Remedy
Developer Studio to restore them by creating custom objects on the staging server using the overlays still
present on UpgradeComparisonServer.
Normally, an overlay that is deleted should not be replaced by a custom object because it will not be used
by the upgraded application. After reviewing the upgraded functionality, if you have overlaid objects that
should be preserved, you can preserve them by saving them as custom objects.
Note
A custom field on a deleted form is not preserved, because there is no form to contain the field.
Perform steps a and b to create custom objects for any overlaid objects that were deleted during the
upgrade that you want to preserve.
a. Compare the overlaid objects on StagingServer against the same objects on
UpgradeComparisonServer:
i. In BMC Remedy Migrator, select Tools > Options.
ii. In the BMC Remedy Migrator Options dialog box, expand Differences and select Display.
iii. Select the Display all missing objects option and make sure that all the other options are
deselected.
iv. Open a new server window for StagingServer.
v. In the navigation pane, click StagingServer to list all the objects on this server.
vi. Sort the object list on the Customization Type column and select all objects with the value
Overlay or Custom in this column.
vii. Right-click and select Differences > UpgradeComparisonServer
b. For every overlaid object that exists on UpgradeComparisonServer, but not on StagingServer, decide
whether you need the object. If you need it, use Developer Studio to duplicate the overlay manually
by saving it as a custom object on StagingServer.
5. If you have overlaid objects that were changed during the upgrade, examine your overlays and add the
functionality that was added to the overlaid objects, or remove overlays containing customizations that
you no longer want.
Removing an overlay exposes the upgraded object's functionality. To examine the overlays, compare each
upgraded origin object that is overlaid on StagingServer to the same origin object on
UpgradeComparisonServer, and compare each overlay and its overlaid origin object. You can then adjust
the overlay to achieve the behavior that you want.
Perform the needed comparisons as follows:
a. Enable the required masking options if you haven't already done so in stage 6.
b.
b. Use BMC Remedy Migrator to compare overlaid objects on StagingServer and

UpgradeComparisonServer to identify which objects were changed and what changes were made by
BMC between the versions, as follows:
i. Open a new server window for StagingServer.
ii. In the navigation pane, click StagingServer to display all the objects on this server in the object
list.
iii. Sort the object list on the Customization Type column and select all objects with the value
Overlaid.
iv. Right-click and select Differences > UpgradeComparisonServer.
The differences report provides a list of objects that have changed.
c. Keep this first instance of BMC Remedy Migrator open to examine objects in this report.
d. Use a second instance of BMC Remedy Migrator to compare overlays to overlaid objects on
UpgradeComparisonServer, as follows
Note
You need to have the BMC Remedy Migrator installed on a different computer to do this
because you can only run one instance of Migrator on a single system.
i. Open a new instance of BMC Remedy Migrator.

ii. Open a new server window for UpgradeComparisonServer.
iii. In the navigation pane, click nameOfUpgradeComparisonServer to display all the objects on
this server in the object list.
iv. Sort the object list on the Customization Type column and select objects (in the previously
created list) with the value Overlay.
v. Right-click and select Differences > UpgradeComparisonServer.

vi. In the Source-Destination Mapping window, click Map Overlay To Base to populate the
Destination Object Name column with the corresponding overlaid object for each overlay
object.
vii. Click OK to generate the difference report.

e. For each object in the difference report from step 4b, use the first Migrator instance to identify
differences resulting from the upgrade. Use the second instance to see differences between the
overlay and the overlaid object.
f. Based on these differences, use Developer Studio to delete the overlay or modify it on StagingServer.
If you want to use the new features in the latest release, delete the overlay.
If you want to retain the customizations in your current production system when you upgrade
to the latest release, merge the differences from the origin object into its overlay.

Related topics


Stage 8 - Test and promote staging server to production with new overlays
13.3.12 Stage 8 - Test and promote staging server to production with new
overlays
Performing the steps in stage 8 turns your staging server into an upgraded production server. Validate the
upgrade on the staging server with user acceptance testing (UAT).
To validate the staging server with UAT
1. Make a backup of the upgraded staging server database.

This backup is called the pre-UAT backup.
2. Conduct your UAT using your test cases.
3. If an issue arises:
a. Identify a solution, or work with BMC Support to identify a solution.
b. Apply any fixes to the server, and then validate the fixes.
c. Make a copy of the fixes for use later.
4. Complete all UAT tasks and obtain sign-off.
5. Revert to the pre-UAT backup.
6. Apply any fixes that were required during UAT.
7. Work with the database administrator responsible for the staging server to back up the database.
This backup is called the UAT-Verified-Clean backup.
8. If desired, run an additional test to validate that fixes have been applied correctly.
Note
If no issues arise, the pre-UAT backup becomes the UAT-Verified-Clean backup.
9. Restore the staging server to the UAT-Verified-Clean backup.

After the upgrade is validated on the staging server, restore the system to the UAT-Verified-Clean backup.
This ensures that any testing data used during the validation is removed and that the staging server is in a
clean state for the delta data migration.
10.

migration.

Migrating delta data after an upgrade
13.3.13 Stage 6 - Adjusting customizations when upgrading

13.4 Migrating delta data after an upgrade

The Delta Data Migration Tool is used in the last stage of the upgrade process to move data that was created or
changed after copying the production database from your production server to the staging server.
Delta data refers to any data changes that occurred on the production server during the upgrade of the staging
server. Using the staged upgrade method, a staging server is created as an exact copy of the production server at
a specific point in time. Then, the active applications on the staging server can be upgraded to the target versions
without affecting the current production server. While the staging server is being upgraded, the production server
continues to run. Then, changes that occurred on the current production database while the staging server was
being upgraded are applied. After validation, the staging server becomes the new production server. This greatly
minimizes production server downtime, because the production server needs to be taken offline only long
enough to perform the delta data migration to move the latest data onto the staging server.
13.4.1 Before you begin

Review the following prerequisites before you start delta data migration:
Supported migration paths

Infrastructure requirements for migration
Migrator tools
Install the most recent version of BMC Remedy Migrator to perform the full migration .
13.4.2 Overview of delta data migration tasks
Warning
Review carefully Restrictions after restoring the database on the staging server with overlays . If you
performed any of these tasks, you are not ready to migrate delta data!

The delta data migration comprises the following major tasks. You should perform these tasks in a
non-production environment, for validation purposes, before you perform the upgrade for the staging and
production servers. This overview assumes the staged upgrade method and focuses on migrating data from
overlay servers, although you can use delta data migration to migrate data from non-overlay servers.
1. Set up the staging server (the server where the current database backup is restored and the upgrade is
performed) with the same operating system, database and BMC Remedy AR System stack versions as are
used for the current production server (customer's old version production server).
2. Upgrade the staging server to the target software versions.
Stage 2 - Upgrade AR System server with overlays present
Stage 3 - Upgrade applications and adjust customizations with overlays present
3. Validate the upgraded staging server.
4. Restore the staging server to its state before validation, and then apply any required corrections.
6. Run the Delta Data Migration Tool to load data that changed while the staging server was being upgraded.
7. Promote the staging server to production.
8. Use the new image.
The following figure provides a high-level overview of the migration process:
The "Staging server" column shows that you start the process by setting up and upgrading the staging
server.
The "QA/Validation" column shows how you then validate the upgrade and perform the delta data
migration.
The "Production" column shows how you end the process by promoting the staging server to production.

13.4.3 Components of the Delta Data Migration Tool

The Delta Data Migration Tool that is included with BMC Remedy Migrator consists of the following components:
Configuration.xml: The file that the DeltaMigration.exe executable uses to run the correct package versions
from the Packages folder.
Note

Update the Configuration.xml file with the Migrator installed directory path:
migrator-dir="C:\Program Files\BMC Software\migrator\migrator\DeltaDataMigration"
Add C:\Program Files\BMC Software\migrator\migrator to the Path variable in your computer settings.
DeltaMigration.exe: The executable that is run to compare or migrate your data from the current
production server to the staging server (new production server).
The Delta Data Migration Tool consists of the following folders, which are store under
<MigratorInstallFolder>\Migrator\migrator\DeltaDataMigration:
Packages: Contains the package, instruction XML files and the mapping files for all supported versions of
the following products. See also the section below, "What is included in the application package."
BMC Remedy AR System
BMC Atrium
BMC Remedy ITSM
Utilities: Contains two utilities that can be used to find and package custom forms from your server:
Custom forms packaging utility
A count utility (AREntryCounter)
Note
Do not modify the contents of any folders, unless directed to do so by BMC.
13.4.4 What is included in the application package

Each application package (BMC Remedy AR System, BMC Atrium Core, BMC Remedy ITSM Suite, BMC Service
Request Management, and BMC Service Level Management) includes:
One package XML file: Lists the instruction files that need to be executed in order.
Many instruction XML files: Provide details for the forms that have data that is being migrated. Each
package XML file references one or more of these instruction files.
.arm files: The field mapping files. One or more instruction files refer to these .arm files.
The instruction files contain the following information specified for each form:
Source and destination form name

Unique field IDs

Qualification to be used to migrate the data:
'6' >= "<DATE>"
which is Last Modified Date.
A migrate option, which is set to Update (This option updates existing records if the same record is already
present and creates new records if the same record is not present.)
An option set to not trigger any workflow during the migration
Mapping files are created in these situations:
For forms that need mappings for newly created required fields (fields where a default value is required) in
applications
For any field needs to be mapped to a different field in the destination server
For handling data transformation changes between product versions
If no mapping files are referenced in the instruction files for a form, the migrator moves data from all fields on the
production server to the staging server.
Following is an example instruction XML file:
<data enabled="true" source-form="FIN:ConfigRules" destination-form="FIN:ConfigRules" type="dat
<qualification>PASS_QUALIFICATION</qualification>
<unique-fields> <field id="270002020"> <field id="1000000001"> </unique-fields>
<ports enabled="true" list="LIST_PORT" fast="FAST_PORT"> </ports>
</data>
A package XML file is created that lists the instruction XML files and specifies their execution order.

Using the AREntryCounter utility
Extending Delta Data Migration to include customizations

Supported migration paths

13.4.7 Supported migration paths

The following table lists the earliest version from which a product can be migrated to the current version.
Product Earliest supported version that data can be migrated from
BMC Remedy AR System 7.0.1
BMC Atrium Core 2.0.1
BMC Atrium Integrator 8.0.00
BMC Remedy ITSM applications 7.0.02
BMC Service Request Management 2.2
BMC Service Level Management 7.1
BMC Remedy Knowledge Management 7.6.03
BMC Service Impact Manager 7.1
Integration for BMC Remedy Service Desk 7.1
BMC ProactiveNet Performance Management 8.5

Infrastructure requirements for migration
13.4.8 Infrastructure requirements for migration

The following table describes the minimum infrastructure required for system and database migration.
Migration Requirements
system
or
database
Staging A clone of your production environment that you create by copying objects from your current production server. You will promote this
server system to your production system after the migration.
Staging A database instance on the staging server that is sufficiently sized for production use, is compatible with the current production server
server database instance, and allows for restoration of a backup.
database
instance
Mid tier A mid tier server that is sufficiently sized for production use.
server
Microsoft A Windows server for running the Delta Data Migration tool. This server should have a minimum of 2 CPUs, 4 GB memory, and 40 GB
Windows disk space.
server
Note

Migration Requirements
system
or
database
It is preferable to have this Windows server on the same local area network (LAN) segment. If the Windows server will reside
outside of the LAN segment, BMC recommends that you deploy a separate server for the Delta Data Migration tool, and that
server should run on the same LAN segment as the current production and staging servers. Alternatively, if you do not have an
additional Windows server, you can use the mid tier server as the host for the BMC Remedy Migrator and the Delta Data
Migration tool (which is bundled with BMC Remedy Migrator).

Migrator tools
13.4.9 Migrator tools

Note


Installing BMC Remedy Migrator for migrating delta data
Installing BMC Remedy Migrator for migrating delta data

Use the following procedure to install BMC Remedy Migrator. You use the Delta Data Migration Tool installed
with BMC Remedy Migrator to migrate delta data.
Note
You must have administrator privileges for the machine on which you are installing BMC Remedy
Migrator. You must install BMC Remedy Migrator 8.1 and the latest binary fix to perform the full
migration.
Always download and install the latest BMC Remedy Migrator version available when you are
migrating delta data.
To install BMC Remedy Migrator
1. Shut down all other running applications before you start.

2. Insert the BMC Remedy Migrator DVD into your DVD drive.
If the BMC Remedy Migrator setup program starts a few seconds after inserting the disk, skip to step 4 or
follow the on-screen instructions.
3. From your DVD drive, double-click setup.exe.
A progress bar appears as the files are extracted.
4. Click Next when you see the Welcome screen.
5. In the License Information dialog box, read the
license agreement, and click Agree.
For more information about licensing, see Configuring BMC Remedy Migrator and Working with BMC
Remedy AR System licenses.
6. Perform either of the following actions:
Click Next to accept the default installation directory.
Click Browse to select another installation directory.
7. Click Next.
8. Click the check box to place the BMC Remedy Migrator program icon on your desktop, and click Next.
9. Review the installation options you selected; if they are correct, click Install to begin the installation.
Note

You might see validation warnings related to the mfc71.dll, mfc71u.dll, and msv1_0.dll2 files.
These warnings can be ignored because they do not affect the ability of BMC Remedy Migrator to
be installed.
10. When installation is complete, click Done. (Optionally, you can click View Log to see the installation log.)
To begin using BMC Remedy Migrator, you must restart your computer.

Preparing the source and destination servers for Delta Data Migration
13.4.10 Preparing the source and destination servers for Delta Data
Migration
migration. Perform the following procedures to prepare your source and destination servers for the Delta Data
Migration Tool.

Server configuration adjustments
Server configuration adjustments

Before running the Delta Data Migration Tool, perform the following server configuration adjustments.
Adjustments for the destination server
Note
Leave the configuration as is until after you complete the delta data migration.
Make the following adjustments on the destination server:
Set the Max Entries Returned by GetList parameter to 0 on the Configuration tab to cover all delta data in
the forms. After completing the delta data migration process, be sure to set this parameter back to the
original value.
Disable the Distributed Server Option (DSO) on all application servers.
Disable escalations on all application servers.
Disable all database triggers within the BMC Remedy AR System schema. Work with your database
administrator to disable the triggers.

To help increase the delta data migration performance, configure the following items on the the Server
Information page of the AR System Administration Console. After running the delta data migration, you
should set all of these items back to their values from before you make these changes.
Select the Disable FTS Indexer and Disable Full Text Searching check boxes on the FTS tab.
Unselect the Localize Server check box on the Advanced tab. If you leave this box selected, the
migration tool looks for localized data twice, which has a significant impact on system performance.
Set the isolation level for MS SQL Server on the source and destination server databases. Otherwise, data
in forms is not migrated successfully and you might see an error like this in the HTML log files:
11/22/2011 17:51:07 1612 *ERROR* Migrations 17:51:07 : An Error Occured with Data 'NTE:Not
17:51:07 1612 *ERROR* Migrations 17:51:07 : [4][The SQL database operation failed. The ROL
If it is not already set correctly, set the isolation level for MS SQL Server databases on the source and
destination server as follows:
1. Run the following commands from the SQL Server Management Studio:
SELECT snapshot_isolation_state FROM sys.databases where name = 'ARSystem'

2. If the commands return 0, stop the AR System server, and run the following ALTER commands. (If
the AR System server is running, the ALTER commands might take a long time to complete.)
ALTER DATABASE ARSystem SET ALLOW_SNAPSHOT_ISOLATION ON

Adjustments for the source server
Note
Leave the configuration as is until after you complete the delta data migration.
For initial runs of the Delta Data Migration Tool, make the following adjustment on the source server.
Set the Max Entries Returned by GetList parameter to 0 on the Configuration tab to cover all delta data in
the forms. After completing the delta data migration process, be sure to set this parameter back to the
original value.
Optionally, you can make the adjustments listed in the previous section, "Adjustments for the destination server."
For the final run of the Delta Data Migration Tool:
Make all of the adjustments listed in the previous section, "Adjustments for the destination server."

For forms where the amount of data is large and the total number of records is greater than 1 million,
create the index at the database level in the T table, and index field ID 6 (Last Modified Date). An additional
index is required for delta data migration purposes.
Important
After the final delta data migration run is completed, you must revert the previous changes back to their
original state.
Related topics
Configuring BMC Remedy Distributed Server Option
Definition for Disable Escalations in Setting administrative options

Resolving issues before performing the migration
Resolving issues before performing the migration

Before performing the migration, resolve the following issues.
Issue 1
The BMC Service Impact Manager or BMC ProactiveNet Performance Management applications have the same
application GUID. If these applications are installed on the same server, you must update the configuration XML
file because both applications have the same application GUID.
To resolve issue 1:
1. Go to the folder where BMC Remedy Migration is installed: <MigratorInstallFolder>\DeltaDataMigration

2. Open the configuration XML file.
3. Perform one of the following actions:
If BMC ProactiveNet Performance Management is installed, comment out the SIM code lines.
If BMC Service Impact Manager is installed, comment out the BPPM code lines.
For example, to comment out the BPPM code lines, insert <!- and -> tags as follows:




Issue 2
BMC Service Impact Manager depends on BMC Atrium Core being installed. You cannot migrate BMC Service
Impact Manager and BMC Atrium Core at the same time.
To resolve issue 2:
If you have installed BMC Service Impact Manager, perform the delta data migration for BMC Atrium Core before
you run the Delta Data Migration Tool for BMC Service Impact Manager.
Issue 3
Note
This issue applies only if you have installed version 7.1 of Integration for BMC Remedy Service Desk on
your production server.
Integration for BMC Remedy Service Desk 7.1 is not registered in the SHARE:Application_Properties form, so the
Delta Data Migration tool cannot detect the integration for BMC Remedy Service Desk 7.1 installation on the
production server.
To resolve issue 3:
1. Create an entry for Integration for BMC Remedy Service Desk 7.1 in the SHARE:Application_Properties
form.
2. Import the SW00388960_fix.arx file from the <Migrator Install
folder>\DeltaDataMigration\Utilities\pre_DDM folder.
Issue 4
Some data did not migrate due to change in selection field values in an upgrade for
CTM:CFG-ApplicationPreferences form data.
The CTM_CFG_ApplicationPreferences form has Reopen_ fields (one for each application — BMC Remedy
Incident, BMC Remedy Change, and so on). The Reopen_ field had a No Action value in versions 7.6.03 and
earlier. This value was removed from version 7.6.04 and higher, as part of an upgrade.
If you are upgrading to 7.6.04 or higher, to map the selection value, run the following UPDATE SQL statement on
the production system before you begin the delta data migration:
ctm_app_pref_update.sql
Note

If you are upgrading from BMC Remedy IT Service Management 7.6.04 or later, you do not need to run
this statement.
Use the SQL statements in the <MigratorInstallfolder>\DeltaDataMigration\Utilities\pre_DDM folder to execute

on the production system (as this is the same UPDATE SQL used in the upgrade), and this will update the delta
records that have the issue. During an upgrade, the installer updates other records by calling the UPDATE SQL
statement through a filter.
The SELECT SQL statement will give you the number of records to update.
The UPDATE SQL statement will fix the mapping.
Work with your database administrator to execute these ANSI SQL scripts on the database.
Note
These issues do not result in loss of functionality. These fixes are required to ensure that the delta data
migration does not produce errors.
To resolve issue 4:
Apply the SQL fixes as directed in the
<MigratorInstallfolder>\DeltaDataMigration\Utilities\pre_DDM\Readme_for_Ctm_App_Pref_Sql_Fix.txt
file.
Issue 5
Some data in these forms will not be migrated on the following forms.
Note
These issues do not result in loss of functionality. These fixes are required to ensure that delta data
migration does not produce errors.
On the TMS:Task form, the Seconds_before_Time_Out hidden field is designed to accept values between 0
and 2147483647. Occasionally, this field can be set inappropriately to negative values through workflow.
When BMC Remedy Migrator uses the BMC Remedy AR System API to conduct its activities, the field
definition violations are not allowed. This results in errors and data not being migrated.
On the TMS:Summary data form, the Task or Task Group Status field accepts values between 1000 and
7000. Occasionally, this field can be set inappropriately to values of 0 and 1 through workflow. When BMC
Remedy Migrator uses the BMC Remedy AR System API to conduct its activities, the field definition
violations are not allowed. This results in errors and data not being migrated.

On the CTM:People form, the Open Tasks field is designed to accept values between 0 and 2147483647.
Occasionally, this field can be set inappropriately to negative values through workflow. When BMC Remedy
Migrator uses the BMC Remedy AR System API to conduct its activities, the field definition violations are
not allowed. This results in errors and data not being migrated.
To resolve issue 5:
Work with your database administrator to execute the following ANSI SQL scripts on the database:
1. From the <MigratorInstallfolder>\DeltaDataMigration\Utilities\pre_DDM folder, extract the tms_select.sql

and tms_update.sql scripts.
2. Execute the tms_select.sql script.
3. If records are reported or found, execute the tms_update.sql script to correct the data.
Note
If running on a DB2 database, replace the corresponding T table names in the form names in
tms_update.sql.


You can use the AREntryCounter utility to estimate total data size and delta data migration run time. The utility
allows you to get the number of entries in the forms that are part of the DDM package. The utility can be run in
the following ways:
Before delta data migration: You can run it to get the counts for all the forms for the date for which you
want to use delta data migration. This gives you an idea of the total amount of data you have in your forms
and how long delta data migration might take to migrate that data.
After delta data migration: You can run it to get the total counts for all the forms that delta data migration
used. You can run it for your source and destination servers separately and compare the counts.
<options> value Definitions
-d <DDM date> Count entries that were created or modified after a specific date
The <DDM date> format is as follows:
mm/dd/yy hh:mm:ss
For example:

<options> value Definitions
06/14/12 11:57:29
-k <package> Construct the form list from the given Migrator package file
-o <output file> The output file for the result report
-p <password> The password for authenticating with the AR System server
-s <server> The AR System server name
-u <user> The user name for authenticating with the AR System server
-x <port> The AR System server port.
Use the following syntax to run the utility for your package files (forms). Make sure to replace the keywords with
your Migrator installation path and the server and version information.
Run the utility from the \DeltaDataMigration\Utilities\migratorutilities folder from a command prompt. You must
run the counts for each product. The output file is available in the same folder where you ran the Delta Data
Migration Tool.
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\ARCore\<YOUR VERS
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\Atrium\CMDB\<YOUR
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\Atrium\AIE\<YOUR
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\Atrium\ProductCat
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\ITSM\<YOUR VERSIO

AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\SRM\<YOUR VERSION
AREntryCounter.bat -k "<MigratorInstallationPath>\DeltaDataMigration\Packages\SLM\<YOUR VERSION

Making modifications for Remedy Knowledge Management 7.5.x
Making modifications for Remedy Knowledge Management 7.5.x

If you are using Remedy Knowledge Management 7.5.x in your current production environment, make the
following modifications to the custom Custom_Form_Instruction.xml located under the Packages\Custom
folder.
Note
If you are using a version earlier than 7.5.x, the Delta Data Migration Tool is not supported. However, you
need bring over the KMS:Associations form data from your current production system to the staging
server to enable the integration of the Knowledge Management System with BMC Service desk
applications, as described in the following procedure.
1. Modify the Custom_Form_Instruction.xml file, and add the data element for the KMS:Associations with the
unique ID set to 179.
2. Follow the standard delta data migration process to migrate the custom application data and all other
application data.

Performing the data migration
13.4.11 Performing the data migration

When migrating your data, observe the following guidelines:

Use the same Admin user account to log in to both servers. The upgrade environment is a database restore
of the production environment. BMC recommends that you use one user to do this migration, which will
help to track and debug issues. If you use Demo, ensure that you have the same password for both servers
for that Admin account.
You can run the Delta Data Migration Tool one time or multiple times. BMC recommends that you run the
tool at least twice — before you start your production outage, and again after the production outage
begins. The first data migration moves all of the data that has been added or changed since you made the
production backup. The second migration moves only the data that has changed since you started the first
data migration. This ensures that the time required to do the data migration (your outage window) is as
small as possible.
This topic includes the following sections:
Before you begin

To migrate data
Related topics
Before you begin

If you have forms that contain large amounts of data and you want to know the total numbers of records that are
migrated or you want to improve performance, you can set the following configuration settings before running
delta data migration.
The BMC Remedy Migrator Migrator Configuration.xml file (located in the * migrator* folder under <
MigratorInstalledDirectory>) contains the count-enabled attribute which executes select count(*) queries by
default and calculates the percentage completion (for every 100 records) that is shown in the MigratorCLI
command window.
To improve performance if you have a large number of records, you can set the attribute to false, which means
that you only see the total number of records processed instead of the percentage. For example:
<count enabled="false" />
Note
After you set this configuration, you no longer can see what percentage of migration is finished while
delta data migration is running.
To see the percentage of migration completed information while delta data migration is running, set
count enabled back to true.
To migrate data
Use the Delta Data Migration Tool to migrate data from the production server (source server) to the staging server
(destination server) as follows:

1. Go to the <MigratorInstallFolder>\DeltaDataMigration folder.

2. Double-click the DeltaMigration.exe file to open the Delta Migrations window.
3. Click the button next to the Source Server field to open the Server dialog box.
4. Complete the following fields:

Source Server — The source server name (production server).
User Name — The user name of the source server and destination servers. The user name should be
the same.
Password — The password of the source server and destination servers. The password should be the
same.
TCP Port — The default value used by the script. If no port is specified, the default is 0.
Fast/List Port — The default is 390635.
5. Click OK.
6. Click the button next to the Destination Server field to open the Server dialog box.
7. Enter the destination server (staging server) information, and click OK.
The Delta Data Migration tool validates the versions on your source and destination servers. It provides a
list of all supported BMC Remedy AR Server products and applications. Applications shown in red indicate
that an appropriate package was not found or is not applicable for your server.

After you click the Migrate or Compare button, the DeltaMigration.log file is created and includes
information about the source and destination servers, the products you selected, date parameters, and the
option that you selected (Migrate or Compare). You can find this file in the same location where you ran
the .exe file for Delta Data Migration Tool.
Note
The destination server data will probably not be consistent until all the data up to the current time
is migrated. You can migrate the data in one or more "chunks" (using the Start Date and End Date
fields in the Delta Data Migration Tool to specify the range of data to migrate).
To ensure that the destination server data is consistent, enter an empty date range (which means
the current time stamp) in the End Date field to migrate the final chunk of data.
8. Make sure that the Re-run applications with previous criteria & instructions check box is selected.
This check box is selected by default and should remain selected even if you are re-running the migration
after fixing any data issues.
Note
If you are using the multi-run approach to migrate to minimize your downtime, clear the Re-run
applications with previous criteria & instructions check box after confirming that the previous
delta data migration is error free and has successfully completed.
At this point, delta data migration will migrate based on the new date and selection criteria that
you have specified. If the previous delta data migration had errors, then fix the errors and run the
delta data migration again with the Re-run applications with previous criteria & instructions check
box selected.
Then, the delta data migration will be based solely on the time stamp.
9. Select all applications that are not shown in red.

10. In the Fetch Data/Objects Created/Modified After Date fields, use the Start Date and End Date fields to
enter a range of dates (so that you can migrate a "chunk" of data).
The dates allow you to migrate only those records that were modified or created in that date range.
a. In Start Date, enter the timestamp from when you want to transfer the data.
Data in the forms that are greater than or equal to this timestamp are migrated.
Note
To account for daylight savings time, enter enter the Start Date and End Date with a
time stamp that is greater than 12:00:00 midnight (for example, 1:00:00 AM).

If this is the first time you are running the migration, the timestamp that applies is
when the production server backup was used to create the staging server. If this is a
multiple-run scenario, the timestamp that applies is when you initiated the previous
run.
b. In End Date, enter the date with the timestamp to when you want to transfer the data (for example,
12/20/2012 1:00:00 AM).
You can run the migration multiple times as needed to finish the delta data. For the final migration,
do not enter an end date.
11. If you are not migrating custom forms data, you can unselect the Custom in the application name list.
12. When you perform the final delta data migration, select Data count validation to generate a report:
This field (not selected by default) validates the data count from the source and the destination servers and
ensures that the counts match. When you finish, navigate to the Working\Logs folder (by default, <
MigratorInstallDir>\DeltaDataMigration\Working\Logs) to review the Count_statistics.csv file. The report
lists:
Source form name
Destination form name
Qualification
Source record count
Destination record count
Semicolon separated string that lists the errors information with unique index field values for entries
that were not migrated from source server due to the errors.
Note
If you see errors in the report, see Reviewing the migration results and resolving issues to fix
them.
13. Click Migrate or Compare.

Click Migrate to start the data migration.
All delta data is transferred from the source server to the destination server.
Click Compare to create a comparison result report.
This report can be used to identify all data that has been created or updated in the source server
during the delta time period.
The comparison script generates an .xml result file for each instruction xml file with the instruction
name and suffix _Compare. For example:
Remedy_Service_Request_Management_Compare.xml
The script generates compare .xml result files for each instruction .xml file. These files include all
data entries that are either different (records updated in the source server during the delta period) or
missing (records created in the source server during the delta period) in the destination server.
The Delta Migration window displays and shows the parameters that will be used by the Migrator.
14.
14. Click Yes to continue with the migration or comparison.

One command window is launched for each application you are running. The windows close automatically
when the process is done or if there is an error.
If you click No, the migration or comparison is cancelled.
Note
If you want to re-run the migration or the comparison, you must wait for all of the command
prompts windows to close before executing a new run.
The command output is available as an HTML log file.
Related topics
Performing the data migration for server groups

Reviewing the migration results and resolving issues
13.4.12 Reviewing the migration results and resolving issues

This page lists activities you should perform after you migrate:
Threshold set for errors

Reviewing log files
Reviewing errors
Resolving unique index violations
Benign migration errors
Related topics
Threshold set for errors

If a form encounters more than a 1000 errors during the delta data migration run, then delta data migration stops
migration of the form and continues with the next one. After you fix the cause of errors, then re-run delta data
migration with the same product selections and date. Delta data migration re-runs for any failed forms and failed
records.
Reviewing log files

After you run the Delta Data Migration (DDM) Tool, you will see a Working folder under
<MigratorInstallFolder>\DeltaDataMigration. This folder contain the package and instruction xml files for all your

products. Under the Working folder, a Logs folder holds the .html, Compare.xml and .mgrresult files. These files
are discussed below.
The DDM tool creates HTML-based log files by using the package names that have the .html suffix:
Migrate.html
Compare.html
Search the HTML log files for the following keywords:
ERROR — Lists the form information and data for a server, API, or SQL error.
WARNING or WARN — Describes warnings from BMC Remedy AR System that do not stop the package
migration.
The DDM tool also creates .mgrresult files and comparison output XML files:
Migrate script details — The migrate script creates a .mgrresult file for each instruction with the instruction
name and suffix _Migrate that includes the results of migrating all the form data (entries). The file lists the
number of entries that were migrated for each form and includes the same error information (if any) that
the HTML log file contains.Open this file with BMC Remedy Migrator. Examples of BMC Remedy Migrator
output file names are:
ITSM_Package_Migrate.html — The migrator log file (you will have one of these for each package).
Remedy_Service_Request_Management_Migrate.mgrresult — The migrator result file (you will have
one of these for each instruction file).
Compare script details — Apart from the HTML log file, the comparison script also creates an .xml result file
for each instruction with the instruction name and suffix _Compare. These files include all data entries that
are either different or missing in the destination server. (A comparison that is run after a successful
migration should not report any differences in form data, but the report will show differences if a field's
data type was changed even if the data is the same.)
Examples of compare output file names are:
ITSM_Package_Compare.html — The compare log file (you will have one of these for each package).
Remedy_Service_Request_Management_Compare.xml — The compare .xml result file (you will have
one of these for each instruction file).
Reviewing errors
This section lists the known errors and warnings that might occur in your log files. Check the log files for errors
and contact Customer Support as needed for assistance.
The following warning in the SRM_Package_Migrate and SRM_Package_Compare HTML files can be ignored:
Keyword Error Description
WARN Instruction The Form Name defined in the mapping file is not the same as specified in the Instruction File.
Interpreter This warning occurs due to data migrating from the SRM:CFG_Rules Form on the production server to a different
form on the staging server.

The following error in the SLM_Package_Migrate, SRM_Package_Migrate, SLM_Package_Compare and

SRM_Package_Compare HTML files can be ignored:
ERROR Comparison Form does not exist on server: INT:SLMSRS:ConfigServiceTarget:Defaults.

Generator The error is displayed if BMC Service Level Management or BMC Service Request Management integration is not
present.
The following error in the Atriumpackage_Migrate and Atriumpackage_Compare HTML files can be ignored if
BMC Atrium Integration Engine or Enterprise Integration Engine is not installed in your servers:
ERROR Migrations [ars81:4] - [ars81:303]-[Form does not exist on server EIE:ApplicationSettings]

This error results from the form being not available in the server.
The following errors in the BMC Remedy Foundation Elements_Migrate and BMC Remedy Foundation
Elements_Compare HTML files can be ignored:
ERROR Migrations An Error Occurred with Data 'CFG:Geography State-Province'
ERROR Migrations [ars81:4] - [ars81:303]-[Form does not exist on server CFG:Geography State-Province]
Form names for these forms and the CFG:Pred-Succ Associations form had a slash (/ ) in their names, which was
changed to a hyphen (-) in BMC Remedy ITSM Suite 7.0.3 Patch 010 and later. Depending on your version, you
might see an error for the form name that contains either ‘ / ‘ or ‘ -‘. This can be ignored because the data will be
migrated with the form name that matches your server.
The following errors in the ITSM_Foundation_Migrate and ITSM_Foundation_Compare HTML files can be ignored
if the forms are not on your source server:
ERROR Migrations An Error Occurred with Data 'AST:AssetAdvancedSearchCriteria
ERROR Migrations [ars81:4] - [ars81:303]-[Form does not exist on server AST:AssetAdvancedSearchCriteria]
ERROR Migrations An Error Occurred with Data ' AST:CILifeCycleStatus '
ERROR Migrations [ars81:4] - [ars81:303]-[Form does not exist on server 'AST:CILifeCycleStatus']
The following errors in the BMC Remedy Task_Management_Migrate and BMC Remedy Task_Management
_Compare HTML files can be ignored if the forms are not on your source server:
ERROR Migrations An Error Occurred with Data 'TMS:RelationshipsInterface_Create'
ERROR Migrations [ars81:4] - [ars81:303] - [Form does not exist on server 'TMS:RelationshipsInterface_Create']

The following errors in the BMC Remedy Foundation Elements_Migrate and BMC Remedy Foundation
Element_Compare HTML files can be ignored if the forms are not on your source server:
ERROR Migrations An Error Occurred with Data 'CFG:HTMLCatalog'
ERROR Migrations [ars81:4] - [ars81:303]-[Form does not exist on server 'CFG:HTMLCatalog']
If you run a compare report after a successful migration, then no data with "state=different" or missing data is
expected. The compare report should not report any differences.
The Remedy_Contract_Management_<datetime>_compare.xml output file might report the following
differences, which can be ignored because the source server does not have default value data for the fields listed.
However, the destination server does have this data.
<data destination-form="CTR:ContractBase" source-form="CTR:ContractBase" unique-field-id="179">
<field id="260600003" name="Purchase Cost" state="different" />

<field id="260600004" name="Renewal Cost" state="different" />
<field id="270002042" name="Cost per Asset" state="different" />
<field id="270002043" name="Cost per Component" state="different" />
If you are migrating data from BMC Remedy ITSM versions 7.0.02 or 7.0.03 with or without patches, you will see
the following errors in the ITSM_Foundation_migrate_<datetime>.html file. This is a known issue that occurs
because data migration in the APR:Approver Lookup and APR:SYS-Approval Definition forms is not supported.
The following errors might appear for the APR:Approver Lookup form:
ERROR Migrations An Error Occurred with Data 'APR:Approver Lookup'
ERROR Migrations [ars81:4] - [ars81:986] - [ars81:Currency fields can not be used for grouping.]
The following errors might appear for the APR:SYS-Approval Definition form:
ERROR Migrations An Error Occurred with Data 'APR:SYS-Approval Definition'
ERROR Migrations [ars81:4] - [ars81:985] - [ars81:No active Currency Code found on the Currency Code form.]
If you are migrating data from BMC Remedy ITSM versions 7.0.02 or 7.0.03 with or without patches, you will see
the following errors in the ITSM_Change_Management_migrate_<datetime>.html,
ITSM_Change_Management_compare_<datetime>.html, and
Remedy_Change_Worklog_DetailDesc_Null_<datetime>_migrate.mgrresult files. You can ignore these errors as
the form does not exist on your source server.

ERROR Migrations An error occurred with Data RMS:WorkLog
ERROR Migrations [ars81:4]-[ars81:303]-[Form does not exist on server RMS:WorkLog]
If your source BMC Service Request Management version is 2.2 or 2.2 patch 1, you might see the following errors
in the .html log file, and you can ignore these errors as they are benign.
ERROR Migrations An Error Occurred with Data 'WOI:Associations'
ERROR Migrations [ars81:4] - [ars81:303] - [Form does not exist on server WOI:Associations]
The SRD:AuditDisplay form is not to be updated during the delta data period, so the following errors can be
ignored:
ERROR Migrations An Error Occurred with Data 'SRD:AuditDisplay'
ERROR Migrations for this form does not match that in owning application SRD:AuditDisplay]
ERROR Migrations [ars81:4] - [ars81:9858] - [ars81:The application is not licensed Remedy Service Request and Catalog System]
Resolving unique index violations

A unique index violation can happen in the following scenarios:
The request ID coming from the source server is already used by another record in the destination server.
This can happen if the same record is already on the destination server, but is using a different ID.
The request ID is not used, but the GUID (value for field 179) or the unique indexed field of that form is
used by another record in the destination server. This can be caused by test data created on the destination
server, which has the same ID as an item being imported.
These situations can occur if test data is created on the destination server but is not reverted to a clean state, or if
an escalation or a process (such as from Atrium Integration Engine, DSO, or Reconcilation Engine) has not been
disabled and created these records on the destination server.
An error looks something like this:
ERROR Migrations 07:01:32 : [4][The value(s) for this entry violate a unique index that has bee
To resolve index violations
1. Delete the records with the duplicate indexes from the destination server.
a. Find the entry ID (field ID 1) in the error message.
b. Search the source server for a record with that field ID.
c.
1.
c. Find the fields and the values of the unique index fields from that form.
d. On the destination server, run a search with those values (not with the field ID 1).
e. Review the data and see if the values for Field ID 1 and field 179 are different.
f. Look for the Last Modified By and Date to confirm who created or updated the record.
g. After you confirm that it is a duplicate, delete the record on the destination server.
2. Run the Delta Data Migration Tool again with same product selections and date used, so that DDM can
look into the working folder instruction xml files and only process records in forms that had errors.
You should choose all the products or applications you selected during the previous run even if some of
them did not have errors for the re-run. Otherwise, the working folder is replaced and DDM is not be able
to process only the records with errors.
Benign migration errors

In any form, you might see the following errors:
ERROR Migrations [Migration failed for schema BMC.CORE:BMC_BaseElement. Entry missing for entry id :000000023575792]
ERROR Migrations An Error Occured with Data 'BMC.CORE:BMC_BaseElement'
ERROR Comparison Form does not exist on server: CMDB.SC:ServiceContextAuthenticationInfo

Generator
ERROR Migrations If your source (current production) server is running BMC Atrium 7.6.0.3, you might encounter the following error in the
Product_Catalog_package_Migrator and Product_Catalog _package_Compare HTML files:
[4] -[303] -[Form does not exist on server PCT:TrustedDataset]
This form exists on the destination (upgraded) server but is not available in Atrium 7.6.03 version, so you can safely ignore
this benign error.
These errors are benign, and you can safely ignore them. The Delta Data Migration Tool is run with a live source
server, and you have not yet committed the record ID that the utility is trying to migrate. Therefore, the record ID
so not in the source server's database yet.
Related topics
Restrictions after restoring the database on the staging server with overlays

13.4.13 Extending Delta Data Migration to include customizations

You can add custom forms to the Delta Data Migration package so that you can migrate the data in these custom
forms. You can do this manually or with the Customer Form Instruction Generation tool.

You can also update a field mapping file to correct customer-defined fields in the BMC Remedy reserved range.
Manually adding custom forms to the package
1. Open the Custom_Form_Instructions.xml instruction file in the

<migratorInstallFolder>\DeltaDataMigration\Packages\Custom folder.
The file will contain information that is similar to the instructions XML example.
2. Provide your custom form name and the unique field IDs (unique index field IDs) in their respective tags.
Follow the same process for all of the forms that you need to add.
3. Open the Custom_Form_Package.xml package file in the
<migratorInstallFolder>\DeltaDataMigration\Packages\Custom folder.
4. Provide the instruction XML file names in the package XML file:
<instructions file="Custom_Form_Instructions.xml type="all" command="migrate" enabled="tru
<instruction name="Custom_Form_Instructions"> </instructions>
5. Save the instruction and package XML files.

Now, you are ready to run the migrate and compare scripts for the custom package. The new package will
run in parallel in a separate command window in the same way as the Delta Data Migration out-of-the-box
package files.
Adding custom forms to the package by using the Customer Form Instruction
Generation tool
If you do not have the list of your custom (non-BMC) regular forms, run the following batch files as outlined in
the following procedure:
The migratorFindCustomForms.bat utility — Finds all of your custom forms from the AR System server that
are not recognized as BMC Software forms. The utility generates a CSV file that includes the list of all
custom form names with their unique indexes.
The migratorCSV2Instructions.bat utility — Uses the generated CSV file as the input, and creates the
Custom_Form_Instructions.xml file for the custom forms in the CSV file.
To add custom forms to the package by using the Customer Form Instruction Generation tool
1. Navigate to the <MigratorInstallFolder>\Migrator\migrator\DeltaDataMigration\Utilities\migratorUtilities

folder.
2. Run the migratorFindCustomForms utility by using the following syntax:
migratorFindCustomForms.bat -s <sourceARServerName> -u <adminUserID> -p <adminPassword> -P
For example:
migratorFindCustomForms.bat -s test.bmc.com -u Demo -p "" -P 2020

3. Open the Customforms.csv output file in a text editor or spreadsheet application.

4. If a form is included in the list but should not be migrated, remove the entire line.
Forms that are used for testing or to keep temporary data should not be included. If you are not sure, it is
better to include the form in the migration. Migrating a form multiple times is permitted.
Note
You can save the names of forms to be excluded in a separate file, then you can use that file the
next time you run migratorFindCustomForms.
5. Save the changes you made to the Customforms.csv file.

6. Run the migratorCSV2Instructions utility by using the following syntax:
migratorCSV2Instructions.bat -i Customforms.csv
For example:
migratorCSV2Instructions.bat -i Customforms.csv
This utility generates an instruction file that BMC Remedy Migrator reads and uses for the migration.
7. Verify that the output file is Custom_Form_Instructions.xml.
8. Open Custom_Form_Instructions.xml file, and ensure that the name inside of the xml file has the same
name "Custom_Form_Instructions."
9. Copy the Custom_Form_Instructions.xml files to the Packages\Custom directory. (You can overwrite the
same file in the directory.)
Now, the custom package is ready to be used. On the DDM user interface, when you select Custom, this
custom package is selected, and the migration for the custom forms is executed.
Updating a field mapping file if you ran ARCHGID utility before or during an upgrade
If you used the BMC Remedy AR System ARCHGID utility to to fix customer-defined fields in the BMC Remedy
reserved range and a field ID was updated, you must add the source and destination field mapping information in
a field mapping .arm file.
To create or update an .arm file and update the reference in the instruction XML file
Warning
Perform these steps only if you used the ARCHGID utility.
1.
1. Under the packages folder, open the custom package folder.

2. Open the instruction file that needs its form mapping information to be updated.
For some reason, if you have more than one instruction file, open the file which contains the form for
which the delta data mapping is available.
3. Create a mapping (.arm) file and map the custom source field ID to the destination field ID (which has a
new ID after running the ARCHGID utility).
The following figure shows an example of a mapping file:
4. Add the mapping file name to the form reference in the instruction file, as shown in the following example:

Post-migration procedures

13.4.14 Performing the data migration for server groups

1. Perform the delta data migration on the primary staging server.
At this point, the outage window has begun and the final data migration is complete.
If you are using a load balancer in front of the mid tiers, make all mid tiers are unavailable in the load
balancer.
If you are using a load balancer between the mid tiers and the BMC Remedy AR System servers,
make all BMC Remedy AR System servers unavailable in the load balancer.
2. Stop all AR System servers in the server group.
3. Promote the staging server to the production server group.
a. Rename the staging server to the same host name as the production administration server.
The staging server will replace the original administration server in the server group.
b. Restart the AR System server.
c. Make the administration server available in the load balancer.
d. Verify that you can connect to the administration server by using the AR System server Virtual IP
(VIP).
4. If you have not already done so, upgrade one of the mid tier servers.
Note
Because the mid tier server is backwards compatible, you can the upgrade the mid tier servers
before the AR System server upgrades.
a. After the upgrade, flush the mid tier cache to update it for the latest release.
b. After the mid tier cache is refreshed, make the mid tier available in the load balancer.
c. Verify that you can connect to the AR System server through the mid tier VIP.
At this point, the production environment is running in a diminished capacity (there is one mid tier
and one AR System server).
5. Upgrade each secondary AR System server in the server group.
a. Point the database client to the newly-upgraded database instance that is set up on the staging
server.
This is the new production database.
b. If needed, update the BMC Remedy AR System server configuration file with the new database
connection information.
c. Upgrade each BMC Remedy components by following the upgrade instructions provided with each
component.
Follow any special instructions related to server group environments. Upgrade in the following
order:
BMC Atrium

BMC Remedy ITSM

d. Verify that you can connect directly to this AR System server.
e. Make each AR System server available in the load balancer.
6. Upgrade the remaining mid tier servers by following the procedure in step 4.
Note
This step should be done in parallel with the upgrade of the secondary AR System server, or
before beginning the upgrade of the production server group.
7. Review the server group managed services to ensure that the rankings for the services are set up correctly
in the AR Server Group Operation Ranking form.
The production environment is now fully functional and at full capacity.
Related topics
Performing the data migration to learn about the Delta Data Migration process

Post-migration procedures
13.4.15 Post-migration procedures
Important
After a successful migration, back up the staging server database.
Complete the following steps after you complete the delta data migration.
Additionally, reset the changes you made prior to the delta data migration (see Server configuration adjustments).
Post-upgrade procedures

Updating fields in forms for delta data

During the post-upgrade portion of the installation, fields in some forms are updated through workflow triggered
by the MSM:MigrationTasks form. To update the fields for the delta data, complete the following procedures and
apply these packages into your destination server.
Applying the BMC Atrium Core post-DDM packages

When the source version of BMC Atrium Core is 8.0 (or earlier) and the target version is 8.1 (or later), fields in
these Atrium Core forms are updated through workflow triggered by a staging form during the post-upgrade
portion of the installer. To update the fields for the delta data, To apply the BMC Atrium Core post-DDM packages
.
The following data transformation changes are the results of updated functionality. These changes are already
been done while upgrading BMC Atrium Core from version 8.0 (or earlier) to 8.1. To update the fields for the delta
data, apply the package in your destination server.
Description of change How to verify
Update existing records to reflect or correct the actual CMDB class names in the Updated schemas are:
CategorizationSchemaKeyword field.
PCT:Product Catalog
PCT:LoadModelVersionPatch
PCT:LoadProdCatAliasMapping
PCT:LoadProdComAssoc
PCT:LoadProdModelVersion
PCT:LoadProductAlias
PCT:LoadProductCatalog
PDL:ESIDapps
PDL:ESIDappsCustom
For the CMDB.SC:ServiceContextAuthenticationInfo* form, fields 530070260 and 530070280 are set Review the field values in the
with a default value of AUTO_FILLED_BY_DDM_PROCESS, if they were null or empty earlier. The CMDB.SC:ServiceContextAuthenticationInfo*
changes are done because the fields been made mandatory in this version. form.
To apply the BMC Atrium Core post-DDM packages

Complete the following procedure if your Product Catalog version is 8.0 or later.
Note
Run the Delta Data Migration Tool to migrate data for all applications, including BMC Knowledge
Management. After the migration has completed, install the BMC knowledge management post-delta
data migration bundle.
1. Open a command window, and change to the Utilities\post_DDM\Atrium\patches folder.

2. Run the batch file with the following command-line options:

2.
setup.bat <destinationServer> <user> <password> <port>
3. Follow the prompts and wait for the batch file to finish.
4. Check the logs located in the Utilities\post_DDM\Atrium\patches\Logs folder to ensure that the package
installed correctly.
If there are any errors, correct them before re-installing the bundle.
Applying the BMC Remedy IT Service Management post-DDM packages

When the source version of BMC Remedy IT Service Management is 8.0 (or earlier) and the target version is 8.1.00
(or later), fields in these ITSM forms are updated through workflow triggered by a staging form during the
post-upgrade portion of the installer. To update the fields for the delta data, see To apply the BMC Remedy IT
Service Management post-DDM packages.
been done while upgrading BMC Remedy ITSM from version 8.0 (or earlier) to 8.1.00. To update the fields for the
delta data, apply the package in your destination server.
Click to view the data transformation changes
Migrates all the data from the old Change Calendar forms to new Change Calendar Check the user-specific data on the NGC:Filters, NGC
forms. Because the schema structure is different from the old calendar to the new Preferences and CHG:CHGNGC:SavedSearches% forms.
calendar, the user defaults of user were migrated to Filters and Preferences, and Saved
Searches were migrated to new Saved Searches forms.
Removes the non-English data from the Derived Factors form for records where "Risk Check the records in the Derived Factors form.
Factor Type" = "Derived Rating”. Due to changes in logic for showing risk
reports, non-English records are no longer required in that form. This change does not
impact any previous functionality of risk reports.
Corrects the customer data with respect to approval processes as Change Management Re-check your change requests for the CI or IA process.
deprecates the CI and IA of level processes and introduces a single CI-IA process. All All of these approval processes will be replaced with the
records must be updated with the respective change. new CI-IA process. In the scenario where the record is in
approval stage and using CI or IA process, you can see no
changes have been done.
Corrects the APR:SYS-Approval Definition form data for release data where the "For Check the records on the APR: SYS-Approval Definition
Stage Number" & "For Status Reason Int" field is updated with corresponding enumid form.
values. Because these changes were made in 8.0, the records before 8.0 must be
updated accordingly.
Removed the records in the VIS:ProcessAcceleratorItem form, so that Approve and Check the Change or Release form where it is in an
Reject options are not visible on Change or Release forms. Because Approving or Approval phase. No Approve or Reject buttons should be
Rejecting from the process flow bar causes some issues with re-loading the change, visible.
they were removed from the process flow bar. Hence this action is required.
Corrects the value of Priority. Initially the value of 'Priority' was exclusively driven Check the priority of a new change request.
by 'Urgency' . Now records are updated so that 'Priority' is based on both
'Impact' and 'Urgency'.

Corrects the records of the SYS:Notification Message form for Change Approval Check the Approval-related notification template of the
template where it updates the form with "CHG:ChangeAPDetailSignature". The SYS:Notification Maessages form. For financials, check
notification triggering form was changed in 8.0, so this fix is required. This fix also the Financial Association form for updates.
corrects the Financial Association form records where the Form Name 01 field value is
updated from the CHG:Infrastructure Change Classic to CHG:Infrastructure Change
form.
Corrects important Foundation form data. The People records are updated with Check the People records, Approval mappings, and
AlternateID using LoginID. Also corrects the Approval Mapping for Individual based on Assignments for corrected data.
the status of People records and for Group Mapping based on Group Status and
Approval role. The Event name in the CFG:Assignment form changed from Assignee to
Coordinator, so that Incident Manager becomes the Incident Coordinator, similar to
Change Management and Problem Management. These changes were made because of
issues observed in functions and processes of the consuming applications.
Corrects the Predefined My Searches in the Asset Management console where it refers Check the changes in the records of predefined searches.
to the AST:Relation_BaseElement_Locale form for searches instead of AST:BaseElement
. These changes were made to allow more locale specific searching capability.
MSM:MigrationTasks form runs the following tasks.
UPDATE_CHG_LEVEL_APR_PROCESSES_2_CIIA task that updates the following In the APR:SYS Approval Definition (Approval Process
Change Level processes (which are being discontinued) to the corresponding Change Configuration) form, verify that the process name and
Level CI-IA process: sort order are changed for entries for the
CHG:Infrastructure Change form.
Change Level - Business
Change Level - Close Down
Note
Change Level - Implementation
Change Level - Review If the Status is Proposed and the Sort Order field
Change Level CI - Business is empty, the procedure in "Updating fields in
Change Level CI - Close Down forms for delta data" does not update the Sort
Change Level CI - Implementation Order field.
Change Level CI - Review
Change Level IA - Business
Change Level IA - Close Down
Change Level IA - Implementation
Change Level IA - Review
This task also updates the sort order in the APR:SYS Approval Definition (Approval
Process Configuration) form. If the sort order was previously specified, it is not
changed. If the sort order was not previously specified and no additional
qualification was specified, the sort is set to 100; otherwise, the sort order is set
to 10.
UPDATE_FINAssociation_DATA_4_Classic_2_CHG task that changes the value in the If there was an entry in the FIN:Association form with
Form Name 01 field from CHG:Infrastructure Change Classic to CHG:Infrastructure CHG:Infrastructure Change Classic in the Form Name 01
Change in the FIN:Association form. field, verify that this value was changed to
CHG:Infrastructure Change.
RMS_APR_POPULATE_STATUSREASONINTFIELDS task that updates the entries to If an entry for the RMS:Release form exists in the Approval
populate the new status reason integer fields (FromStatusReasonInt and Process Configuration form for any phase that has a
ToStatusReasonInt) with corresponding enumerated values for the status reason. Status Reason for every status (Begin, Approved, Rejected
, and No Approvers), export this entry into a .csv file, and
verify that the FromStatusReasonInt (ID: 303554300) and
ToStatusReasonInt (ID: 303804100) fields have values.

UPDATE_CHG_LEVEL_APR_PROCESSES_ Verify the status is marked as Deleted if there is any

2_REMOVE_DUPLICATE_PHASE task that deletes the duplicate review phase record duplicate entry in the APR:SYS Approval Definition
from the APR:SYS Approval Definition form. (This record was introduced during the (Approval Process Configuration) form.
upgrade from BMC Remedy IT Service Management 7.6.03 to 7.6.04.) This task also
deletes records that were introduced in version 7.0.3 for the Close Down approval.
UPDATE_CHG_DATA_2_SET_APR_PROCESSLIST task that updates and initializes the Verify that the preview of approver list shows the
approval process list that is required for Approval Preview in the BMC Remedy Change approvers for change requests for which approval
Management application. This list was not persisted in earlier releases, but has been mapping was added and moved to the next review
made to persist with version 8.1 and later versions to optimize the roundtrips to the AR approval phase. (You may need to refresh the change
System server. request to check the approver list.)
UPDATE_APDETAIL_4CHGLEVEL_PROCESSES_2_ Verify that the process name was changed to the Change
CIIA_WHEN_PROC_NOTSTARTED_ADDOC_APR updates approval process names if the Level CI-IA process for the change request for which an
application has not started approval process and if ad-hoc approvers were added prior ad-hoc approver was added and where the approval
to the upgrade against the processes being deprecated. process was not started. In addition, Verify the process
name was not changed to the Change Level CI-IA process
for the change request for which ad-hoc approver was
added and where the approval process was started.
UPDATE_PRIORITY_BASEDON_URGENCY_IMPACT updates the value in the Priority Verify that the value in the Priority field (for example,
field in the CHG:CFG-Prioritization (Prioritizations) for Global Company form based on Critical) in the CHG:CFG-Prioritization (Prioritizations) for
the values in the Impact and Urgency fields. (In previous versions, Priority was based Global Company form is updated based on values in the
only on Urgency.) Impact (for example, 1-Extensive/WideSpread) and
Urgency (for example, 2-High) fields.
1-Extensive/WideSpread 2-High Critical

1-Extensive/WideSpread 3-Medium High
4-Minor/Localized 2-High Medium
3-Moderate/Limited 1-Critical High
4-Minor/Localized 1-Critical High
APPR_MAPPING_FIX_ASSIGNMENT_AVAILABILITY corrects the Approval Mapping for Not applicable

individuals based on the Status in the People record and for groups based on the
group's Status and the presence of anyone in the group with the approval role.
UPDATE_CHG_AP_PROCESS_CONFIG_N_NOTIFY identifies configuration changes (if Verify that configuration users are notified if any
any) in the AP:Process Definition form for all out-of-the-box approval processes, and configuration changes were made in the AP:Process
notifies configuration users to review the changes manually. Definition form for all out-of-the-box approval processes.
To apply the BMC Remedy IT Service Management post-DDM packages
Note
Run the Delta Data Migration Tool to migrate data for all applications, including BMC Remedy IT Service
Management. After the migration has completed, install the BMC Remedy IT Service Management
post-delta data migration package.
1. Open a command window, and navigate to the Utilities\post_DDM\ITSM\patches folder.


2.
setup.bat "<destinationServer>" "<user>" "<password>" <port>
4. Check the logs located in the Utilities\post_DDM\ITSM\patches\Logs folder to ensure that the package
Applying the BMC Knowledge Management post-DDM packages

When the source version of BMC Knowledge Management is 8.0 (or earlier) and the target version is 8.1 or later,
fields in these RKM forms are updated through workflow triggered by a staging form during the post-upgrade
portion of the installer. To update the fields for the delta data, see To apply the BMC Knowledge Management
post-DDM packages.
been done while upgrading BMC Knowledge Management from version 8.0 (or earlier) to 8.1. To update the fields
for the delta data, apply the package in your destination server.
In the RKM:KnowledgeArticleManager form, the value of z1D_FlagVGVersion is set to Yes when creating new versions of A migration package is
the article. This value needs to be reset to NULL (if it is Yes). These are the data transformation changes done due to a available to fix this
change in functionality. scenario.
To apply the BMC Knowledge Management post-DDM packages
Note
Run the Delta Data Migration Tool to migrate data for all applications, including BMC Knowledge
Management. After the migration has completed, install the BMC Knowledge Management post-delta
1. a. Open a command window, and navigate to the Utilities\post_DDM\RKM\patches folder.

b.
1.
b. Run the batch file with the following command-line options:
setup.bat "<destinationServer>" "<user>" "<password>" <port>
c. Follow the prompts and wait for the batch file to finish.
d. Check the logs located in the Utilities\post_DDM\RKM\patches\Logs folder to ensure that the
package installed correctly.
Applying the BMC Service Request Management post-DDM packages

When the source version of BMC Service Request Management is 8.0 (or earlier) and the target version is 8.1 (or
later), fields in these SRM forms are updated through workflow triggered by a staging form during the
post-upgrade portion of the installer. To update the fields for the delta data, see To apply the BMC Service
Request Management post-DDM packages.
been done while upgrading BMC Service Request Management from version 8.0 (or earlier) to 8.1. To update the
fields for the delta data, apply the package in your destination server.
Corrects the data on the SRM:Request form and sets the received date to the submit date when the received date is Re-check the corrected
NULL. Any service request created before 8.0 did not have received dates populated. To correct these blank values, the data on the SRM:Request
received date is populated with the submit date. form.
Sets the AOI Status field value to "Resolved" and Request Status field value to "Completed" on the Request Details form, Check the status of the
based on the Status field value set to "Completed" on the CHG:Infrastructure Change form. service request created
before the upgrade.
To apply the BMC Service Request Management post-DDM packages
Note
Run the Delta Data Migration Tool to migrate data for all applications, including BMC Service Request
Management. After the migration is completed, install the BMC Service Request Management post-delta

1. Open a command window, and navigate to the Utilities\post_DDM\SRM\patches folder.

4. Check the logs located in the Utilities\post_DDM\SRM\patches\Logs folder to ensure that the package
Applying BMC Service Request Management 2.2.00 post-DDM packages

When the source version of BMC Service Request Management is 2.2.00 Patch 1 or earlier and the target version
for BMC Service Request Management is 2.2.00 Patch 2 or later, delta data migration does not migrate the Service
Request Question Response information because of a data model change. A hotfix is available to migrate the
question responses data.
Before you begin

If you have not already applied BMC Service Request Management hotfixes, resolve the BMC Service Request
Management version issues.
To apply the BMC Service Request Management 2.2.00 post-DDM packages

Complete the following procedure if the BMC Service Request Management source version is 2.2.00 Patch 1 (or
earlier). For all other combinations, there is no need to complete the following procedure.
Note
Run the Delta Data Migration Tool to migrate data for all applications, including BMC Service Request
Management. After the migration has completed, install the BMC Service Request Management
post-delta data migration bundle.
1. Open a command window, and change to the Utilities\post_DDM\SRM\patches folder.

2. Run the installer with the following command-line options:
3. Follow the prompts and wait for the installer to finish.


3.
4. Check the logs located in the Utilities\post_DDM\SRM_22\Logs folder to ensure that the package installed
correctly.
5. In a browser, open the DDM:MigrationTasks form and search for the entry with 'Task Tag' =
"DDM_MigrateSRM2200-2200p2".
6. Edit the Delta Start Time to reflect the date and time when the delta data migration snapshot was taken.
Only Question Response entries that are created or modified after that time are migrated.
7. Set the Migrate Data field to Yes, and save the entry.
The migration process begins. At the end of the migration, the Migration Status field should display
Successful.
Updating multi-tenancy fields on forms for delta data records

After the multi-tenancy update utility successfully runs against all of the forms in all of your installed applications,
you must migrate the delta data from your production server to your staging server. After you migrate the delta
data, you must run the multi-tenancy updates against the migrated delta data.
Recommendation
Depending on the volume of data, BMC recommends that you run the multi-tenancy utility after every
delta data migration.
Depending on the size of your database, an upgrade on the staging server can take an extended period of time,
perhaps days. While the applications and data on the staging server are being updated, your production server
will continue to acquire new data. This new data is the delta data, which eventually must also be moved to the
staging server and updated with the multi-tenancy model changes.

Depending on the extent of your environment, you might need to process migrated delta data iteratively until the
production server and the staging server are synchronized, at which point you can move your staging server into
production.
After you migrate the delta data, return to to the Application Maintenance console to prepare the staging server
for applying the multi-tenancy updates.
Before you begin

Before you start this procedure, the following tasks must be successful:
You completed the upgrade.

You ran the multi-tenancy update utility with no errors.
You completed the delta data migration.
To run the multi-tenancy utility for delta data

You use the Maintenance Group field in the Application Maintenance console to select the type of maintenance
work that the console manages. For the multi-tenancy update, select Multi-Tenancy only.
1. Log on to the BMC Remedy ITSM application as an administrator.

From the Home page Applications list, select Administrator console > Application Administration console.
2. Click the Custom Configuration tab.
Select Foundation > Advanced Options > Application Maintenance console, and then click Open.
The Application Maintenance console opens, as shown in the following figure:
3. In the Maintenance Group field, select Multi-Tenancy.

4. In the View By field, select All Products, and then click Refresh.
5. Review the Status of the records in the multi-tenancy update.
6. Verify that all records are set to Successful.
7. In the Date field on the Application Maintenance console, enter the date of the time when the database
back-up was taken from the customer's production server.

You must use the Date field for multi-tenancy runs with delta data migration to specify the date and time
from which the system starts applying the data updates. You select the date and time when the last record
was created in your production environment prior to taking the snapshot of the database that you used in
your upgrade staging environment. This ensures that the update utility processes only the newer records,
that is, those records that were created after the snapshot was taken.
8. Click Reset.
The status of all forms, for all installed applications, is reset to Pending.
9. Restart the multi-tenancy update process.
10. Open the SHARE:Application_Properties form and verify the new records were successfully created.
One new record per installed product is created if you are successful.
Checking the status of the multi-tenancy update

You can use the Application Maintenance console to check for the following types of information.
Information Action
Form currently being Check the Status column in the console table for the form with the status of Executing.
processed

Information Action
Data errors If the update stops running because of a data error, check the Status column in the console table for the form with the
status of Fail. This is the record with the data error. Perform your troubleshooting diagnosis on this form.
Number of records to Click Refresh Counts and then, in the console table, check the number in the Records to Update column of the form that
process for a given form has the status of Executing.
Forms already Check the Status column in the console table for forms with the status of Successful.
processed
Forms waiting to be Check the Status column in the console table for forms with the status of Pending.
processed
Note
For a description of the columns and other UI controls, see Application Maintenance console UI
description.
Related topics from the IT Service Management documentation
Opening the Application Maintenance console

Starting the multi-tenancy update utility manually
Performing the data migration
To troubleshoot records that are in Fail or Pending status, see Troubleshooting the multi-tenancy update.
For general information, see Update to the multi-tenancy model.
For the entire end-to-end process of the multi-tenancy update, see Managing the multi-tenancy update and
Installation process flow.
Starting the multi-tenancy update utility manually

This topic describes how to manually start the multi-tenancy update utility. You use this procedure only in the
following situations:
You selected to bypass the multi-tenancy update during the main installation (after being prompted by the
installer, because your environment has more than 20 million records).
You encountered errors during an earlier run of the mult-tenancy update and need to restart the update.
You have performed a delta data migration and need to apply the multi-tenancy updates to the delta data.
To start the update utility manually
1. Open a command prompt window.

2. Configure the JAVA_HOME environment variable to contain the full Java home path.
3.
3. Navigate to %INSTALL_DIR%\BMCRemedyITSMSuite\Utilities\BMCMultiTenancyUtility\artools.
Use one of the following strings for the %INSTALL_DIR% variable, according to the BMC Remedy ITSM
application that you are upgrading:
BMC_REMEDY_ITSM_SUITE_HOME
BMC_SERVICE_REQUEST_MANAGEMENT_HOME
BMC_SLM_HOME
4. At the command prompt, type one of the following commands and then press Enter.
(UNIX) mtutility.sh
(Microsoft Windows) mtutility.bat
5. Select a mode in which to run, Mode 1 or Mode 2, and provide the arguments.
Mode 1, or (1) Command — You type the command arguments that are listed in the following table
on the command line.
Mode 2, or (2) Interactive — The utility prompts you for the arguments one at a time.
Multi-tenancy update utility arguments

Argument Value Description
type
-u String AR System administrator user name, mandatory
-p String AR System administrator user name password, mandatory if your system uses a password
-x String Name of AR System server on which the server is installed and the BMC Remedy ITSM applications are
deployed, mandatory
-a String Authentication string for user validation
-t Integer AR System communication port number

Argument Value Description

type
-r Integer RPC queue number for API private queue
-timeout String AR System timeout values, in seconds
Format = MediumTime:LongTime:ExtraLongTime
Example: 120:400:1800
Note: If the multi-tenancy update utility is timing out because the server is busy or if the utility is taking a
long time to respond after recaching, you must increase the timeout values. For example, you would
increase the values 120:400:1800, provided in the preceding example, to 300:600:2000.
The following illustrations provide an example of what the command line looks like for each mode:
Mode 1, or (1) Command
Mode 2, or (2) Interactive

6. When you finish providing the arguments, press Enter to start the utility.
Validating the migration

To validate the migration, run the AREntryCounter utility. Alternatively, you can run the SQL scripts that are
available for all the products and versions supported by delta data migration. These scripts are available in the
<migratorInstallfolder>\DeltaDataMigration\Utilities folder. Execute the scripts on the current production and
staging servers.
Note
If your source (current production) server is running BMC Atrium 7.6.0.3, you might encounter the
following error in the Product_Catalog _package_Migrator and Product_Catalog _package_Compare
HTML files: [4] -[303] -[Form does not exist on server PCT:TrustedDataset]

This form exists on the destination (upgraded) server but is not available in Atrium 7.6.03 version, so you
can safely ignore this benign error.
Running the RKM Conversion Tool after performing the migration

If you are upgrading BMC Knowledge Management from a version prior to 7.6.04, run the BMC Knowledge
Management Article Conversion Tool after every delta data migration or, at minimum, after the final delta data
migration.
See Converting XML-based articles from the 7.2 and 7.5 releases.
Note
If you are upgrading from a version of Knowledge Management System 7.5.x, or earlier, you must also
load the KMS:Associations form data. See Loading KMS:Associations form data.
Synchronizing form IDs to the destination server

An escalation that runs every day cleans up the records in the ID generator forms. Consequently, the ticket
number generator form IDs may not get synced properly to the destination server if not all of the following
parent forms had data in the final production run of the delta data migration.
Use one of the following methods for synchronizing form IDs to the destination server:
To synchronize form IDs to the destination server using dynamic select commands
You need to run the dynamic select command on the source DDM ( current production) server which gives you
an automated SQL as output. You must then copy this automated SQL output and execute it on the DDM
destination (new production) server.
In case you want to roll back, you dont need to do anything because source DDM ( current production)
server is not changed. You can directly roll back and start using the current system.
1. Execute the following command on the source DDM ( current production) server. The result would be an
automated SQL output.
On Oracle server
select 'update arschema set nextid = ' || nextid || ' where name = "' || name || '"; '
from arschema where name IN ('CFG:BusTimeTagGenerator',
'CFG:CFG PBB TicketNumGenerator','CFG:CFG ScriptTagNumGenerator',
'CHG:CFG Ticket Num Generator','CTM:CFG PTTicket Num Generator',
'CTM:CFG PeopleTagNumGenerator','HPD:CFG Ticket Num Generator',

'PBM:CFG KDBTagNumGenerator','PBM:CFG KE TicketNumGenerator',

'PBM:CFG PI TicketNumGenerator','SRD:CFG DefinitionNumGenerator',
'SRD:Cart TicketNumGenerator','SRD:Package TicketNumGenerator',
'SRM:CFG TicketNumGenerator','WOI:CFG TicketNumGenerator')
On SQL server
select 'update arschema set nextid = ' + convert(varchar(10),nextid) + ' where name = "' +
name + '"; ' from arschema where name IN ('CFG:BusTimeTagGenerator',
2. Copy the output to a text file.

3. Find and replace double quotes to single quote.
4. Execute the output on DDM destination (new production) server.
To synchronize form IDs to the destination server manually
1. Using SQL, check the Next ID value for the following forms within the arschema database table on the
source and destination databases. (The form name is stored within the Name column, and the Next IDis
stored within the Nextid column.)
CFG:BusTimeTagGenerator
CFG:CFG PBB TicketNumGenerator
CFG:CFG ScriptTagNumGenerator
CHG:CFG Ticket Num Generator
CTM:CFG PTTicket Num Generator
CTM:CFG PeopleTagNumGenerator
HPD:CFG Ticket Num Generator
PBM:CFG KDBTagNumGenerator
PBM:CFG KE TicketNumGenerator
PBM:CFG PI TicketNumGenerator
SRD:CFG DefinitionNumGenerator
SRD:Cart TicketNumGenerator
SRD:Package TicketNumGenerator
SRM:CFG TicketNumGenerator
WOI:CFG TicketNumGenerator
If you have the entire BMC Remedy IT Service Management Suite, use the following SQL query to
display all appropriate Next IDs within a single query:

select name, nextid from arschema where name IN ('CFG:BusTimeTagGenerator',

2. Ensure that the nextid value in the destination is equal to or greater than the source after the final Delta
Data Migration run has completed. If the nextid value is not equal to or greater than the source, use an
SQL UPDATE statement on the arschema table on the destinationserver. For example:
UPDATE arschema SET nextid = ‘100000’ WHERE name = ‘CFG:BusTimeTagGenerator’;
Note
If you are using an Oracle database platform, you must execute a commit; command after you
complete the SQL updates.
The following table lists the ticket number generator forms that are installed.
Form name Parent form name
AAS:ConfigurationTicketNumGenerator AAS:Activity
AST:LC Ticket Num Generator AST:LicenseCertificates
CFG:BusTimeTagGenerator CTM:Support Group On-Call
CFG:CFG PBB TicketNumGenerator CFG:Broadcast
CFG:CFG ScriptTagNumGenerator CFG:Scripts
CHG:CFG Ticket Num Generator CHG:Infrastructure Change
CTM:CFG PTTicket Num Generator CTM:People Template
CTM:CFG PeopleTagNumGenerator CTM:People
HPD:CFG Ticket Num Generator HPD:Help Desk
PBM:CFG KDBTagNumGenerator PBM:Solution Database
PBM:CFG KE TicketNumGenerator PBM:Known Error
PBM:CFG PI TicketNumGenerator PBM:Problem Investigation
RMS:CFG Ticket Num Generator RMS:Release

Migrating a modified service target or agreement after initial migration

For products included in the BMC ITSM Suite, including BMC Service Request Management and BMC Service
Level Management, you might want to migrate a modified service target or agreement after the initial migration.
BMC recommends that you do the following tasks before you begin the migration and after you complete the
migration.
Before you migrate a modified service target or agreement
1. Make sure that the source database and the destination servers are exactly the same.
2. Delete existing service targets or agreements from the destination server.
Warning
If you do not delete the service targets or agreements from the destination server, you could
receive a unique index violation error.
After you migrate a modified service target or agreement

After you migrate the service target or agreement from the source database to the destination server, rebuild the
service target and agreement.
Note
If you need to migrate the service target or agreement again, note the following:
Do not change the name of the service target or agreement that has already been migrated to the
destination server.
Do not delete any existing milestone and action items for service targets or agreements on the
destination server.
13.5 Upgrading server groups

Upgrading server groups requires a few modifications to the general upgrade procedures. Use the following
procedures to upgrade server groups:
To upgrade with server groups if you are migrating data

To perform an in-place upgrade
Note

When upgrading in a server group, you must not run the installer parallelly on multiple members of the
server group. Running the installer simultenously on multiple members causes authentication issues. For
example, if server A is primary server, server B, and server C is secondary, you must not run the installer
on server B and server C at the same time or on server A and server B at the same time.
Note
13.5.1 To upgrade with server groups if you are migrating data

1. Perform the steps already documented up to when you are ready to switch the staging server to
production — Stage 4 for upgrades with overlays present or Stage 8 for upgrades without overlays already
present.
2. Disable all servers in the server group on the load balancer, and stop them.
This usually requires you to remove them from a load balancer or to disable the load balancer.
3. Promote the staging server (Admin server) to an upgraded production server.
For upgrades with overlays present, see Stage 4. For upgrades without overlays already present, see Stage 8
.
4. Start the staging server and enable it on the load balancer.
5. For each server in the server group:
a. Point the server to the new database (so that it detects that the database has been upgraded).
b. Upgrade the server.
Upgrade BMC Remedy AR System on the primary and secondary servers. (Do not start the AR System
server before starting the installer.) Then, install BMC Atrium on the primary and secondary servers.
Finally, install the remaining applications on the primary and secondary servers.
c. Start the server, and enable it on the load balancer.
13.5.2 To perform an in-place upgrade

1. Shut down all of the non-administrative servers in the server group.
2. Disable the Admin server on the load balancer.
3. Perform the steps already documented to upgrade the administrative server.
See Upgrading with overlays already present or Upgrading without overlays already present.
4. Start the administrative server and enable it on the load balancer.
5. For each server in the server group:
a. Upgrade the server. (Do not start it first.)
b. Start the server, and enable it on the load balancer.

To identify the administrative server in a server group, open the Configuration tab on the AR System
Administration: Server Information form. For the administrative server, the Disable Admin Operations check box is
not selected. A server group should have only one administrative server.
13.6 Upgrading encryption security

When you upgrade BMC Remedy AR System 5.1.2 or later servers and clients to the latest version, standard
security is automatically installed on them.
If BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security is already
installed, the BMC Remedy AR System installer removes it and displays a message instructing you to install the
latest version of BMC Remedy Encryption Performance Security or BMC Remedy Encryption Premium Security on
the server after the upgrade is complete. You must also install the latest version of BMC Remedy Encryption
Performance Security or BMC Remedy Encryption Premium Security on your AR System clients after they are
upgraded.
13.7 Post-upgrade procedures

After you upgrade, perform the necessary procedures to complete the upgrade:
For information about how the service address prefix is set in a WSDL, see Adding web report and service address
prefix.
13.7.1 After upgrading from BMC Remedy AR System 7.6.04 with view
overlays present
When you upgrade from version BMC Remedy AR System 7.6.04, the view overlays that you had created in
version 7.6.04 are available after the upgrade. Before you start using the view overlay with the upgraded AR
System server, make sure that:
Only the fields with customizations are included in the view overlay
Fields that do not have customizations are not included in the view overlay
For information about how to remove unmodified fields from view overlays, see Adjusting customizations when
upgrading.
You can use the existing customizations after upgrade. The fields without customizations inherit updates to the
base properties when you apply a hot-fix or upgrade the AR System sever in the future.
13.7.2 Comparing objects after you upgraded with overlays already present
When you upgrade with overlays, you might have three objects to compare:

The new base object that is installed

The previous version's base object that was installed in the previous release
Your customized object (your overlay) from the previous release
You must determine how you want to compare the objects. You might perform a comparison as follows:
1. Compare the new base object with the previous version's base object to understand what BMC changed.
This helps you identify changes that BMC has made to its application in the upgrade.
2. Compare your customized object (your overlay) to the previous version's base object to understand what
changes you made to the object. This helps you identify the changes that you made in your overlay.
3. Compare your customized object (your overlay) with the new base object.
Then, you can determine whether you need to keep your customized object or if you can use the new base
object.
To see if there are differences between two sets of objects, use BMC Remedy Migrator. To examine the different
objects so that you can understand whether to merge changes, use BMC Remedy Developer Studio.
To obtain a list of all of the overlay objects that were modified in the latest release, obtain the Snapshot utility (a
Developer Studio plug-in). This unsupported utility is available on the BMC Developer Network (
https://communities.bmc.com/communities/community/bmcdn).
13.7.3 Disabling ServletExec after an upgrade

If you are upgrading and you do not want to use the ServletExec application server, follow the instructions in this
section to disable it (Windows or UNIX).
Note
If you do not plan to use the ServletExec application server, you can uninstall it.
To disable ServletExec after an upgrade on Windows
1. From the Control Panel, click Administrative Tools.

2. Open the Internet Information Services (IIS) Manager.
3. Find your local computer in the left navigation pane.
4. Click the Web Service Extensions folder for your local computer.
5. Right-click ServletExec in the list of Web Service Extensions, then choose Prohibit.
6. Right-click the Web Sites folder in the left navigation pane, then choose Properties.
7. On the ISAPI Filters tab, remove ServletExec from the list of filters.
8. Click OK, and close the IIS Manager.
9. Stop and restart the IIS.

To disable ServletExec after an upgrade on UNIX
1. Locate the httpd.conf file in the <ApacheInstallDirectory>/conf directory, and open the file with a text
editor.
2. Insert a # symbol at the beginning of the following lines to prevent them from being processed:
#LoadModule servletexec_module libexec/mod_servletexec.so

#ServletExecAdapterConfigFile
"<ServletExecInstallDirectory>/ServletExecAS/config/webadapter.properties"
3. Save and close the file.

4. Restart the web server.
13.7.4 Approval Server post-upgrade procedures

If you upgraded BMC Remedy Approval Server after backing up your data and customizations, perform the
following activities:
Import your customizations from the relevant .def and .arx files.
Restore your customized form views.
Disable the approval server workflow you documented. (Approval Server workflow is overwritten and
re-enabled during an upgrade installation.)
Note
When upgrading, the following error might be written to the

<ARSystemInstallDir>/Logs/Approval-RIK_PostUpgradeInstall.log file while the sample data is being
imported: ERROR (338): Duplicate Entry ID. You can safely ignore this error because it has no
impact on the functionality of the approval server.
Additionally, after you upgrade the Approval Server, review and complete the following sections:
Overview of the Approval upgrade utility

BMC Remedy Approval Server provides an approval upgrade utility that populates data for newer enhancements.
This utility runs automatically as part of installation. However, if you apply an approval server patch by using the
file replacement method, you need to run the approval upgrade utility manually. To run the approval upgrade
utility manually, see Running the approval utilities.
Note

Before running this utility, or before upgrading your approval server, you need to set the
Max-Entries-Per-Query setting in the ar.cfg file to 0. If this is not done and you have more AP:Detail
records than the size specified in the Max-Entries-Per-Query setting, not all records will be updated. The
zero value defines this as no server defined maximum, so all records are updated.
The following table lists the fields whose values the approval upgrade utility populates when upgrading from an
earlier release:
Fields populated by the approval upgrade utility
Release Field Form
7.1.00 or later
Process Instance ID AP:Alternate
Requestor AP:Detail-Signature
AP:Notification
AP:Process Administrator
AP:Process Definition
AP:Rule Definition
7.5.00 or later Full Name (ID 14201) AP:Signature
7.6.xx or later Recent History Time (ID 14105) AP:Signature
7.6.04 or later AP:Form

Field 1 (ID 14506)
Field 2 ( ID 14507)
The syntax of the approval upgrade utility is as follows:
upgrade -d <ARSystemInstallDir> [-l <logFileDestinationPath>]
Approval server upgrade utility parameters
Parameter Value
-d (mandatory) The location of the AR System installer. For example, C:\Program Files\BMC Software\ARSystem.
-l (optional) By default, the AR System suite installer places the approval-utils.log file in ARSystemServerInstallDir/approval/bin. If you run
the approval upgrade utility manually, you can use this parameter to specify the name and location for the log file.
If the approval upgrade utility fails during installation or upgrade, run the utility manually. Then, you restart the
approval server or wait for the cache to be refreshed for the changes to be visible. Even if the approval upgrade
utility fails, no data is lost.

Mapping application request form fields to AP-Detail fields

The Approval upgrade utility sets the values of two fields (field IDs 14506 and 14507) on AP:Detail for active detail
records, and maps them to the appropriate fields from the application request form through the Advanced tab on
AP:Form. The Process Administrator is responsible for mapping the fields 14508, 14509, 14510, 14511, 14512,
14513, and 14514 to the appropriate fields on the application request forms.
For more information about these fields, see AP:Form form.
Performing required three-way join form updates

Two of the new features introduced with version 7.0.00 of the approval server require new fields in the three-way
join form. If you are using version 7.0.00 or later with older approval server applications, you must add the
following character fields to the three-way join form for your application:
Additional Fields (field ID 12340), Notification Message (field ID 12303), Subject (field ID 12305), and
Process Instance Id (field ID 13021), for the Workflow-based notifications feature.
Assignee Group Permissions (field ID 112), for the multi-tenancy feature.
The approval server uses Process Instance IDs instead of Process Names. Therefore, notifications are based on
the Process Instance IDs.
Note
When you configure a notification for a process, a notification filter is created, based on the Process
Instance ID. If the Process Instance ID is changed by any means, it is not automatically reflected in the
notification filter. You must update the notification filter manually with the new Process Instance ID.
The three-way join form is the join between the application request form and the AP:Detail-Signature form. For
example, in the Get Agreement sample application, the application request form is AP-Sample2:Get Agreement,
and the three-way join form is AP-Sample2:Issue Detail Signat.
You can add the new fields to your application in one of the following ways:
By editing the form in BMC Remedy Developer Studio

By using the joinfix utility
This section describes these options.
To add the fields using BMC Remedy Developer Studio
1. Open the three-way join form in BMC Remedy Developer Studio.

2. Right-click on the form, and choose Add Fields from AP:Detail-Signature from the menu that appears.
3.
3. Select the new required fields, and click OK.

4. Position the fields on the form, and hide them.
5. Save the three-way join form.
To add the fields by using the joinfix utility
1. (UNIX) Navigate to ARSystemServerInstallDir and export the directory as a shared library path by using one
of the following commands:
On the Oracle Solaris and Linux operating systems:
#export LD_LIBRARY_PATH=/usr/ar/ARSystemServerInstallDir/bin
On the HP-UX operating system:
#export SHLIB_PATH=/usr/ar/ARSystemServerInstallDir/bin
On the IBM AIX operating system:
#export LIBPATH=/usr/ar/ARSystemServerInstallDir/bin
Note
You need to set the library paths on UNIX for all approval server utilities.
2. Run the joinfix utility available for your platform as described in Running the approval utilities.
3. Enter the appropriate approval request form name, and press Enter.
The following table provides examples of applications and their application request forms.
Example applications and their application request forms
Application Application request form
Get Agreement sample application AP-Sample2:Get Agreement
Lunch Scheduler sample application AP-Sample:Lunch Scheduler
BMC Change Management CHG:Change
BMC Asset Management AST:PurchaseRequisition
The utility prompts:

1. Update Join Criteria
2. Addnew fields in Three-way Join Form
Arguments:
4. Enter 2 to add the new fields, and press Enter.
The utility adds the five new fields to the three-way join form that is associated with the application request
form you entered.
Note

If you created the three-way join form after installing version 7.0.00 or later of the approval
server, you do not have to run joinfix to add these fields. These fields exist in the AP:Signature
form, and automatically become part of the three-way join form when you create the join. See
Creating the join forms.
For more information about the joinfix utility, see Running the Approval Join Fix utility.
Running one-time escalations to configure new data

When you upgrade from version 6.3.00 to 7.0.00 or later of the approval server, use the following escalations:
AP:Common-Set-Process-GUID — Sets the value of the Process Instance ID field to the Process Name for
the existing data.
AP:Common-Set-AssigneeGroup — Sets the value of the Assignee Group Permission field to Public for the
existing data.
Note
You must run these escalations only once after upgrading. After the Process Instance ID and Assignee
Group Permission fields are set with the appropriate values, you should disable these escalations.
13.7.5 Developer Studio post-upgrade procedures

When you upgrade BMC Remedy Developer Studio, the installer performs the following actions:
Moves the previous Developer Studio files to a DeveloperStudioBackup folder. (This includes workspaces
and external plug-ins.)
Places the new binaries in the DeveloperStudio folder.
Copies workspaces from the DeveloperStudioBackup folder to the DeveloperStudio folder.
External Developer Studio plug-ins that you configured before the upgrade are not copied to the
DeveloperStudio folder.
To ensure that the correct plug-ins are in the DeveloperStudio folder
Manually copy external Developer Studio plug-ins from the DeveloperStudioBackup folder to the
DeveloperStudio folder.
13.7.6 Enabling LDAP plug-ins for SSL connections post-upgrade
Note

This topic explains how to enable LDAP plug-ins for SSL connections in configured networks after an upgrade.
For information on adding a certificate for SSL communication after a new installation, see Enabling LDAP
plug-ins for SSL connections post-installation.
For more information about BMC Remedy AR System support for IPv6, see Support for IPv6
Adding an LDAP certificate to the certificate database after an upgrade

To enable LDAP plug-ins for SSL connections in configured networks after an upgrade, you must add an LDAP
certificate to the certificate database for SSL communication. LDAPJ plug-ins support SSL communication to the
LDAP server. When you configure LDAP plug-ins that use SSL connections, you specify the file location of the
keystore that contains the certificate. LDAPJ then uses the Java KeyStore (JKS) type to store the certificates.
Note
Pre-8.1 releases use the NSS based keystore. For more information, see Enabling LDAP plug-ins to
establish SSL connections with LDAP servers.
To add a certificate for SSL communication after an upgrade

In an upgrade scenario, if the AREA or ARDBC LDAP plug-ins are already configured to use SSL, export the
existing certificate to the Java Keystore as explained in this procedure.
1. Locate the certificate path in the Certificate Database field in the AREA LDAP Configuration form or the
ARDBC LDAP Configuration form.
2. List all of the certificates from the configured certificate database by using following command:
certutil -L -d <certificatePath>
Where certificatePath is the parent directory that contains certificate database.
For example, using this command can result in the following:

my_x509_cert CT,P,P
cert_ibmc_c8s25bs CT,P,P
3. Select the certificate alias name that you want to use to export to the file.
4. Export the certificate to file using the following command:
certutil -L -a -n my_x509_cert -d C:\ldapCert\my_x509_cert.rfc
5.
5. Import the certificate by using the following command:
keytool -import -noprompt -trustcacerts -keystore C:\certdb\ldaptruststore.jks -storepass

mypassword
-alias my_x509_cert -file my_x509_cert.rfc
Note
If the keystore does not already exist, this command creates a new keystore.
6. Update the AREA LDAP Configuration form or ARDBC LDAP Configuration form to use this new keystore.
7. Restart the plug-in server to use the updated configuration.
13.7.7 IPv6 post-upgrade procedures

This section describes the tasks that you can perform after you upgrade BMC Remedy AR System on an
IPv6-configured network. The following topics are provided:
Updating configuration after upgrading and changing from IPv4 to IPv6
Recommendation
Instead of changing a server from an IPv4 network to an IPv6 network directly, BMC recommends
leaving the server in dual mode so that the IPv4 and IPv6 clients can both connect to the server.
If you must switch a server from an IPv4 network to an IPv6 network, then follow the procedures in this
topic.
If you have installed BMC Remedy AR System and BMC Atrium Core on a server with an IPv4 address and then
changed it to an IPv6 address, you must complete the following tasks:
Before you restart the BMC Remedy AR System server after switching to an IPv6 domain, you must ensure that
the hostname, or fully qualified domain name (FQDN) in the configuration files is valid in the IPv6 environment.
Otherwise, BMC Atrium Core components might not work as expected, such as adding or editing CIs in BMC
Atrium Explorer.
To verify valid domain names for IPv6 servers

For all platforms, you need to verify that the domain name specified in the configuration files are valid in the IPv6
environment.
1. On the server where BMC Atrium Core is installed, open each of the following files in a text editor:

1.
Windows:
<BMC_AR_SYSTEM_HOME>\conf\ar.cfg
<BMC_AR_SYSTEM_HOME>\conf\armonitor.cfg
<ATRIUMCORE_HOME>\wsc\wsregistryapi\conf\registryserver.properties
UNIX and Linux:
<ARSYSTEM_HOME>/conf/ar.conf
/etc/arsystem/<MACHINE_NAME>/armonitor.conf
<ATRIUMCORE_HOME>/wsc/wsregistryapi/conf/registryserver.properties
<ATRIUMCORE_HOME>/cmdb/server/bin/normeng.sh
<ATRIUMCORE_HOME>/cmdb/server/bin/atriumplugin.sh
2. For the plugin aliases in ar.cfg and ar.conf, verify that the specified hostname is valid on the IPv6 network.
For example, if arserver1.calbro.com:9999 is the specified hostname, check that it is valid in the IPv6
environment. If it is not, you might have to remove the domain name (arserver1:9999) or change it to a
valid hostname, such as arserver1.ipv6lab.calbro.com.
The following code is an example of plugin aliases with the domain names.
Server-Plugin-Alias: ARSYS.ARF.REGISTRY ARSYS.ARF.REGISTRY arserver1.calbro.com:9999

Server-Plugin-Alias: ARSYS.ARDBC.REGISTRY ARSYS.ARDBC.REGISTRY arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARDBC.ARREPORTENGINE ARSYS.ARDBC.ARREPORTENGINE
arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.QUERYPARSER ARSYS.ARF.QUERYPARSER arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ALRT.WEBSERVICE ARSYS.ALRT.WEBSERVICE arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.PARSEPARAMETERS ARSYS.ARF.PARSEPARAMETERS arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.PUBLISHREPORT ARSYS.ARF.PUBLISHREPORT arserver1.calbro.com:9999
Server-Plugin-Alias: ARSYS.ARF.REPORTSCHEDULER ARSYS.ARF.REPORTSCHEDULER arserver1.calbro.com:9999
. . .
3. For armonitor.conf, armonitor.cfg, registryserver.properties, normeng.sh, and atriumplugin.sh, search for

and verify domain names.
The following code is an example of server entries with the domain names.
bmc.uddi.registryserver.url.security=http://webservices1.calbro.com:8080/uddi/services/security
bmc.uddi.registryserver.url.inquiry=http://webservices1.calbro.com:8080/uddi/services/inquiry
bmc.uddi.registryserver.url.publishing=http://webservices1.calbro.com:8080/uddi/services/publicationbmc.uddi.re
4. Save the edited files.

5. If you have a server group configuration prior to switching from an IPv4 to IPv6 network, check and update
the entries in the AR System Server Group Operation Ranking form.
a. Open the AR System Server Group Operation Ranking form in search mode.
http://:/arsys/forms/ /GroupAR+System+Server+Group+Operation+Ranking/
b. Perform an unqualified search to see the entries in the form.
c. For each server, check the Server value.
d.
d. Verify that the domain name is valid for all entries in the IPv6 environment.
e. If it is not, remove the domain name or change it to a valid IPv6 domain name.
f. Save the AR System Server Group Operation Ranking form.
6. Restart the AR System server and the BMC Atrium Core Web Services Tomcat server.
To update the Administration configuration

This issue occurs in a setup in which the server group setting is present before switching the network from IPV4
to IPV6.
If you have not verified the domain names as described above in AR System Server Group Operation Ranking
form, then, on restart, the BMC Remedy AR System server might not recognize upon restart the hostname (such
as arserver1.calbro.com). It then sets that property in the server configuration information and adds a new set of
entries for the hostname in the AR System Server Group Operation Ranking.
If that happens, you must delete the new set of entries and edit the the Server Name Alias field to reflect the
correct hostname/FQDN in an IPV6 network.
1. Log in to the BMC Remedy AR System Administration Console.

*http://:/arsys/forms/ /GroupAR+System+Server+Group+Operation+Ranking/*
4. For each server, check the Server value.
5. Verify that the domain name/FQDN is valid for all entries in the IPv6 environment.
6. If it is not, remove the domain name or change it to a valid IPv6 domain name.
Updating Java paths after upgrading

If you upgrade to Java SE 7 after upgrading to BMC Remedy Action Request System and BMC Atrium Core version
8.1.00 or later, you must update the Java paths in armonitor.cfg. Java SE 7 is required for IPv6 support, but you
can upgrade BMC Remedy AR System and BMC Atrium Core with Java SE 6 installed. You can then install Java SE
7, but you will have to update the Java paths to the Java SE 7 installation.
To update the Java paths
1. On the server where BMC Remedy Action Request System is installed, open the
<BMC_AR_SYSTEM_HOME>\conf\armonitor.cfg file in a text editor.
2. Find and replace references to the Java 6 path with the Java 7 path.
The following are two examples where the JRE 6 path is specified:

2.
"C:\Program Files\Java\jre6\bin\java" -Djava.net.preferIPv4Stack=true

-Djava.net.preferIPv6Addresses=false -Xmx512m -classpath "C:\Program Files\BMC
Software\AtriumCore\cmdb\plugins\ne;C:\Program Files\BMC
Software\AtriumCore\cmdb\plugins;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arpluginsvr80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arapi80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arutil80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\log4j-1.2.14.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\cmdbapi80.jar;" com.bmc.arsys.pluginsvr.ARPluginServerMain -x
vw-sjc-bsm-dv16 -i "C:\Program Files\BMC Software\ARSystem"
"C:\Program Files\Java\jre6\bin\java" -Djava.net.preferIPv4Stack=true

-Djava.net.preferIPv6Addresses=false -Xmx512m -classpath "C:\Program Files\BMC
Software\AtriumCore\cmdb\plugins\ne;C:\Program Files\BMC
Software\AtriumCore\cmdb\plugins;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arpluginsvr80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arapi80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\arutil80_build001.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\log4j-1.2.14.jar;C:\Program Files\BMC
Software\AtriumCore\cmdb\sdk\bin\cmdbapi80.jar;" com.bmc.arsys.pluginsvr.ARPluginServerMain -x
vw-sjc-bsm-dv16 -i "C:\Program Files\BMC Software\ARSystem"
In these cases, the C:\Program Files\Java\jre6\bin\java path is replaced with C:\Program

Files\Java\jre7\bin\java.
3. Save the edited file.

14 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 with a directory Integrating 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 Data and database integrations
System database with a third-party application, and providing read-only access to data 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
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

14.1 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:
14.1.1 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
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.
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.
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.
14.1.2 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.
14.1.3 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.
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.
14.1.4 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 BMC Remedy AR
Programming programming and building executables. However, it provides access to all AR System server System C API
Interface) 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 BMC Remedy AR
Java development environment. Using this abstraction layer allows developers to quickly build System Java API
enhanced applications for the web. overview
Web Services This integration technology (XML, WSDL, UDDI, and SOAP) allows you to build distributed applications Publishing the BMC
without programming: Remedy AR System
functionality as a
Use the Set Fields workflow action and a Web Services object to "consume" third-party web web service
services in AR System applications.
Use BMC Remedy AR System to create and "publish" a Web Services object.
BMC Remedy AR AR System clients perform data operations on external systems through the AR System server, plug-in Enabling Plug-ins
System Plug-Ins 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.
Data Visualization The data visualization field provides a framework and services for mid tier-based graphing solutions. It Data visualization
Field provides an efficient way to add graphical elements (such as BMC Remedy Flashboards) to AR System fields
forms.
AREA Plug-Ins BMC Remedy provides a special API that allows user logins to be validated from a data source outside AREA plug-ins
(BMC Remedy AR the AR System database. This API is called the AR System External Authentication (AREA) API. introduction and
System External Installing sample
Authentication) AREA
implementations
Filter API Plug-Ins The filter API enables you to use filters to permit other applications to make calls back into BMC Integration
Remedy AR System. considerations
ARDBC Plug-Ins AR System Database Connectivity enables you to access and manipulate data that is not stored in BMC AR filter API plug-ins
(BMC Remedy AR Remedy AR System. introduction
System Database Using the ARDBC API, you can create plug-ins used by AR System server to manage data. These
Connectivity) 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.
Vendor Forms Vendor forms allow BMC Remedy AR System to present data from external sources as entries in an AR Vendor forms
System form. Vendor forms require you to have an ARDBC plug-in installed and configured. introduction
View Forms View forms allow direct read-and-write access to data in database tables that are not owned by BMC View forms
Remedy AR System. This allows direct access to these tables, as if they were owned by BMC Remedy AR introduction
System, without programming, database replication, or synchronization.
SQL Database Third-party tools with appropriate permissions can access any information in the AR System database. SQL database access
Access In addition, AR System workflow can query other databases.
ODBC Access ODBC (Open DataBase Connectivity) is a standard database access method developed by Microsoft. ODBC database
Using the ODBC driver, any client capable of accessing ODBC can have read-only access to AR System access introduction
forms. Reporting is a common use of ODBC.
Integration
considerations

Method Description Section or topic
BMC Atrium The BMC Atrium Integration Engine mediates between the AR System server and vendor applications
Integration such as SAP, Oracle, and other applications and databases for which adapters are developed. Adapters
Engine (AIE) can come from BMC Remedy, from partners, or from customers.
Command Line A Command Line Interface (CLI) is available with most AR System clients. This enables a client to be Integration
Interface (CLI) started and passed a set of parameters so that either it is in a specific state and displays information or it considerations
completes a process and exits with no user interface displayed.
XML Import and BMC Remedy AR System can export and import object definitions in XML. Importing object
Export AR System clients can convert AR System objects to XML and vice versa without making calls to the AR definitions and
System server. Exporting objects
When the server exports the file in XML format, it adds a header required to make it a valid XML and data to XML
document. This same header is required for the server to import an XML file correctly. Otherwise, the format
file is assumed to be in the standard AR System definition format.
Running External One of the actions available in AR System workflow is the Run Process action. BMC Remedy AR System Running external
Applications (Run can use the command line interfaces of other applications to start those applications and pass them processes
Process) initial data. introduction
In some cases, the third-party application is simply started, while in others BMC Remedy AR System
waits for a response.
SNMP You can use SNMP to manage complex networks through SNMP-compliant management consoles and BMC Remedy SNMP
monitor network devices. Agent configuration
Licensing Authorized integration system vendors (ISVs) can make their applications licensable at the application Making applications
Applications and user levels. licensable for
integration system
vendors
14.2 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.
14.2.1 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, 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.
14.2.2 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 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
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.
14.2.3 AR Filter API plug-ins introduction

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
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\arpluginsdocVerNum.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
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.
Related topics
AR Filter API plug-ins introduction
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>
Software/ARSystem/pluginsvr/websvcalrtjava81_build001.jar</pathelement>
<classname>com.bmc.arsys.ws.alert.ARAlertPlugin</classname>
Software/ARSystem/pluginsvr/websvcalrtjava81_build001.jar</pathelement>
</plugin>
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>
Software/ARSystem/pluginsvr/arregistryplugin81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.registry.ARRegistryPlugin</classname>
Software/ARSystem/pluginsvr/WSRegistryAPI8.1.jar</pathelement>
Software/ARSystem/pluginsvr/activation.jar</pathelement>
Software/ARSystem/pluginsvr/tibco-uddi-client3.0.jar</pathelement>
</plugin>
<plugin>
<name>ARSYS.ARDBC.REGISTRY</name>
Software/ARSystem/pluginsvr/arregistryquery81_build001.jar</pathelement>
<classname>com.bmc.arsys.plugins.registry.ARDBCRegistryQuery</classname>
Software/ARSystem/pluginsvr/WSRegistryAPI8.1.jar</pathelement>
Software/ARSystem/pluginsvr/activation.jar</pathelement>
Software/ARSystem/pluginsvr/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
The configuration information of the CAI plug-in is available in the

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-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
follows:
<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\WSRegistryAPI8.1.jar</pathelement>
<pathelement type="location">C:\Program Files\BMC Software\ARSystem\pluginsvr\json.jar</pathelement>
<userDefined>

</userDefined>
</plugin>
The ar.cfg/ar.conf file includes the Server-Plugin-Alias setting that points to the correct plug-in 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.
The configuration information of the Charge-back plug-in is available in the
follows:
<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>
example:
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.
The configuration information of the Docs Migration plug-in is available in the

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>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\commons-io-1.4.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\dom4j-1.6.1.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-common.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\jconn2-2.0.jar</pathelement>

Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\ojdbc14-10.1.0.4.0.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\sqljdbc-1.1.1501.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\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-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
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
The configuration information of the File System Sync plug-in is available in the
follows:
<plugin>
<name>RMDY.ITSM.RKM.FS.KAM.SYNC</name>

<code>JAVA</code>
<filename>C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins\file-system-sync.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.kamfilesystemsync.RkmFileSystemKamSyncPlugin</classname>
</plugin>
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>
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
The configuration information of the Form Permissions plug-in is available in the
follows:
<plugin>
<name>RMDY.ITSM.RKM.FORMPERMISSIONS</name>

<code>JAVA</code>
<filename>C:\BMC
Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-form-permissions.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.formpermissions.Permissions</classname>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-form-permissions.jar</pathelement>
</plugin>
Server-Plugin-Alias: RMDY.ITSM.RKM.FORMPERMISSIONS RMDY.ITSM.RKM.FORMPERMISSIONS
myServer:9999

</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

Configuring full text search for a server group
The configuration information of the FTS plug-in is available in the

follows:
<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>
Software/ARSystem/pluginsvr/fts/ftsplugin80_build001.jar</pathelement>
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-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

Software\ARSystem\pluginsvr\fts;C:\Program Files\BMC Software\ARSystem\pluginsvr;C:\Program Files\BMC
Software\ARSystem\pluginsvr\arpluginsvr80_build001.jar" 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
follows:
<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>

example:
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.
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
follows:
<plugin>
<name>RMDY.ITSM.RKM.LOGLEVEL.CHANGE</name>
<code>JAVA</code>
<filename>C:\BMC
Software\BMCRemedyITSMSuite\Shared_Components\plugins\itsm-plugin-log-level-change.jar</filename>
<classname>com.bmc.itsm.common.utils.pluginloglevelchange.PluginLogLevelChange</classname>
</plugin>
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.

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
follows:
<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>
example:
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.

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
The configuration information of the Registration plug-in is available in the
follows:
<plugin>
<name>RMDY.ITSM.RKM.REGISTRATION</name>
<code>JAVA</code>
<filename>C:\BMC
Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-registration.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.registration.RegistrationController</classname>
</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: 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

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
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>
example:
Server-Plugin-Alias: RMDY.ITSM.RLE RMDY.ITSM.RLE myServer:9999
Related topic
Troubleshooting Rule Engine plug-in issues
SDG plug-in configuration

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.
SDG plug-in configuration

The configuration information of the SDG plug-in is available in the
follows:
<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>
Software\ARSystem\pluginsvr\excelgenerator\lib\arutil80_build001.jar</pathelement>
<pathelement type="location">C:\BMC Software\ARSystem\pluginsvr\excelgenerator\lib\sdg.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\commons-lang-2.2.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\dom4j-1.6.1.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\ooxml-schemas-1.0.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\poi-3.5-FINAL-20090928.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\poi-contrib-3.5-FINAL-20090928.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\poi-ooxml-3.5-FINAL-20090928.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\poi-scratchpad-3.5-FINAL-20090928.jar</pathelement>
Software\ARSystem\pluginsvr\excelgenerator\lib\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-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.

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 ( aralerttwitterVerNum.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
follows:

<plugin>
<name>ARSYS.ALRT.TWITTER</name>
Software/ARSystem/pluginsvr/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.

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
follows:
<name>ARSYS.ARF.TWITTER</name>
Software/ARSystem/pluginsvr/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
The configuration information of the Update KAM Mapping plug-in is available in the
follows:
<plugin>
<name>RMDY.ITSM.RKM.UPDATEKAMMAPPINGS</name>
<code>JAVA</code>
<filename>C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins\rkm-operations.jar</filename>
<classname>com.bmc.itsm.rkm.filterapi.operations.UpdateKAMMappings</classname>

</plugin>
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.

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
follows:
<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-Plugin-Alias: ARSYS.ARF.WEBSERVICE ARSYS.ARF.WEBSERVICE HOST:9999
Related topic
Troubleshooting Web Service plug-in issues
14.2.4 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 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
This section contains information on:

AREA plug-in C API functions

These are the AREA plug-in API functions:
AREAFreeCallback
AREANeedToSyncCallback
AREAVerifyLoginCallback
For more information, see the BMC Remedy AR System C API functions.
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
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

14.2.5 ARDBC plug-ins introduction

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 Integration considerations.

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

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

Home
6. BMC Software Confidential
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
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.
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.
Related topic
ARDBC plug-ins introduction
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.
The configuration information of the AppQuery plug-in is available in the
follows:
<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>
The ar.cfg/ar.conf file includes the Server-Plugin-Alias setting that points to the correct plug-in 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.
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

follows:
<plugin>

</plugin>
follows:
Server-Plugin-Alias: ARSYS.ARDBC.PREVIEW ARSYS.ARDBC.PREVIEW myServer:9999
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
follows:
<plugin>
<name>DSO.FILTERCONFIGURATION</name>
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.
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

The configuration information of the File System plug-in is available in the
follows:
<plugin>
<name>RMDY.ITSM.RKM.FILESYSTEM</name>
<type>ARDBC</type>
<code>JAVA</code>
<filename>C:\BMC Software\BMCRemedyITSMSuite\Shared_Components\plugins\file-system.jar</filename>
<classname>com.bmc.itsm.rkm.ardbc.filesystem.RkmFileSystemPlugin</classname>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\commons-io-1.4.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\poi-3.5-FINAL-20090928.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\iText-2.1.5.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\dom4j-1.6.1.jar</pathelement>
Software\BMCRemedyITSMSuite\Shared_Components\plugins\3rd_party\poi-ooxml-3.5-FINAL-20090928.jar</pathelement>
<userDefined>
<entry_id_length>500</entry_id_length>
</userDefined>
</plugin>
follows:
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
follows:
<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>
Software/ARSystem/diserver/ardbc-plugin/pentahoardbc80_build001.jar</pathelement>
Software/ARSystem/diserver/ardbc-plugin/arcmnapp80_build001.jar</pathelement>
Software/ARSystem/diserver/data-integration/lib/kettle-core.jar</pathelement>
Software/ARSystem/diserver/data-integration/lib/kettle-db.jar</pathelement>
Software/ARSystem/diserver/data-integration/lib/kettle-engine.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/cmdbapi80.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/arpdi-utils80_build001.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/arpdirepository80_build001.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/LucidDbClient-minimal.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/asjava.zip</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/db2jcc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/db2jcc_license_cu.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/derby.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/derbyclient.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/h2.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/hive-jdbc-0.5.0-pentaho-1.0.0.jar</pathelement>

Software/ARSystem/diserver/data-integration/libext/JDBC/hsqldb.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/ifxjdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/iijdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/infobright-core-3.3.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/interclient.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/jaybird-full-2.1.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/jt400.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/jtds-1.2.5.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/kingbasejdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/monetdb-1.7-jdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/mysql-connector-java-3.1.14-bin.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/ojdbc14.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/orai18n.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/postgresql-8.3-603.jdbc3.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/rdbthin.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/sapdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/sqlitejdbc-v037-nested.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/unijdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/vertica_3.5_jdk_5.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/JDBC/xdbjdbc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-beanutils-1.7.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-codec-1.3.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-collections-3.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-dbcp-1.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-digester-1.8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-fileupload-1.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-httpclient-3.0.1.jar</pathelement>


Software/ARSystem/diserver/data-integration/libext/commons/commons-io-1.4.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-lang-2.4.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-logging-1.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-net-1.4.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-pool-1.3.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/commons/commons-validator-1.3.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/feed4j.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/georss-rome-0.9.8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/jdom.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/nekohtml.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/rome-1.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/feeds/xml-apis.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/hadoop-core-0.20.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/hive-exec-0.5.0-pentaho-1.0.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/hive-metastore-0.5.0-pentaho-1.0.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/hive-service-0.5.0-pentaho-1.0.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/libfb303.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/hive/libthrift.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jfree/jcommon-1.0.14.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jfree/jfreechart-1.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/config/mondrian.properties</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/commons-math-1.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/eigenbase-properties-1.1.0.10924.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/eigenbase-resgen-1.3.0.13768.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/eigenbase-xom-1.3.0.13768.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/javacup-10k.jar</pathelement>

Software/ARSystem/diserver/data-integration/libext/mondrian/mondrian-3.2.1.13885.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mondrian/saxon8-xom.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/hadoop-core-0.20.2.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/jets3t-0.7.4.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/kettle-vfs-20100924.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/libbase-1.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/libformula-1.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/olap4j-0.9.8.340.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-database-4.0.5.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-formula-editor-0.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-hdfs-vfs-1.0.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-s3-vfs-1.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-vfs-browser-2.0.2.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-xul-core-3.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/pentaho-xul-swt-3.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/sqleonardo-swt-wrapper.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/pentaho/sqleonardo.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/antlr-runtime-3.1.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/core-3.4.2.v_883_R34x.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/drools-api-5.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/drools-compiler-5.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/drools-core-5.0.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/rules/mvel2-2.0.10.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/salesforce/axis.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/salesforce/commons-discovery-0.2.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/salesforce/jaxrpc.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/salesforce/saaj.jar</pathelement>


Software/ARSystem/diserver/data-integration/libext/salesforce/salesforce20.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/spring/spring-beans-2.5.6.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/spring/spring-context-2.5.6.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/spring/spring-context-support-2.5.6.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/spring/spring-core-2.5.6.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/activation.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/jetty-6.1.21.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/jetty-plus-6.1.21.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/jetty-util-6.1.21.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/servlet-api-2.5-6.1.9.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/web/simple-jndi-0.11.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/webservices/jsr173_api.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/webservices/qname.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/webservices/wsdl4j.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/webservices/wstx-asl-3.2.9.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/webservices/xalan-2.4.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/SNMP4J.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/ascsapjco3wrp.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/dom4j-1.6.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/edtftpj2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/ftp4che-0.7.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/ini4j-0.5.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jackcess-1.2.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jakarta-oro-2.0.8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/janino.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/javadbf.jar</pathelement>

Software/ARSystem/diserver/data-integration/libext/javassist.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jaxen-1.1.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jcifs-1.3.3.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/js.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jsch-0.1.42.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/json_simple-1.1.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jsonpath.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jug-lgpl-2.0.0.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/junit-4.7.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/jxl.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/ldapjdk.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/livetribe-jsr223-2.0.6.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/log4j-1.2.14.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/mail.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/odfdom.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/ognl-2.6.9.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/palo-core.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/poi-3.6-20091214.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/poi-ooxml-3.6-20091214.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/poi-ooxml-schemas-3.6-20091214.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/saxon8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/scannotation-1.0.2.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/secondstring.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/slf4j-api-1.5.8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/slf4j-jcl-1.5.8.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/snakeyaml-1.7.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/syslog4j-0.9.34.jar</pathelement>


Software/ARSystem/diserver/data-integration/libext/trilead-ssh2-build213.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/xbean.jar</pathelement>
Software/ARSystem/diserver/data-integration/libext/xercesImpl-2.9.1.jar</pathelement>
</plugin>
follows:
Server-Plugin-Alias: ARSYS.ARDBC.PENTAHO ARSYS.ARDBC.PENTAHO myServer:9999
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
follows:
<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>
</plugin>

follows:
Server-Plugin-Alias: RMDY.ITSM.RKM.GROUP RMDY.ITSM.RKM.GROUP myServer:9999
Related topic
Troubleshooting RKM Group plug-in issues
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
follows:
<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-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>
</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
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
follows:
<plugin>
<name>RMDY.ITSM.ASSET.SOFTWAREUSAGE</name>
<code>JAVA</code>
<filename/>
<classname>com.bmc.itsm.asset.swusage.plugin.AssetSoftwareUsagePlugin</classname>
Software\ARSystem\pluginsvr\swu\AstSoftUsagePlugin.jar</pathelement>
<userDefined>
</userDefined>
</plugin>
Server-Plugin-Alias: RMDY.ITSM.ASSET.SOFTWAREUSAGE RMDY.ITSM.ASSET.SOFTWAREUSAGE
myServer:9999

Related topic
Troubleshooting Software Usage plug-in issues
14.2.6 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
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
pluginsvr_config.xml 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.
14.2.7 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.
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.
14.2.8 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.
14.2.9 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, 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

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.
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 pluginsvr_config.xml file.
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 pluginsvr_config.xml file.
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 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.
1.
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
See the plug-in server configuration file (ar.cfg or ar.conf).
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.

5.
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
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

1.
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.
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.)
14.2.10 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
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

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:

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.
14.2.11 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

You define plug-in aliases in the ar.cfg or ar.conf configuration file. Use this format:
Server-Plugin-Alias: aliasName realName hostName[:portNumber]

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.
In this topic:
Vendor form accessing the ARDBC 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.
Vendor form accessing the ARDBC plug-in scenario
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.
14.2.12 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.
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

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.
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\arpluginsdoc
VerNum.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.

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.
14.2.13 Common plug-in C functions and Java methods

This section describes the calls or methods common to all plug-in types including:
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.
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
14.2.14 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.

14.3 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.
14.3.1 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.
14.3.2 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.
14.3.3 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.
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.
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. In the LDAP Date-Time Format field, select the format to use to represent date and time to LDAP servers.
Format Value Description Example: 6 a.m. Sept.
28, 2001
Generalized 0 YYYYMMDDHHMMSSZ This format is recognized by all LDAP servers, and it is 20010928060000Z
Time recommended.
AD Generalized 1 YYYYMMDDHHMMSS.0Z This format is recognized only by Microsoft Active Directory 20010928060000.0Z
Time servers.
UTC Time 2 YYMMDDHHMMSSZ This is a historical format and does not indicate the century. It is 010928060000Z
not recommended.
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 Size field, 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.

10.
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 Discovery field, 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 Cache box, 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 Size field, specify the maximum size of the cache.
Tip
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.
14.3.4 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

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
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=inetorgperson) Filter that selects the objects
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. 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
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:
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
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.
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.
14.3.5 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

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


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 Information section, 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. To create a
certificate database, see Creating a certificate database.
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.
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. No prevents 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 Information section, 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.
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.
5.
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
0 - - - -
1 - - - X
2 - X - -
3 - X - X
4 - - X -
5 - - X X
6 - X X -
7 - X X X
8 X - - -
9 X - - X
10 X X - -
11 X X - X
12 X - X -
13 X - X X
14 X X X -
15 X X X X
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.
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.
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.conf files.
Note
For the changes to take effect, restart your AR System server.
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

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

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.
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 Entry Mode: Optional Read/Write Default Value: none Vendor Information Column: dn
Name
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

14.3.7 Enabling LDAP plug-ins to establish SSL connections with LDAP

servers
The AR System External Authentication (AREA) and AR System Database Connectivity (ARDBC) plug-ins use
Secure Sockets Layer (SSL) certificates for authentication and encrypting data transmission. SSL encryption
requires the use of a Certificate Authority (CA) and digital certificates to ensure the security and integrity of BMC
Remedy Action Request (AR) System.
The following topics in this section explain how to add an SSL certificate to a certificate database by using the
Certificate Database Tool (certutil included with Mozilla Network Security Services (NSS) shipped with BMC
Remedy AR System), and how to troubleshoot and debug general SSL certificate issues:
NSS is a collection of open source libraries and tools based on open standards used by BMC for Internet security.
The NSS library files are also included in your BMC Remedy AR System distribution at C:\Program Files\BMC
Software\AR System. The certutil command line utility assists you with certificate selection and installation.
Note
This information is provided as a convenience only. BMC assumes that customers have a working
certificate database. If you require a compiled version of certutil, contact your BMC Support
representative.

For reference information about NSS libraries, see the Mozilla documentation
http://www.mozilla.org/projects/security/pki/nss/. This image shows how the NSS libraries, certutil, and the
certificate database work together.
Certificate database, certutil, and NSS libraries
When you configure LDAP plug-ins that use SSL connections, you must specify the directory that contains the
certificate database. Ensure that the certificate database directory contains cert8.db or cert7.db and key3.db files,
which are required for the LDAP plug-in configuration.
For information on configuring LDAP plug-ins, see these procedures:
To configure the ARDBC LDAP plug-in

To configure settings for the AREA LDAP plug-in
NSS library support

The following table shows the NSS library versions used by BMC Remedy AR System. Release 3.11.4 or newer NSS
libraries are preferred for any version of AR System.
AR System and NSS library compatibility
NSS library version number Included with BMC Remedy AR System

releases
3.11.4 or newer — This library creates cert8.db. However, it is fully backward compatible; it reads the Release 7.5.00 and higher
cert7.db certificate database.
3.4.2 — This library creates cert7.db. Releases earlier than 7.5.00
NSS 3.11.4 binary distributions for AR System platforms

Source and binary distributions for BMC Remedy AR System release 7.5.00 and higher UNIX platforms may be
downloaded at http://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_4_RTM/

The following table lists supported binary files. The nss-3.11.4 directory for your platform will contain three
subdirectories:
NSS header files are in the include subdirectory.

NSS shared libraries are in the lib subdirectory.
NSS utilities and test programs are in the bin subdirectory.
AR System supported platform NSS 3.11.4 binary files
UNIX platform distributions Last modified date and time
HP-UXB.11.11_64_OPT.OBJ 22-Nov-2006 11:20
HP-UXB.11.23_ia64_64_OPT.OBJ 22-Nov-2006 11:23
Linux2.6_x86_64_glibc_PTH_OPT.OBJ 22-Nov-2006 11:23
SunOS5.9_64_OPT.OBJ 22-Nov-2006 11:24
For Windows NT use the nss-3.11.4.zip file in the WINNT5.0_OPT.OBJ directory at

http://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_4_RTM/msvc6.0/
NSS 3.4.2 binary distributions for AR System platforms

Source and binary distributions for BMC Remedy AR System releases earlier than 7.5.00 UNIX platform may be
downloaded at http://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_4_2_RTM/
The following table lists supported binary files. The nss-3.4.2 directory for your platform will contain three
subdirectories:
NSS header files are in the include subdirectory.

NSS shared libraries are in the lib subdirectory.
NSS utilities and test programs are in the bin subdirectory.
AR System supported platform NSS 3.4.2 binary files
UNIX platform distributions Last modified date and time
AIX4.3_OPT.OBJ 13-Jun-2002 11:38
HP-UXB.11.00_64_OPT.OBJ 13-Jun-2002 11:42
Linux2.4_x86_glibc_PTH_OPT.OBJ 13-Jun-2002 11:44
SunOS5.8_64_OPT.OBJ 13-Jun-2002 12:02
For Windows NT use the WINNT4.0_OPT.OBJ file last modified 13-Jun-2002 12:04.

Certificate databases introduction

BMC Remedy AR System uses the Mozilla LDAP C SDK libraries to enable the AREA and ARDBC LDAP plug-ins to
establish SSL connections with LDAP servers for login authentication, as shown in the runtime architecture
diagram below. NSS requires that the LDAP server's certification authority (CA) certificate reside in a certificate
database.
Configure certutil to generate:
New certificate databases

Certificate lists from the database
Certificate database additions
Note
NSS 3.11.4 shared libraries are backward compatible with all older NSS 3.x shared libraries.
When LDAP plug-ins that use SSL connections are configured, the cert8.db file should be configured to trust the
certificate of the LDAP server and specify the directory that contains the certificate database. To start you must
build certutil.
Runtime architecture

To build the certutil utility for NSS 3.11.4
1. Browse and download the binary files for your operating system to a temporary location:
https://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_11_4_RTM/
2. Extract the OPT release build file into a directory on the AR System server called c:\nss-3.11.4.
3. Follow build instructions here:
http://www.mozilla.org/projects/security/pki/nss/nss-3.11.4/nss-3.11.4-build.html
4. For troubleshooting your build, go here:
http://www.mozilla.org/projects/security/pki/nss/troubleshoot.html
Creating a certificate database

If you do not have a certificate database (cert8.db file), use the certutil utility to create one on the BMC
To create a certificate database in a specific directory

At the command line, enter:
certutil -N -d <certDir>
Where:
-N specifies a new certificate and key database.

-d certDir specifies the directory in which the certificate database is created.
To add certificates to or list certificates in a database, see:
Adding a certificate to a certificate database

Listing certificates in a certificate database
Adding an LDAP certificate to the certificate database in an IPv6-configured network
Adding a certificate to a certificate database

Use the certutil utility to add a certificate to a certificate database.
Note
The certificate that you want to add must exist on your LDAP server. For information about creating
certificates and adding them to your LDAP server, see your LDAP server documentation.
To add a certificate to a certificate database


certutil -A -n <nickname> -t "<trustedAttributes>" -d <certDir> -i <certName>.cer
Where:
-A adds an existing certificate to a certificate database.

The certificate database should exist. If it does not, this option creates one.
-d certDir specifies the directory that contains the cert8.db or cert7.db and key3.db files (these files must
reside in the same directory). The specified directory must exist. If it does not, the command fails.
-i certName.cer specifies the file name of the certificate to add to the certificate database.
-n nickname specifies the nickname of the certificate.
If the nickname contains spaces, enclose it in double quotation marks.
-t "trustedAttributes" specifies the trusted attributes to apply to a certificate when adding it to a certificate
database.
Each certificate includes the following trust categories:
SSL
email
Object signing
For each category, specify zero or more of these trust attribute codes shown in the table below.
Use commas to separate each category. Enclose the entire set of attributes in double quotation marks. For
example, this is a standard trust attribute configuration: PTCu,P,P.
Example
certutil -A -n "My CA Certificate" -t "PTCu,P,P" -d /tmp/mycertdirectory -i mycertname.cer
Where:
My CA Certificate is the certificate name.

PTCu,P,P are the trust attributes.
/tmp/mycertdirectory is the certificate directory.
mycertname.cer is the file name of the certificate to add to the database.
Option Description
c Signifies a valid CA.
C Signifies a trusted CA to issue server certificates for SSL only and implies c.
p Signifies a valid peer.
P Signifies a trusted peer and implies p.
T Signifies a trusted CA to issue client certificates and implies c.

Option Description
u Signifies a user certificate that can be used for authentication or signing.
w Signifies a warning. This attribute is used with another attribute to include a warning when the certificate is used in the context of that
attribute.
Listing certificates in a certificate database

Use the certutil utility to list all certificates in a certificate database, or to list specific information about an
individual certificate.
To list all certificates in a certificate database for a specific directory

certutil -L -d <certDir>
Where:
-L generates a list.
-d certDir specifies the directory that contains the database certificate.
Example
C:\conf>certutil -L -d cert
QAtest CT,P,P
Where:
QAtest is the certificate name.

CT,P,P are the trust attributes.
Option Description
c Signifies a valid CA.
C Signifies a trusted CA to issue server certificates for SSL only and implies c.
p Signifies a valid peer.
P Signifies a trusted peer and implies p.
T Signifies a trusted CA to issue client certificates and implies c.
u Signifies a user certificate that can be used for authentication or signing.
w Signifies a warning. This attribute is used with another attribute to include a warning when the certificate is used in the context of that
attribute.

To list information about a specific certificate

certutil -L -d <certDir> -n <nickname>
Where:
-n nickname is the nickname of the certificate whose information you want to list. If the nickname
contains spaces, enclose it in double quotation marks.
To view sample output, see Sample certificates.
Sample certificates
Two sample certificates are shown below:
Windows
Separate certificate authority (CA)
Note
BMC requires that the Issuer and the Subject are always resolvable for your certificate to be valid.
Example: Microsoft Windows Certificate

Certificate information
Certificate section Description
Common Name (CN) for Issuer Acme CA
Organizational Unit (OU) Support
Organization (O) BMC
Location (L) San Francisco
State (ST) CA
Country (C) US
Windows certificate
Certificate:
Data:
Version: 3 (0x2)

Serial Number:
5e:c9:54:50:18:2a:bf:a5:43:17:25:6a:ff:3a:47:fa
Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption
Issuer: CN=Acme CA, OU=Support, O=BMC, L=San Francisco, ST=CA,
C=US, E=user@bmc.com
Validity:
Not Before: Thu Mar 25 20:50:35 2011
Not After: Sat Mar 25 20:50:35 2015
Subject: CN= CA, OU=Support, O=BMC, L=San Francisco, ST=CA,
C=US, E=user@bmc.com
Subject Public Key Info:
Public Key Algorithm: PKCS #1 RSA Encryption
RSA Public Key:
Modulus:
.
.
.
Exponent: 65537 (0x10001)
Signed Extensions:
Name:
2b:06:01:04:01:82:37:14:02
Data: ""
Name:
Certificate Key Usage
Data:
03:02:01:46
Name:
Certificate Basic Constraints
Critical:
True
Data: Is a CA with a maximum path length of -2.
Data: Is a CA with a maximum path length of -2.
Name:
Certificate Subject Key ID
Data:
04:14:20:a1:e7:b8:9e:e7:f7:49:22:fb:47:b6:fd:c5:
e3:20:fa:67:6d:e3
Name:
CRL Distribution Points
Data: Sequence {
Sequence {
Option 0
.
.
.
Name:
2b:06:01:04:01:82:37:15:01
Data: 131328 (0x20100)
Fingerprint (MD5):
D4:1D:8C:D9:8F:00:B2:04:E9:80:09:98:EC:F8:42:7E
Fingerprint (SHA1):
DA:39:A3:EE:5E:6B:4B:0D:32:55:BF:EF:95:60:18:90:AF:D8:07:09

Signature:
.
.
.
Certificate Trust Flags:
SSL Flags:
Valid CA
Trusted CA
Trusted Client CA
Email Flags:
Valid Peer
Trusted
Object Signing Flags:
Valid Peer
Trusted
Example: Separate Certificate Authority

This certificate shows a separate Issuer and Subject Common Name (CN).
To generate a certificate with separate CAs

C:\CertUser\ldap>certutil.exe -L -d c:\CertUser\ldap\Sequoia
USOMALDC01 CT,P,P
USADISBDC07 CT,P,P
C:\CertUser\ldap>certutil.exe -L -n USADISBDC07 -d c:\CertUser\ldap\Sequoia
Option Description
Common Name (CN) VeriSign (Issuer) Acme (Subject)
Organizational Unit (OU) Shared Services
Organization (O) Sequoia Institute
Location (L) Sopia Landing
State (ST) New York
Country (C) US
Separate certificate authority
Certificate:
Data:
Version: 3 (0x2)
Serial Number:

53:19:a1:ae:00:00:00:00:57:d9
Issuer: "CN=VeriSign,OU=Shared Services,O=Sequoia Institute,L=Sopia Landing,ST=New York,C=US"
Validity:
Not Before: Thu Oct 14 13:12:02 2010
Not After : Sat Oct 13 13:12:02 2012
Subject: "CN=Acme,OU=Domain Controllers, DC=Sequoia,DC=com"
Subject Public Key Info:
Public Key Algorithm: PKCS #1 RSA Encryption
RSA Public Key:
Modulus:
.
.
.
Name: Extended Key Usage
TLS Web Client Authentication Certificate
TLS Web Server Authentication Certificate
Microsoft KP SmartCard Logon
Name: Certificate Key Usage
Usages: Digital Signature
Key Encipherment
Key Encipherment
Name: OID.1.3.6.1.4.1.311.21.10
Data: Sequence {
Sequence {
TLS Web Client Authentication Certificate
}
Sequence {
TLS Web Server Authentication Certificate
}
Sequence {
}
}
}
Name: Certificate Subject Key ID
Data:
.
.
.
Name: Certificate Authority Key Identifier
Key ID:
.
.
.
Name: CRL Distribution Points
URI: "ldap:///CN=VeriSign,CN=VeriSign,CN=CDP,CN=Public%20Key%
20Services,CN=Services,CN=Configuration,DC=Sequoia,DC=com?certificateRevocationList?base?objectClass=cRLDistributionP
20Services,CN=Services,CN=Configuration,DC=Sequoia,DC=com?certificateRevocationList?base?objectClass=cRLDistributionP
Name: Authority Information Access
Method: PKIX CA issuers access method

Location:
URI: "ldap:///CN=Acme,CN=AIA,CN=Public%20Key%20Services
,CN=Services,CN=Configuration,DC=Sequoia,DC=com?cACertificate?base?objectClass=certificationAuthority"
Method: PKIX CA issuers access method
Location:
URI: "http://VeriSign.Sequoia.com/CertEnroll/VeriSign.Sequoia.com_VeriSign.crt"
URI: "http://VeriSign.Sequoia.com/CertEnroll/VeriSign.Sequoia.com_VeriSign.crt"
Name: Certificate Subject Alt Name
DNS name: "Acme.am.Sequoia.com"
DNS name: "Acme.am.Sequoia.com"
Signature:
.
.
.
Fingerprint (MD5):
19:D2:22:17:CE:65:76:9A:B1:CE:EC:A2:F7:29:46:F0
Fingerprint (SHA1):
4F:0C:1D:C6:94:AE:98:CB:CC:95:0D:3B:27:5D:C3:AA:83:17:BF:62
4F:0C:1D:C6:94:AE:98:CB:CC:95:0D:3B:27:5D:C3:AA:83:17:BF:62
Certificate Trust Flags:
SSL Flags:
Valid CA
Trusted CA
Trusted Client CA
Email Flags:
Valid Peer
Trusted
Object Signing Flags:
Valid Peer
Trusted
Resolving certificate issues

The general approach to resolving certificate issues in BMC Remedy AR System includes:
Preventing common issues

To avoid common problems with certificates, ensure that:
The Issuer and Subject in your Secure Socket Layer (SSL) certificate are resolvable. The Issuer and Subject
are in distinguished name format at times.
Your SSL certificate(s) reside(s) in the certificate database.
For every link in the certificate chain:
The domain is known.
The Issuer is a recognized and trusted Certificate Authority (CA). Your LDAP plug-in must trust the
certificate from your LDAP server. This means that your CA, such as VeriSign, must provide a known
root certificate before the LDAP plug-in will trust the certificate.
All failover devices in your environment contain functioning certificates.

Identifying certificate issues

To establish an SSL connection for external authentication, credentials are exchanged between the BMC Remedy
AR System server and an LDAP server. The AR System server must verify the credentials sent by the LDAP server
with the requirement that the certificate database on the AR System server contain the CA certificate used to
generate the LDAP server certificate.
Some issues that can occur when a validated certificate is used to establish an SSL connection between the AR
System server and an LDAP server. You should check to make sure that your installation is free from these
problems:
An incorrect NSS library version or patch was used to generate a certificate. You must use the correct NSS
libraries. For information about library versions, see NSS library support.
The LDAP server is not configured to use SSL.
The SSL port is closed.
Your LDAP server's CA certificate is:
Not found in the certificate database
Either expired or is not appropriate. For example, a client certificate might be used as a CA
certificate.
BMC Remedy AR System does not receive the certificate when required.
The LDAP server certificate is not imported.
Follow these steps to verify that AR System is properly configured with the LDAP server for SSL connections:
1. Open the web browser on the AR System server and enter: https://<LDAP server address>
2. When asked, choose to accept the certificate.
3. Enter this command for information about a validated certificate:
certutil -L -d <certificate databaselocation> <certname>
Determining the associated forms and fields

Make sure that the AR System External Authentication (AREA) LDAP and AR System Database Connectivity
(ARDBC) LDAP Configuration forms are configured correctly so that AR System can establish SSL connections to
the LDAP server. Ensure that:
1. Secure Socket Layer is set to Yes.

2. The correct certificate database directory path is entered in the Certificate Database field.
3. The same user name and password can be used to log in to any application that supports the LDAP
protocol.
AREA LDAP Configuration form

ARDBC LDAP Configuration form
See the AREA LDAP plug-in and ARDBC LDAP plug-in information in the Integrating section to configure the
AREA LDAP and ARDBC LDAP plug-ins.

Isolating the problem

To obtain more detailed information about the SSL communication between the AR System server and the LDAP
server, use the SSL debugging tools SSLDEBUG and SSLTRACE.
Note
You can also use the SSLTAP debugging tool to debug. For more information see
http://www.mozilla.org/projects/security/pki/nss/tools/ssltap.html
To send debugging information to standard output
1. Edit the armonitor.conf file and prefix the arplugin line with a hash symbol (#) to comment it out.
2. Restart the AR System server so that the plug-in server is no longer running.
3. From the command line, change to the directory where arserverd and arplugin are located.
4. From the command line, enter the following:
For UNIX
SSLDEBUG=1;export SSLDEBUG
SSLTRACE=3;export SSLTRACE
For Microsoft Windows
SET SSLDEBUG=1
SET SSLTRACE=3
5. From the command line, enter the following to launch the plug-in server:
For UNIX
./arplugin -i <server_installation_directory>
For Windows
arplugin -i . -m
6. Enable the plug-in log file:

a. In the AR System Administration console, click System > General > Log Files.
b. Select Plug-In Log.
c. Set the log level to All.
7.
7. Perform some user actions that would cause an LDAP connection using SSL to take place.
If an SSL connection to the LDAP host was processing, the command prompt should contain diagnostic
information such as an error number. This error number may be used by your SSL administrators to
troubleshoot the problem. In some cases, a descriptive error message is also provided.
Examining the plug-in log

The plug-in server log can track the events of the AREA and ARDBC LDAP plug-ins that AR System uses. Each line
of a plug-in log file begins with an <PLGN> prefix. Each entry includes information such as the time stamp, the API
calls encountered, and name of the plug-in. Here's a section from a plug-in log:
<PLGN> <TID: 0000002944> <RPC ID: 0000000000> <Queue: Dispatcher>

<Client-RPC: 000000> /* Fri Apr 21 2011 15:56:41.6300 */ Plug-in Trace Log -- ON
<PLGN> <TID: 0000002944> <RPC ID: 0000000000> <Queue: Dispatcher>
<Client-RPC: 000000> /* Fri Apr 21 2011 15:56:41.6460 */ AREA
Plug-in Loaded: EXAMPLE.AREA.SIMPLE version 1
Checking certificates
1. From the command line, enter:
certutil.exe -L -d C:\CertUser\ldap\Sequoia
Acme CT,P,P
VeriSign CT,P,P
2. Enter the following and ensure that subject corresponds to the name of the LDAP server and that a
separate certificate exists for the Issuer.
certutil.exe -L -n VeriSign -d C:\CertUser\ldap\Sequoia
where
-n nickname specifies the nickname of the certificate. If the nickname contains spaces, enclose it in
double quotation marks.
CT,P,P are the trust attributes. C signifies a trusted CA to issue server certificates and implies a valid
CA. T signifies a trusted CA to issue client certificates and implies a valid peer.

Option Description
Common Name (CN) VeriSign (Issuer) Acme (Subject)
Organizational Unit (OU) Shared Services
Organization (O) Sequoia Institute
Location (L) Sopia Landing
State (ST) New York
Country (C) US
Certificate:
Data:
Version: 3 (0x2)
Serial Number:
53:19:a1:ae:00:00:00:00:57:d9
Issuer: "CN=VeriSign,OU=Shared Services,O=Sequoia Institute,L=Sopia Landing,ST=New
York,C=US"
Validity:
Not Before: Thu Oct 14 13:12:02 2011
Not After : Sat Oct 13 13:12:02 2012
Subject: "CN=Acme,OU=Domain Controllers,DC=am,DC=Sequoia,DC=com"
Examining SSL debugging logs

A sample log file, used when debugging certificate problems on UNIX with SSLDEBUG and SSLTRACE, is shown in
Example output. A sample verbose log file is shown in Example verbose output. The detailed debugging log is
only available if you use the compiled version of the NSS libraries from BMC. If you require this compiled version,
contact your BMC Support representative.
Example debug output

The example standard output shown here does not require the BMC-compiled version of the NSS libraries. To
display this output, follow the procedure in step 3, Isolate the problem.
Sample debugging output includes the following key areas:
Successful initiation of the SSL handshake, which demonstrates AR System is attempting to establish a
connection to your LDAP server.
6408: SSL[10538544]: sending client-hello

6408: SSL3[10538544]: handle server_hello handshake
6408: SSL3[10538544]: Set XXX Pending Cipher Suite to 0x000a
Information that shows the plug-in server received the certificate from the LDAP server.

Important
AR System must verify the peer certificate. It is critical that this certificate reside in the SSL
certificate database or be resolvable through a certificate chain.
6408: SSL3[10538544]: Peer Certificate Issuer:[CN=idd-corporate-usa-02-CA,DCidd,DC=com]
Successful completion of the LDAP handshake.
6408: SSL3[10538544]: handle finished handshake

6408: SSL[10538544]: handshake is completed
Verification of the Administrator user from the AREAVerifyLoginCallback API call.
<PLGN> <TID: 007056> <RPC ID: 0000000001> <Queue: AREA> <Client-RPC: 390695> /* Wed Oct 27 2011
14:14:24.9790 */+VL AREAVerifyLoginCallback -- user Administrator
14:14:24.9790 */<ARSYS.AREA.LDAP> <FINEST> AREAVerifyLoginCallback
Validation that the AREA plug-in has established a connection with the LDAP server ( usa-02.idd.com). In
this example, the LDAP server authentication is enabled on port 636, and the SSL certificate used to secure
the connection resides in the /OPT/ARSystem/LDAP/SSL/cert directory.
14:14:24.9790 */<ARSYS.AREA.LDAP> <FINER> Connecting via SSL(host=HOSTNAME-usa-02.idd.com,
port=636, certPath=OPT/ARSystem/LDAP/SSL/cert with Server SSL Authentication enabled
Confirmation that the AREA plug-in bind to the LDAP server is successful.
14:14:25.2120 */<ARSYS.AREA.LDAP> <FINEST> Successful bind as user Administrator
Confirmation that the AREA plug-in authentication on the LDAP server is successful.
14:14:25.2250 */-VL OK

Example verbose output
Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI

idd-corporate-usa-02-CA CT,P,P
Debug snippet
SSL: tracing set to 3
SSL: debugging set to 1
6408: SSL[10538544]: sending client-hello
6408: SSL3[10538544]: handle server_hello handshake
6408: SSL3[10538544]: Set XXX Pending Cipher Suite to 0x000a
6408: SSL3[10538544]: handle certificate handshake
6408: SSL3[10538544]: Peer Certificate Issuer:[CN=idd-corporate-usa-02-CA,DCidd,DC=com]
6408: SSL3[10538544]: handle certificate_request handshake
6408: SSL3[10538544]: handle server_hello_done handshake
6408: SSL3[10538544]: send client_key_exchange handshake
6408: SSL3[10538544]: DONE sending client_key_exchange
6408: SSL3[10538544]: send change_cipher_spec record
6408: SSL3[10538544] SendRecord type: handshake (22) nIn=269
6408: SSL[10538544]: Send record (plain text) [Len: 269]
.
.
.6408: SSL3[10538544] SendRecord type: change_cipher_spec (20) nIn=1
01 .
6408: SSL3[10538544] Set Current Write Cipher Suite to Pending
6408: SSL3[10538544]: send finished handshake
6408: SSL3[10538544] SendRecord type: handshake (22) nIn=16
14 00 00 0c bc 24 c1 f7 e0 3f aa db 35 72 5e 8a .....$...?..5r^.
6408: SSL3[10538544]: handle change_cipher_spec record
6408: SSL3[10538544] Set Current Read Cipher Suite to Pending
6408: SSL3[10538544]: handle finished handshake
6408: SSL[10538544]: handshake is completed
6408: SSL[10538544]: SecureSend: sending 65 bytes
6408: SSL3[10538544] SendRecord type: application_data (23) nIn=65
.
.
.
6408: SSL[10538544]: recving 22 bytes securely (errno=0)
kjdsf;lajsdflaj
CATHERINE
DC=idd
2c 44 43 3d 63 6f 6d 80 08 54 68 72 65 65 32 23 ,DC=com..Three2#
30 0


30 05 02 01 05 42 00 0....B.
6408: SSL3[10538544]: send alert record, level=1 desc=0
6408: SSL3[10538544] SendRecord type: alert (21) nIn=2
01 00 ..
14:14:24.9790 */+VL AREAVerifyLoginCallback -- user Administrator
14:14:24.9790 */<ARSYS.AREA.LDAP> <FINER> Connecting via SSL(host=HOSTNAME-usa-02.idd.com, port=636,
certPath=OPT/ARSystem/LDAP/SSL/cert with Server SSL Authentication enabled)
14:14:25.0460 */<ARSYS.AREA.LDAP> <FINER> connect timeout previously: -1
14:14:25.0460 */<ARSYS.AREA.LDAP> <FINER> connect timeout used: 35000
14:14:25.0460 */<ARSYS.AREA.LDAP> <FINER> ldap_simple_bind("CN=Administrator,CN=Users,DC=idd,DC=com",
hidden)
14:14:25.1850 */<ARSYS.AREA.LDAP> <FINEST> After the bind
14:14:25.1850 */<ARSYS.AREA.LDAP> <FINER> ldap_search_ext("CN=Users,DC=idd,DC=com", 2,
"samAccountname=Administrator")
hidden)
14:14:25.2120 */<ARSYS.AREA.LDAP> <FINEST> Successful bind as user Administrator
hidden)
14:14:25.2210 */<ARSYS.AREA.LDAP> <FINEST> User attribute: objectClass
14:14:25.2210 */<ARSYS.AREA.LDAP> <FINEST> User attribute: cn
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: description
<PLGN> <TID: 007056> <RPC ID: 0000000001> <Queue: AREA > <Client-RPC: 390695> /* Wed Oct 27 2011
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: userCertificate
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: distinguishedName
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: instanceType
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: whenCreated
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: whenChanged

14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: uSNCreated
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: memberOf
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: uSNChanged
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: name
14:14:25.2220 */<ARSYS.AREA.LDAP> <FINEST> User attribute: objectGUID
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: userAccountControl
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: badPwdCount
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: codePage
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: countryCode
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: badPasswordTime
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: lastLogoff
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: lastLogon
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: logonHours
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: pwdLastSet
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: primaryGroupID
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: objectSid
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: adminCount
14:14:25.2230 */<ARSYS.AREA.LDAP> <FINEST> User attribute: accountExpires
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: logonCount
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: sAMAccountName
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: sAMAccountType
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: servicePrincipalName
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: objectCategory
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: isCriticalSystemObject
14:14:25.2240 */<ARSYS.AREA.LDAP> <FINEST> User attribute: dSCorePropagationData
14:14:25.2250 */<ARSYS.AREA.LDAP> <FINE> Found valid user

14:14:25.2250 */<ARSYS.AREA.LDAP> <FINER> LicenseMask=0 LicenseWrite=0 LicenseFTS=0 LicenseReserved1=0

Notification=3 Email=<NULL> LoginStatus=0 ModificationTime=0
14:14:25.2250 */<ARSYS.AREA.LDAP> <FINER> Groups=<NULL>
14:14:25.2250 */-VL OK
14.4 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.
14.4.1 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.
Implementing AREA authentication
1. Create a library (.dll or .so) to handle AREA API calls. See these sections:
Creating C plug-ins
Common plug-in C functions and Java methods
AREA plug-in C API functions
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.

14.4.2 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

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:
Authenticate Unregistered Users — If a user is not in the User form, BMC Remedy AR System tries external
authentication. See Authenticating unregistered users.
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.
To authenticate unregistered users
2. In the External Authentication Server RPC Program Number field, enter 390695.
3. Select the Authenticate Unregistered Users check box.

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,
AREA and then the AREA plug-in.
ARS - AREA - BMC Remedy AR System attempts to authenticate the user by using the User form, then the AREA plug-in, and then
OS Windows or UNIX authentication.
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
External Authentication Server RPC Program Number is 390695
User does not exist in User form

Authentication Authentication behavior
chaining mode
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.


chaining mode
ARS - OS - AREA
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
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

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
Authentication is performed using AREA LDAP. If successful, user information is retrieved from AREA 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 BMC Remedy AR
System.
If AREA LDAP authentication fails, the user is authenticated using OS authentication. If OS 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 BMC Remedy AR
System.
If AREA LDAP authentication fails, the user is authenticated using OS authentication. If OS 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

chaining mode
Off


chaining mode
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
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
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
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.
AREA behavior when the RPC program number is 0

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 Authentication behavior
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 Authentication behavior
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

chaining mode
Off
form.
If BMC Remedy AR System authentication fails, authentication processing stops.
ARS - AREA
form.
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 - AREA
form.
ARS - AREA - OS
form.
14.4.3 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.
Note
You do not need to configure the AREA Hub manually to use multiple AREA LDAP plug-ins. See
Configuring the AREA LDAP plug-in.
To set up the AREA hub plug-in
1. Create the following entry for the AREA hub in the ar.cfgfile:
Plugin: areahub.dll
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.

14.4.4 Enabling FIPS support for BMC Atrium SSO

BMC Atrium Single Sign-On (SSO) integration is Federal Information Processing Standards (FIPS-140) 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
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.
14.5 Data and database integrations

This section contains information about data and database integrations:
14.5.1 Creating vendor forms

In this topic:

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:
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.
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
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.

14.5.2 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.
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

Use BMC Remedy Developer Studio to create and modify view forms.
In this topic:
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. 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. 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.
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:
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
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 Character (limited length)
ntext,text Character (unlimited length)
int, tinyint, smallint Integer
real, float Real
decimal Decimal
datetime, smalldatetime Date/Time (default), Date, Time
image Attachment field in attachment pool

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 AR System field types
varchar, varchar2, char, nchar Character (limited length)
clob Character (unlimited length)
number Integer
float Real
number Decimal
date Date/Time (default), Date, Time
blob Attachment field in attachment pool
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 AR System field types
varchar, char Character (limited length)
text Character (unlimited length)
int, tinyint, smallint Integer
float, smallfloat Real
decimal Decimal
date Date
datetime, smalldatetime Date/Time
time Time
image attachment field in attachment pool
Database requirements for view forms

In this topic:
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.
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.

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
14.5.3 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

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 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.
14.5.4 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
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 Checking system requirements and supported configurations for
additional information about supported ODBC clients.
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.
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 Checking system requirements and supported
configurations.
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.
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. 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.
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.
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.
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
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
10. Select the form to include in your report, and click Next.
11. Click Next.
The wizard lists all fields in the underlying form.

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.
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
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.
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.
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.
14.6 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:
Note
This feature does not apply to BMC Remedy AR System release 7.5.00 or earlier.
14.6.1 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
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.)
14.6.2 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.
14.6.3 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 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.
14.6.4 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 .jar file, and open the index.html file.

14.6.5 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.
14.7 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
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 Checking system requirements and
supported configurations. 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.
14.7.1 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 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
14.7.2 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 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.
14.7.3 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.

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.
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 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.
14.7.4 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
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.
14.8 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
14.8.1 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

Atrium An ARDBC plugin that receives requests for executing and monitoring jobs from the AR System server, sends them to the Atrium
Integrator Integrator Carte server, then returns the Carte server results to the AR System server. Installed with your AR System server.
adapter
Atrium A GUI used to create and manage data integration jobs and transformations. Installed with your AR System server.
Integrator
Spoon client
Atrium A web server for data integration that allows remote job and transformation execution by accepting XML files that contain the job's
Integrator (or transformation's) execution configuration. Enables remote monitoring as well as starting and stopping of jobs and
Carte server transformations that run on the server. Installed with your AR System server.
Atrium 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
Integrator AR BMC Atrium CMDB. Installed with your AR System server and BMC Atrium Core installation. For more information, see Installing a
and CMDB stand-alone Atrium Integrator server.
plugins
BMC Remedy The AR System server.

AR System
server
BMC Remedy Forms that store jobs and transformation definitions and log files. The Spoon client can be used to access the repository.
AR System
repository
BMC Remedy Forms that are shipped with AR System or are created by you.
AR System
forms
Atrium Atrium Integrator ARDBC plugin front-end forms that allow job execution and monitoring on the Carte server. Installed with your
Integrator AR System server.
engine forms
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.
14.8.2 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.

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
14.8.4 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.
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

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:
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
14.8.5 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.
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

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
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
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

AR System Data Type Atrium Integrator Adapter Data Type
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.
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
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
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

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
The Edit Mapping button provides a helper dialog to map the fields.
Enter Mapping dialog from Field Mapping tab
AROutput data type conversions
Atrium Integrator Adapter Data Type AR System Data Type
None Null

Atrium Integrator Adapter Data Type AR System Data Type
Number Real
String Char
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

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

14.8.6 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

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

14.8.7 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.

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:

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.
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:
1. Open the transformation or job in the Spoon client.

2.
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 A connection to AR system is missing from a transformation step.
AR System connection.
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. 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 The ARInput step failed to fetch the string enum values for the Status field (AR Core field ID 7).
enum values
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 value to The ARInput step failed to convert the BMC Remedy AR System data type value to an Atrium Integrator value.
Pentaho 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 The ARInput step failed to fetch the Attachment value for a row.
field: {0}
Field {0} couldn't be found on form The AROutput step cannot find an AR System field contained in the field mapping.
{1}
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 The AROutput step cannot locate the stream field (fields from previous steps) and defined in the field
input stream! 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: The AROutput step failed to commit the bulk entry transaction.
{0}
More than one entry matched the Review the qualification and modify it to ensure that it matches one entry, or change the multi-match option
qualification and the multi match to update first or update all.
option is set to ERROR
Error while parsing matching The AROutput step failed to parse the specified matching qualification.
qualification
No or Empty Currency Code for The AROutput step cannot find the currency code for the currency field value.
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.
No conversion date for Currency The AROutput step cannot find the conversion date for the currency field value.
value for field {0}
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 A currency conversion between two different currency types was needed during the execution of a
Defined from {0} to {1} 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 Remove the External operator from the qualification.
in the matching 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. The AROutput step determined that stream fields (fields from previous steps) are used in the left side of the
Stream field {0} should be used on relation operation in the matching qualification.
the right hand side of a relational
operation. 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 The file path specified in the ARX File Input step or specified as a variable value is not found on the system.
step...java.io.FileNotFoundException:
Ensure that the file is present on the system.
Error while setting the private RPC An error occurred while setting the private RPC queue number on the AR connection.
Queue
Error while reloading the password An error occurred while reloading information from the UDM:RAppPassword form.
collection
Did not find Remedy Application The Remedy Application Service password for a server is missing from the UDM:RAppPassword form.
Service password for server {0} in
UDM:RAppPassword Form on server Add an entry for the server in this form.
{1}
Error while impersonating user {0} An error occurred while impersonating the provided user.
Error occurred while trying to create An error occurred while starting a client managed transaction on the AR connection.
transaction on the ARdatabase
No valid database connection No connection related information is defined on AR connection. Please define host, port, TCP port, RPC port,
defined! user name on connection to avoid this error.
Error occurred while trying to An error occurred while connecting to BMC Remedy AR System.
connect to the database

Error disconnecting ARdatabase: {0} An error occurred while disconnecting from BMC Remedy AR System.
Error performing commit on An error occurred while committing the client managed transaction on the AR connection.
connection
Error performing rollback on An error occurred while rolling back the client managed transaction on the AR connection.
connection
Error occurred while trying to get list An error occurred while fetching a list of form names from BMC Remedy AR System.
of tables
Error occurred while trying to get An error occurred while fetching a list of fields on a form from BMC Remedy AR System.
table fields
Error occured while trying to get An error occurred while fetching form entries from BMC Remedy AR System.
table entries
Error while converting AR value to An error occurred while converting an AR data type value to an Atrium Integrator value.
pentaho 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 An error occurred while writing a log record to the logging form, such as the UDM:TransformationLog form
form {0} or the UDM:JobLog form.
Error while fetching log records An error occurred while fetching log records from logging form such as, the UDM:TransformationLog form
from {0} form or the UDM:JobLog form.
Error while clearing log form entries An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog form
from {0} form or the UDM:JobLog form.
A log timeout was defined for log A log timeout value is defined in the logging setting, but the log date field is not defined on the log form.
table {0}, but it doesn't have a log
field 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 An error occurred while deleting log records from a logging form such as, the UDM:TransformationLog form
from log table {0} or the UDM:JobLog form.
Invalid selection value {0} for field The AROutput step found that the provided string value is not a valid string alias selection value for the enum
[Name - {1}, ID - {2}] 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 The AROutput step cannot convert a string value to a diary list field value.
diary list value1
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 a The AR System connection is not configured for an ARInput or AROutput step.
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 The Form name is not configured for the ARInput or AROutput step.
form name to
use Configure the form name for the ARInput or AROutput step by using the Browse button on the General tab of the step dialog.
No fields are Configure fields in the ARInput step.

specified.
Please add 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 in fields fields as needed.
tab.
Field with name A Field name specified on Fields tab was not found on the ARInput step form.
{0} does not
exist on form 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
{1} dialog to see all form fields. Delete or add fields as needed.
Invalid field ID A Field ID specified on Fields tab is non-numeric for the ARInput step.
{0}. Field ID
should be a 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
number. ARInput step dialog to see all form fields. Delete or add fields as needed.
Field with ID {0} A Field ID specified on Fields tab is not found on the ARInput step form.
does not exist
on form {1} Ensure that you entered the correct Field ID in the Fields tab in the ARInput step dialog. 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 {0} The Field Name for a Field ID is different than the actual Field name of the Field ID in the form definition.
does not have
name {1} on 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
form {2} 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.
No field Field mappings are not configured for the AROutput step.
mappings are
specified. Configure the field mappings with the AROutput step field mapping editor. To access the editor, press the Edit Mapping button on
Please specify Field Mapping tab of AR output step dialog.
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 AROutput step.
source fields
for this step
because of an
error: {0}
It was not The AROutput step dialog could not fetch AR fields from a form. Problems establishing a connection to the BMC Remedy AR
possible to System server might exist.
retrieve the
target fields for

this step
because of an
error: {0}
Certain The AROutput step dialog cannot find some stream fields (fields from previous steps) used in field mappings.
referenced
fields were not Check if the hop between the previous step and the AROutput step is disabled. If it is disabled, enable the hop and save the
found! These transformation. Also check if a field was removed from previous step but not removed from the AROutput step field mapping. If it
source fields was removed, remove it from the field mapping and save the transformation. In addition, check if the field is defined as an error
were not handling parameter in a previous step. If the hop between the previous step and the AROutput step is not defined as a normal hop
found: {0} or as an error hop, change the hop type from a normal hop to an error hop. Save the transformation.
Certain The AROutput step dialog cannot find BMC Remedy AR System fields specified in the field mapping. Check the mapping to ensure
referenced that the correct field names are used.
fields were not
found! These
target fields
were not
found: {0}
An ARX file is The ARX file path is not configured for the ARX File Input step.
not specified.
You must 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
specify the variable and supply the variable value at execution time.
correct ARX
file.
No schema The Form name is not configured in the ARX File Input step.
name is
specified, In the Spoon client, open the combo box for the ARX File Input step and enter the Form name.
please specify
schema name.
Chunk size Use a Chunk size value greater than zero in the ARX File Input step.
cannot be
blank, please
specify chunk
size.
No fields are You must configure fields in the ARInput step.

specified.
Please add 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
fields in fields 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 In a server group environment, the Atrium Integrator Engine Server Name field is not populated with
UDM:Config for entry ID {0} 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 A BMC Remedy AR System server's Remedy Application Service password is missing from the
password for server {0} in UDM:RAppPassword form.
UDM:RAppPassword Form on server {1}
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 The Atrium Integrator adapter ARDBC plug-in failed to remove an Execution Instance of a
instance {0} of transformation/job {1}on the transformation or job from the Carte server.
Carte server {2}: {message}
Review the Carte server error message and the arcarte.log file for more information about this error.
There was an error doing pause/resume for The Atrium Integrator adapter ARDBC plug-in failed to pause or resume an Execution Instance of a
execution instance {0} of transformation from the Carte server.
transformation/job {1} on the Carte server
{2}: {message} Review the Carte server error message and the arcarte.log file for more information about this error.
There was an error stopping the execution The Atrium Integrator adapter ARDBC plug-in failed to stop an Execution Instance of a transformation
instance {0} of transformation/job {1} on the or job from the Carte server.
There was an error starting the execution The Atrium Integrator adapter ARDBC plug-in failed to start an Execution Instance of a transformation
instance {0} of transformation/job {1} on the or job from the Carte server.
Repository Directory or Object ID is For the Create Execution Instance request, you must provide a Repository Directory or an Object ID
required for Operation for the transformation or job.
CREATE_EXEC_INSTANCE
There was an error posting the The Atrium Integrator adapter ARDBC plug-in failed to create an Execution Instance of a
transformation/job on the Carte server {0}: transformation or job on the Carte server.
{message}
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 The Atrium Integrator adapter ARDBC plug-in only supports a Search entry with a Get List Entry
form {0} 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 In the vendor forms that support Search, modify your qualification because only the AND conditional
supported only AND is supported operator (and not OR or NOT) is supported.
Only EQUAL relational operation is In the vendor forms that support Search, modify your qualification because only the EQUAL relational
supported for qualifier operator is supported.

Field {0} is not supported for query. In the vendor forms that support Search, check the associated Field IDs and modify your qualification
Supported fields for query are {1} 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 A transformation or job uses the UDM:PermissionInfo form, which specifies a Carte server name, but
UDM:Config form. 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 The Execution Instance name provided for the Create Execution Instance operation is not unique.
for transformation/job {1}
Provide a unique Execution Instance name.
Invalid Execution Instance. Execution The Execution Instance name provided for the Start, Stop, Pause, Resume or Remove operation does
Instance {0} does not exist or user {1}is not not exist in the database.
allowed to access it.
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 The transformation or job provided for the Create Execution Instance operation does not exist.
ID {1}, Directory ID {2}) does not exist Or
User {2} is not allowed to access Provide the correct transformation or job name and directory or object ID. If the transformation or job
transformation/job {3} 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.
Missing required parm {0} The schedule for the transformation or job requires a parameter.
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 {0}) The ARDBC plug-in failed to process an asynchronous UDM:Import task.
Invalid xml file. Root Element should be The transformation or job definition file attached to the UDM:Import record is not a valid file.
transformation or job
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 The UDM:Config form is empty.

details are present in UDM:Config
Add repository and Carte server connection information to the form so the Atrium Integrator adapter
ARDBC plug-in can process the transformation.
14.8.8 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
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 x
UDM:Execution Vendor x x
UDM:ExecutionInstance Regular x x
UDM:ExecutionStatus Vendor x x
UDM:Import Regular x
UDM:JobEntryLog Regular x x
UDM:JobLog Regular x x
UDM:LoggingChannelLog Regular x x
UDM:PermissionInfo Regular x
UDM:RAppPassword Regular x
UDM:RepositoryObject Vendor x x
UDM:ScheduleProcessor Vendor x

Form name Form type UDM Admin role access UDM User role access
UDM:StepLog Regular x x
UDM:StepPerformanceLog Regular x x
UDM:StepStatus Vendor x x
UDM:TransformationLog Regular x x
UDM:Variable Regular x x
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
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
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.
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

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

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

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 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
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

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

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


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

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.

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.
14.8.9 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.
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.
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.
14.8.10 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.)
14.9 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.
14.9.1 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 Integration
considerations.
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.
14.9.2 Triggering Run Process on clients and servers

The Run Process action can be triggered on both AR System clients and servers.
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.
14.9.3 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.
The Run Process action simply executes an independent process; it does not return a value to the calling
program.
Executing another application

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 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:

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

14.9.4 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

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:

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$


14.9.5 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.

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.
14.10 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.
14.10.1 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.
14.10.2 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.
14.10.3 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

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.
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.
14.10.4 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. 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.

8.
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

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

8.
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.
12. Click Save.
14.10.5 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:

('Support Group ID' = $Support Group ID$) AND ('Assignment

Availability' = "Yes") AND ('Assignment Availability 2' =
"Yes") AND ('Profile Status' = "Enabled")
6. Click Save.
14.10.6 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.
14.10.7 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.
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.
14.11 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).
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.
14.11.1 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
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.

14.11.2 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.
14.11.3 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 user’s 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.
14.11.4 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.
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.
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.
14.11.5 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.
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.
14.11.6 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.
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 5–10% 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.

15 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 Navigating the BMC Remedy AR System
System interface interface
Working with searches Running and saving 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 Using BMC Remedy Flashboards
15.1 Navigating the BMC Remedy AR System interface

The following topics provide information about how to navigate the BMC Remedy AR System interface:
15.1.1 Using the AR System Object List

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
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

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.
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:
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
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.
The following topics provide information about working with RTF fields:
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
underline formats
Subscript, Superscript, Select from the character options Subscript, Superscript, and Strike through. Applying RTF character
and Strike through formats
Text Color Select the text color from the list. Applying RTF character
formats
Text Background Select the text background color from the list. The options are Red, Blue, Green, Black, Applying RTF character
Color Yellow, and White. formats
Remove Formatting Remove all formatting from the selected text. Applying RTF character
formats
Show/Hide Hidden Select to show or hide the hidden elements. Applying RTF character
Elements formats
Note
You can use this option only with formatted text. However, if you format the text
using Subscript, Superscript, or Strike 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 character
formats
Indent Increase or decrease the selected text's distance from the left margin. Applying RTF character
formats
Bulleted and Create a list formatted with bullets or numbers. Applying RTF character
Numbered list formats
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 Using other formatting
characters. options
Spell Check Runs the spell checker. Using the spell checker in
the RTF

Button Function See also
Cut, copy, and paste Remove, copy, and paste selected text to and from the clipboard. 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
RTF shortcuts that work after text is selected
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 ( ) to edit the properties of a cell in a table. Cell properties include:
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 ( ) next to the character field.

2. Click the image button ( ) 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 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
new window check box is not selected, the URL's web page opens on the same browser.
4. Click OK.
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.
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
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.
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. Double-click the text or click to open the Link Options dialog box.
4. Click Remove link from text.
5. Close the Link Options dialog box.
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.
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 >).
6.

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.
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. 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.
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.
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.
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:

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. 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
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.
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
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.
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:
The term focus refers to keyboard focus, not to virtual cursor positions defined by certain assistive technologies.
Panel field shortcut keys

Panel field shortcut keys
Key Description
LEFT ARROW RIGHT If the focus is on a tab selector (an anchor link), sets focus to the next or previous tab selector without displaying it. Press
ARROW ENTER to display the selector.

Key Description
ENTER If the focus is on a tab selector, displays the page.
Character field menu shortcut keys

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.
Character field menu shortcut keys
Key Description
UP or DOWN ARROW Moves focus through the menu items. Press ENTER to fill the field with the menu selection.
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.
Form action shortcut keys

These keys work only when the corresponding form action button is visible and enabled.
Form action shortcut keys
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.
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.

15.1.2 Opening Approval Central

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.
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.
15.1.3 Copying field information to a new request

You can 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.
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. Add or modify information in the fields for the new request.
5. Click Save.
15.2 Running and saving searches

The following topics provide information about how to save and run searches on the web:
15.2.1 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

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.
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.
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
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 characters a through f,
and [abcf] matches the set of characters a, b, c, or f.
[^] (Square brackets Matches any single character not within a specified range or set. For example, [â-f] matches all characters except the range a
with caret) through f, and [âbcf] matches all characters except a, b, c, or f.
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.
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 ([^).
15.2.2 Running a saved, recent, or defined search

1. From the toolbar, select Searches > Run My Searches, Run Recent, or Run Defined.
Searches menu
2. From the list of searches, select a search to run.

The system executes the search and displays a results list.
Search results
15.2.3 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.
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.
15.2.4 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.
15.2.5 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.
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.
15.2.6 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:
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.
15.2.7 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.
15.2.8 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.
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

Enclose field labels in single quotation marks. For example:
'Short Description'
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

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
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 administrators use
this keyword.
$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.
$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.
$INBULKTRANSACTION$ Indicates whether you are in a bulk transaction. This keyword is not supported and is reserved for 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 administrators use this
keyword.
$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.
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.
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.
% 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.
_ (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 characters a through f,
and [abcf] matches the set of characters a, b, c, or f.
[^] (Square brackets Matches any single character not within a specified range or set. For example, [â-f] matches all characters except the range a
with caret) through f, and [âbcf] matches all characters except a, b, c, or f.
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.
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$
15.3 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:
The following topics provide information about report permissions:
Running reports
Setting permissions for a report
15.3.1 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
Finding reports
Running reports
Adding to or overriding a report query at runtime
Reporting based on a search

15.3.2 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
15.3.3 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.
15.3.4 Running reports in the Report Console

The following topics provide information about how to use the Report Console to run existing reports:
For information about creating reports, see Creating reports.
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.
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.
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.
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:
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.
Adding to or overriding a report query at runtime

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 to narrow the
report results (Show Additional Filter) or override the built-in query to widen or change the report results
(Override).
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.

In this topic:
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.
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, 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.
Reporting based on a search

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.
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.
3. Delete, disable, or enable reports as needed.

4. Click Save.
15.3.5 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

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.
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.
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. 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.
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. (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 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.
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 unique value in the
category field.
Maximum — Shows the maximum of the values in the series field for each unique value in the
category field.
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.
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
Is not equal to — Selects records in which the value in the chosen field does not match the value
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:
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.
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.
Defining BMC Remedy AR System reports

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

2.
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 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:

5.
Single — Displays all the statistical results on one line.

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.
Setting permissions for a 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:

2.
Active — Makes the report available in the Report Console.

Inactive — Indicates a report that is no longer active.
Pending — Indicates a report that is being reviewed.
If Inactive or Pending is selected, the report does not appear the Report Console list.
15.3.6 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 .
15.3.7 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).

Note
Only administrators and sub administrators can 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.
15.3.8 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 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 of the recipients to provide information about the report
status or errors that might occur while publishing the report.
5. In the Qualification to Use field, 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.
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.
15.3.9 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

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.
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.
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.
15.3.10 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
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
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.

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 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


15.
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:
Creating a new report with the BIRT Report Designer

Modifying an out-of-the-box Web report with the BIRT Report Designer
Creating a new report with the BIRT Report Designer

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
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. In the BIRT Report Designer, go to the Data Explorer tab, right-click Data Sources, and select New Data
Source.

1.
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. 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


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


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.
Modifying an out-of-the-box Web report with the BIRT Report Designer

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.

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.

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

This example explains how to customize the appearance of a new report by doing the following tasks:
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. 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.
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.
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.
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]
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.
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

9. Go to the Binding tab 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


12.
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

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. 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. 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:
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. 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.
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

6.
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

17.
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

b.
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.
15.4 Approving requests

The following topics provide information about how to approve requests:
15.4.1 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.
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:
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.
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.
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. 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

b.
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. 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.
15.4.2 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.
3.
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.
15.4.3 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.
15.4.4 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

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

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.
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:
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. 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.
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.
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. 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.
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:
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.
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.
Viewing and responding to More Information requests

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.
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.
Viewing and responding to More Information requests
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.
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

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.
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.
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.
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.
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:
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. 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.
15.4.5 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

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 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

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

5.
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.
Reassigning approval requests

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

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
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. 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.
15.5 Using BMC Remedy Flashboards

The following topics provide information about working with BMC Remedy Flashboards:
15.5.1 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.

15.5.2 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.
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

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:

2.
sortType
sortOrder
sortAttribute
sortIsAttributeEnum
For more information, see Display parameters for charts.
Note
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

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
15.5.3 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.
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.
15.5.4 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.
15.5.5 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 Description
field
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.

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 Displays a legend for the flashboard.

Legend
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.
15.5.6 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.

16 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 Navigating the BMC Remedy AR System
Administration console interface
Setting options in configuration files that are read upon startup of BMC Remedy AR System BMC Remedy AR System configuration files
components
Understanding processes or utilities and how to set options for BMC Remedy AR System AR System server components and external
components and external utilities 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 Setting user preferences
Preference form or the BMC Remedy Mid Tier
Managing time periods to define business schedules by using BMC Remedy AR System Defining business schedules using Business Time
commands
Configuring the server to allow workflow to notify users Enabling alert notifications
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 Enabling full text search
Configuring the appearance, functionality, and processing of your email Controlling BMC Remedy AR System through
email
Managing processes and rules for approval requests Setting up the approval process
Transferring and managing requests between multiple servers in various distribution Setting up DSO to synchronize data across
environments multiple AR System servers
Managing the capture of server-related activities, and notifying other servers or clients of these Capturing server events for workflow or API calls
changes
Auditing, archiving, importing, and exporting data, including other BMC Remedy AR System Managing data
database matters
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 Enabling Social Collaboration in BMC Remedy AR
Twitter alerts System

16.1 Navigating the BMC Remedy AR System 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:
16.1.1 Opening the AR System Administration Console

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.
16.1.2 AR System Administration Console introduction

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


The following sections describe the categories available in the AR System Administration Console.
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
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 Enforcing a password
policy introduction.
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.
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.
Currency Codes — See Localizing currency codes.
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
16.2 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.
16.2.1 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
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.
16.2.2 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
UNIX — ARSystemServerInstallDir/conf/ar.conf
Windows — ARSystemServerInstallDir\Conf\ar.cfg
Options
For ar.conf options, see:

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.
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: Server Information form.
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.
ar.cfg (ar.conf) file 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
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. 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 Information
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.)
AE-Poll-Interval 2 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.
AE-Worker-Thread Indicates the total number of worker threads that process various assignment requests (see
Configuring the 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.
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 Administration:
Server Information form. (See Setting administrative options.)
Allow-Unqual-Queries 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
Administration: Server Information form. (See Setting administrative options.)
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).
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-SQL-Stats-Control A bit mask value indicating options selected .
This option was added in Service Pack 1 for version 8.1.00.
API-SQL-Stats-Max-Saved-Long-Operations Maximum number of longest API and SQL operations 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).
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.
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 2 Base distinguished name (DN) to use instead of the root DN as the starting point for discovering
vendor tables when you design vendor forms. For example:ARBDC-LDAP-Base-DN: CN=Users,
DC=ldapesslab, DC=com
Maps to: The Base DN For Discovery field on the ARDBC LDAP Configuration form. (See Configuring
the ARDBC LDAP plug-in.)
ARDBC-LDAP-Cache-MaxSize 2 Size limit (in bytes) for the cache. For no size limit, set this to 0. The default is 32768 bytes.
Maps to: 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 2 Time limit (in seconds) that data remains cached. For no time limit, set this to 0. The default is 60
seconds.
Maps to: 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 2 Directory name of the certificate database. The cert8.db 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 only when
ARDBC-LDAP-UsingSSL is set to T.
Maps to: The Certificate Database field on the ARDBC LDAP 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 2 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
Maps to: The Host Name field on the ARDBC LDAP Configuration form. (See Configuring the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Key-DB 2 Not yet implemented.
ARDBC-LDAP-Key-Password 2 Not yet implemented.
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 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 2 Port number on which the directory service listens for clients.
Maps to: The Port Number field on the ARDBC LDAP Configuration form. (See Configuring the ARDBC
LDAP plug-in.)
ARDBC-LDAP-Time-Format 2 Format of LDAP date and time data. Values are
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 2 Distinguished name (DN) of the user account that the ARDBC LDAP plug-in uses to search and modify
the contents of the directory service. For example:ARDBC-LDAP-User-DN: server1\admin
Maps to: The Bind User field on the ARDBC LDAP Configuration form. (See Configuring the ARDBC
LDAP plug-in.)
ARDBC-LDAP-UsingSSL 2 Flag indicating whether to establish a secure socket layer (SSL) connection to the directory service.
Values are T and F. If you use LDAP over SSL, you must also specify the file name of the certificate
database used to establish the connection.
Maps to: The Using Secure Socket Layer field on the ARDBC LDAP Configuration form. (See
Configuring the ARDBC LDAP plug-in.)
AREA-LDAP-Bind-Password 2 Password of the user account that the AREA LDAP plug-in uses to find the user object when using the
User Search filter. If the distinguished name (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
user.
Maps to: The Bind Password field on the ARDBC LDAP Configuration form. (See Configuring the
ARDBC LDAP plug-in.)
AREA-LDAP-Bind-User 2 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
user. For example:AREA-LDAP-Bind-User: ldapesslab\admin
Maps to: The Bind User field on the ARDBC LDAP Configuration form. (See Configuring the ARDBC
LDAP plug-in.)
AREA-LDAP-Cert-DB 2 Directory name of the certificate database. The cert8.db 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 ARDBC-LDAP-UsingSSL is
set to T.
Maps to: The Certificate Database field in the Directory Service Information area on the AREA LDAP
Configuration form. (See Configuring the AREA LDAP plug-in.)
AREA-LDAP-Chase-Referral Flag that specifies whether referral chasing is performed by the AD server or the AREA LDAP plug-in.
Values are
2

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.
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.
Maps to: The Chase Referral field in the Directory Service Information area on the AREA LDAP
AREA-LDAP-Connect-Timeout 2 Number of seconds that the plug-in waits to establish a connection with the directory service. 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).
Maps to: The Failover Timeout field in the Directory Service Information area on the AREA LDAP
AREA-LDAP-Disable-Referral Flag that disables all referral processes by the AREALDAP plug-in. Values are
2
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.
AREA-LDAP-Email-Default 2 Value that the AREA LDAP plug-in uses if the AREA-LDAP-Email parameter is not specified or has no
value for the user.
AREA-LDAP-Group-Base 2 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.
$\AUTHSTRING$ — Value that users enter into the Authentication String field when they log in.
Maps to: The Group Base field in the User and Group Information area on the AREA LDAP
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 2

LDAP search filter used to locate the groups to which the user belongs. To determine the option's
values at runtime, use these keywords:

$\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.
Maps to: The Group Search Filter field in the User and Group Information area on the AREA LDAP
AREA-LDAP-Hostname 2 Host name of the system on which the directory service runs. If no value is specified, the AREA LDAP
plug-in uses localhost as the host name.
Maps to: The Host Name field in the Directory Service Information area on the AREA LDAP
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.
AREA-LDAP-Lic-Default 2 Value that the AREA LDAP plug-in uses if the 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 Value that the AREA LDAP plug-in uses if the AREA-LDAP-LicApp attribute is not specified or has no
value for the user.
AREA-LDAP-LicMask 2 Attribute that specifies how to mask the license information returned from the AREA LDAP plug-in.
Values are
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.
If the license is not used from the plug-in, the license information in the user's User entry is used.
Maps to: The License Mask field in the Defaults and Mapping Attributes to User Information area on
the AREA LDAP Configuration form. (See Configuring the AREA LDAP plug-in.)
AREA-LDAP-LicMask-Default 2 Value that the AREA LDAP plug-in uses if the 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 Value that the AREA LDAP plug-in uses if the 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 Value that the AREA LDAP plug-in uses if the AREA-LDAP-Notify-Meth attribute is not specified or has
no value for the user.
AREA-LDAP-Port 2 Port number on which the directory service listens for clients.
Maps to: The Port Number field in the Directory Service Information area on the AREA LDAP
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 2 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.
Maps to: The Group Membership field in the User and Group Information area on the AREA LDAP
AREA-LDAP-User-Base 2 User base in the LDAP directory to search for the user. To determine the option's values at runtime,
use these keywords:

$\DN$ — User's distinguished name. This only applies to the Group Base Name and Group
Maps to: The User Base field in the User and Group Information area on the AREA LDAP Configuration
form. (See Configuring the AREA LDAP plug-in.)
AREA-LDAP-User-Filter 2 LDAP search filter used to locate the user in the directory from the base that the
AREA-LDAP-User-Base option specifies. To determine the option's values at runtime, use these
keywords:

$\DN$ — User's distinguished name. This only applies to the Group Base Name and Group
Maps to: The User Search Filter field in the User and Group Information area on the AREA LDAP
AREA-LDAP-UseSSL 2 Flag indicating whether to establish a secure socket layer (SSL) connection to the directory service.
Values are T and F. If you use LDAP over SSL, you must also specify the file name of the certificate
database used to establish the connection.
Maps to: The Use Secure Socket Layer? field 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.
Arfork-Log-File Full path name of the file to use if arforkd logging is on (see Debug-mode). This file is not subject to
the maximum file size specified in the Max-Log-File-Size option.
ASJ-Thread-Count Specifies the total number of worker threads that process various approval requests.
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.
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)
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:
0 — 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.)
1 — No longer supported as a unique option. Defined the same as 3.
2 — No longer supported as a unique option. Defined the same as 3.
3 — (Default) Cache all form-display properties.

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.
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.
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.
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.
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 Delay, in seconds, between each retry of a deadlocked ARCreateEntry() function. Value is an integer.
2
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 Number of minutes between each refresh of currency conversion ratios on the client.
2
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.
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.
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
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-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.
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;
2
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
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 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 Remedy AR System server.
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
2
administrator call). Setting the option to 0 causes slower performance for cache operations. The default
value is 5 seconds.
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.
Disable-ARSignals Flag indicating whether automatic signals triggered by changes to the following data on a server group's
administrative server are disabled:
2
Archive definitions
Escalation definitions

Group information from the database
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 only those records whose field values have
changed (F, the default).
Disable-Client-Operation Option that restricts time-consuming operations (such as reporting) during busy times, improving overall
performance. The syntax is
2
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
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 Flag indicating whether escalations are allowed on the 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.
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.
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-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
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.
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

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

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.
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-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:
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. Use this format:DSO-Target-Connection:
serverName:RPCNumber portNumber
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.
While running the utility for all existing form , A user may see error "Error message ERROR (552): The SQL
database operation failed.; ORA-00942: table or view does not exist.", as the indexes are not applicable on below
forms.
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)
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:
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
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)
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).
Encrypt-Security-Policy 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 exchanged in plain text.
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
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
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 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.
Full-Text-Signal-Delay (Server groups only) Number of seconds before a signal is sent to the server that owns the
full text indexing operation (if no signal is 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 a
signal is pending, 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. 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 restricted read license when they log in to BMC
Remedy AR System. Values are
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 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.
Init-Form 2 Form opened every time any client logs in to the system. (This does not work on the mid
tier.) Workflow might be specified to record details of the login or to deny access based on
various parameters. Without this option, it would be necessary to attach the workflow to
every single form defined on the system.
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 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 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
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-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.
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 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:
Bit 8 (value = 128 ) for ARFORK.

Bit 16 (value = 32768 ) for the DSO server.
Bit 17 (value = 65536 ) for Approval Server.
Bit 18 (value = 131072 ) for the plug-in server.
Map-IP-Address 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
2
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
Max-Entries-Per-Query 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.
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.
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.
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.
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.
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

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)
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.
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.
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.
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 — If your Oracle database is set for SIMILAR, use this value.
Oracle-Dblink-Character-Set 2 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.
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.
Plugin 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

2 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 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
2
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 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
2
the number of threads for a plug-in as needed up to the specified maximum). The syntax is
Plugin-AREA-Threads: <minimumNumberOfThreads> [<maximumNumberOfThreads>]
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 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
2
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> [maximumNumberOfThreads>]
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 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.
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-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 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.

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.
Private-RPC-Socket (for debug Option that designates debug queues. A debug queue is a type of private queue used by the BMC Remedy AR
queue) 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
RE-Log-File-Location 2 Location of the Reconciliation Engine log file.
Read-Only-Tran-Off 2 Option that causes BMC Remedy AR System not to create database transactions when only reading data.

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 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.
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 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.
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
Required-Field-Identifier Character to add to the label of a field whose entry mode is Required. The default is an asterisk.
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.
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.)
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)
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
0 — (Default) No comment is required.

1 — A comment is required.
SCC-Comment-Checkout Flag indicating whether a source code control integration requires you to enter a
comment at checkout. Values are
0 — (Default) No comment is required.

1 — A comment is required.
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.
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 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
2
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
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).
Server-Group-Signal-Option Method that a server in a server group uses to notify other members of the group
about object definition cache changes. Values are
2
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 all-arsignald method. See
Configuring the server group signaling option.
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 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
2
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: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.
Server-Plugin-Default-Timeout 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>
Server-Side-Table-Chunk-Size 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.
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.
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
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.
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.)
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.

1/1/55 is interpreted as 1/1/1955.
1/1/30 is interpreted as 1/1/2030.
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).
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.
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
0 — (Default) Disabled
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.
VersionControl-Object-Modification-Log-Save-Definition-Files 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.
You can also set this option by using the Save Definition Files field on the Version
Control tab in the AR System Administration: Server Information 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
0 — (Default) Disabled
10 — Enforced
You can also set this option by using 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 256-bit AES algorithm for better
security.
This parameter is available only in Service Pack 1 for version 8.1.00 and later
versions.
XML-VUI-Export-Default-Is-Localized 2 Flag indicating whether to export localized views when forms are exported in XML
definition format. Values are T and F (default).
16.2.3 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:
(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.
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. 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.
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
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
}
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
}

16.2.4 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
Windows: ARSystemServerInstallDir\Conf\armonitor.cfg
UNIX: /etc/arsystem/serverName/armonitor.conf
Options
This file contains the following types of entries:
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

Option Description
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
16.3 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.
16.3.1 AR System server components

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
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.
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
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.
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
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 BMC Remedy AR System.
Synopsis
arserverd [-s serverName] [-i ARSystemServerInstallDir] [-l licenseDirectory] [-m] [-t]
[-checkdb [logFileNameWithAbsolutePath]]
Note

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, arsystem does
not modify ARCONFIGDIR if a preset value is found.
ARDATE

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.
(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.
successfully displayed but cannot be translated for input. If you do not set 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.
(Windows only) This value consists of a string of operators defined by Regional Settings. If you do not set
ARTIMEONLY, the system uses the date format specified in the Regional Settings of the user account that runs the
service.
successfully displayed but cannot be translated for input. If you do not set 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.
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
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> ]}
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 ./ <commandName> <commandOption1> <commandOption2> ...

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, arsystem does not
modify ARCONFIGDIR if a preset value is found.
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.
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

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
pluginsvr_config.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.
For information about locating the log4j_pluginsvr.xml and pluginsvr_config.xml files, see Installed plug-in
components.
16.3.2 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
In this topic:
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
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.
-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
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
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.
-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 ARSystemServerInstallDir/conf,
and you should not need to change this value. However, arsystem does not modify ARCONFIGDIR if a preset
value is found.
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.
arsignal.exe or arsignal
In this topic:
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.
-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
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.

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
16.4 Security administration

This section describes how to administer BMC Remedy AR System security. Topics include:
16.4.1 Creating users, groups, and roles

These sections provide an overview of BMC Remedy AR System users, groups, and 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
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.
2. From the AR System Administration Console, click System > Application > Users / Groups / Roles > User.
The User form opens in Search mode.
3. Choose Actions > New to switch to New mode.
4. Enter information in the appropriate fields, as described in the previous table.
To modify user information
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
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 To field 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.
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.
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.
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
User Login Name Identifying name that the user enters into the User Name field when logging in to BMC Remedy AR System. The
Information 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 Enforcing a password policy introduction.
User Full Name Full name of the user.

Information
User Password Identifying password that the user enters when logging in to BMC Remedy AR System. This field's length is 30 bytes,
Information 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 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 The access control groups to which the user belongs. If you leave this field empty, the user has only basic Submitter,
Information 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 Computed The names of the computed groups to which the User is a member. The members of a computed group are
Information Group List 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
Information operation.
User License Type Type of license that the user is assigned: Read , Restricted Read , Fixed, or Floating. The default is Read. See License
Information types overview for further descriptions of these types.
User Application List of application licenses granted to the user. For example, BMC Change Mgmt User Fixed, where BMC Change
Information License 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).
User Default Method by which the user is notified for Notify filter and escalation actions when User Default is specified. The
Information Notify default setting on the User form is Alert.
Mechanism
User Email Email address used to notify the user if email is the notify method.
Information Address
User Status Defines the status of the user account. This field is for information only. It does not change the status of a user's
Information 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.
Password Disable Disables password management for the user. If this check box is selected, when the User Password Management
Management Password Configuration form is updated, the user is not affected. For more information about password management, see
Management Enforcing a password policy introduction.
For This User
Password Dynamic The dynamic group to which the user belongs.

Management Group
Access
Password Last The last time the password was changed. BMC Remedy AR System automatically updated this field when a user's
Management Password password is changed.

Change for
Policy
Password Account The date the account was disabled, if applicable.

Management Disabled
Date
Password Force Indicates that the user must change the password. The next time the user logs in, the user is prompted to change the
Management Password password. After the password is changed, the check box in the User form is automatically cleared through workflow.
Change on
Login
Password Number of The numbers of days before a user's password expires if it is not changed.
Management Days Before
Expiration
Password Number of Indicates when a user receives a warning message before the password is set to expire unless changed.
Management Warning
Days
Password Days After The number of days after which a user's account is disabled if the password is not changed.
Management Expiration
Until
Disablement
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.
Note
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

Name of the access control group. Use this name in the Group list field in the User form and in the Permission and No Permission lists
when you are defining 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.
Group Maximum permission type intended for the group. Your choices are None (no access), View (view field contents), and Change (modify
Type 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 Additional information about a group. The text should be descriptive of the group because it appears by default in the Results pane in
Group the mid tier when listing groups.
Name
Group The group category, such as Regular, Dynamic, or Computed, which is described in Regular, computed, and dynamic groups. To define
Category 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 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
Group 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, provides the
Group 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.
For more information, see Groups in BMC Remedy AR System and Operations on objects restricted by development mode.
Computed Qualification string that defines a computed group. Construct the string from any valid combination of explicit group IDs, explicit
Group group names (in double quotation marks), user names (in single quotation marks), and operators such as AND, OR, and NOT.
Definition 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.
"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 Number of floating licenses reserved for the group. See About floating licenses in a license pool. If this field is missing from the Group
Licenses form, you can add it using Remedy Administrator. Use field ID 115. See Creating data fields.
Application Manually enter the information for this field. You can add more than one entry of application names and number of licenses, separated
Floating by a semicolon. Use the following syntax when providing users with application licenses:
License
_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 A unique identifier for the group. A unique identifier is useful if you have two groups with the same name for different applications. You
Identifier 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
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.
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
Form Name Access Details
Type
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 All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: actlink_call Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: actlink_dde Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: actlink_goto Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
actlink_group_ids
actlink_macro
actlink_macro_parm
actlink_mapping
actlink_message
AR System Metadata: actlink_open Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
actlink_process
AR System Metadata: actlink_push Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
actlink_serviceaction
AR System Metadata: actlink_set Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
actlink_set_char
AR System Metadata: actlink_sql Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: actlink_wait Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: arcontainer Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.


Type
arctr_group_ids
arctr_subadmin
AR System Metadata: arreference Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: arschema Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: char_menu Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
char_menu_dd
char_menu_file
char_menu_list
char_menu_query
char_menu_sql
cntnr_ownr_obj
escal_mapping
AR System Metadata: escalation Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: field Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: field_char Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: field_column Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: field_curr Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
field_dispprop
AR System Metadata: field_enum Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
field_enum_values
field_permissions
AR System Metadata: field_table Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.


Type
AR System Metadata: filter_call Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter_goto Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter_log Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
filter_mapping
filter_message
AR System Metadata: filter_notify Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter_process Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter_push Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
filter_serviceaction
AR System Metadata: filter_set Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: filter_sql Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Metadata: image Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
schema_archive
schema_audit
schema_group_ids
schema_index
AR System Metadata: schema_join Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
schema_list_fields
subadmin_group
vendor_mapping
view_mapping
AR System Metadata: vui Read All Metadata forms are used by Search, Analyzer and Workflow Viewer.
AR System Administration: Server Read This form is used by the Analyzer to read configuration data.
Information


Type
AR System Ignored Analyzer Read/Write This form is used by the Analyzer to store results marked as Ignored.
Results
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 Read/Write These forms are used to read and write administrator and user preferences.
Preference
AR System User Preference Read/Write These forms are used to read and write administrator and user preferences.
AR System Version Control: Object Read/Write These forms are used for Object Reservation feature.
Reservation
AR System Version Control: Object Read These forms are used for Label Management.
Modification Log
AR System Version Control: Label Read/Write These forms are used for Label Management.
AR System Version Control: Read/Write These forms are used for Label Management.
Labeled Object
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 Read This form is used in Set Fields action when Data Source is set to Webservice.
Configuration
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
Distributed Pool Read/Write These forms are used in Distributed Mapping and Distributed Pool editors.
DSO Distributed Logical Name Read Used by DSO Editors and DSO action to read logical names.
BMC Remedy Localization Toolkit: Read/Write This form is used by L10n Toolkit.
Items
BMC Remedy Localization Toolkit: Read These forms are used by L10n Toolkit.
Location Package Join
BMC Remedy Localization Toolkit: Read These forms are used by L10n Toolkit.
Location Package Link
BMC Remedy Localization Toolkit: Read/Write These forms are used by L10n Toolkit.
Locations
BMC Remedy Localization Toolkit: Read/Write This form is used by L10n Toolkit.
Translations
Read/Write This form is used by L10n Toolkit.


Type
BMC Remedy Localization Toolkit:

Translations Audit
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.
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.
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:
The following table lists the key fields in the Roles form.
Key fields in the Roles form

Field Description
Application Name of the deployable application for which the role is defined. You can define the same role for multiple applications, but you must
Name 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.
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
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.
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 is 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.
Overlay Group field set to 0
When a group assigned to the user has the Overlay Group field is 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.
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
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
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 BMC Remedy AR System.
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.
16.4.2 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.
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

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

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 0 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.
Administrator 1 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 2 Explicit Grants users the ability to customize their form view layout in the mid tier. Use this group with caution.
Submitter 3 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 4 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.
5 Explicit

Group ID Type Description
Sub Provides administrative access to selected server objects. Subadministrators, members of this group, can be granted
Administrator 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 7 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)
Group 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 8 Explicit Struct Admin members can create, modify, and delete AR server objects, but have no access to data or to
1 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 9 Explicit Struct Subadmin members can modify AR server objects subject to the same rules that govern Sub Administrator
Subadmin 1 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.
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 group C, but not members of group D.

Computed groups make groups easier to manage. You can manage your users in a limited number of
regular groups, and use computed groups based on these regular groups for more complex access control
without the need to make changes in multiple groups.
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
Type Description Predefined groups 1 Custom groups 2

of
access
control
group
Explicit A group to which you must assign users. Any regular and computed groups that you create.Regular
Administrator groups are groups to which you assign a specific list of users.
Sub Computedgroups are groups to which users are assigned based
Administrator on their memberships in groups included in an expression. For
Customize 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 Any dynamic groups that you create.Dynamic groups use the
implicitly) belongs by virtue of the contents of Public contents of special fields to determine group membership.
certain fields in a request. You cannot assign Submitter
users to implicit groups. All users are members of Assignee
Public. You use the other types of implicit groups Assignee
to control access to requests (row-level database Group
access).

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

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

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:
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

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 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

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 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

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:
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.

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.
Alice is a member of the Sales Staff group, which has maximum permission of Change. However, at the field level,
members of the Sales Staff group can only view the contents of this field.
Rick also can only view the contents of the Short Description field because he is a member of the Browser group.
Because the Browser group has maximum privileges of View, you can never give him Change permission for the
Short Description field through the Browser group as it is currently defined.
Active link permissions

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

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.
The following figure lists the questions that you can ask to determine the access that users have to requests in
Accessing requests

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 3 Submitter 2 Yes User name
Assignee 3 Assigned To 4 Yes User name
Assignee Group 7 None 112 No User, group, or role names
Dynamic groups 60000-60999 None 60000-60999 No User, group, or role names
You can also grant parent groups row-level access. For information, see Controlling access to requests for
hierarchical groups.
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.
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
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.
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.
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

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

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

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:
Form, active link guide, and application permissions

Field permissions
Active link 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 service Hidden Access to the object only through workflow.

Object Types Access level Access for users in the group or groups mapped to the role
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.
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:
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

6.
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.
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

5.
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. 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.
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.
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:
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.
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
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

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:
Enforcing restrictions on passwords
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:
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.
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.
Enforcing restrictions on passwords

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

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
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.
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:
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.
Setting up password expiration with scheduled warnings
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
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.
Disabling an account after the expiration period

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:
2.
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

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.

For more information about the BMC Remedy AR System Administration Console, see Navigating the BMC
Remedy AR System Administration console interface.
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).
To set advanced options
AR System Administration: Server Information form — Advanced tab
3. Edit the options listed in the following table as needed, and click Apply.
Default Web Specifies the base URL for the mid tier and is used by clients such as Flashboards. The URL appears as:
Path
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 For forms that contain hierarchical data, such as manager and employee relationships, specifies the
Depth for maximum number of levels in the hierarchy that a recursive query retrieves. By default, the maximum is 25.
Hierarchical Enter any integer greater than 0. See ARGetListEntryWithMultiSchemaFields.
Query

Maximum Specifies the maximum number of temporary tables that can exist on an AR System server for a single
Vendor vendor form. The ARGetListEntryWithMultiSchemaFields function stores data from vendor data sources in
Temp these tables. By default, only one temporary table can exist for each vendor form. This setting applies to all
Tables vendor forms on the server. It is overridden by the value of an individual vendor form's Maximum Vendor
Temp Tables property
Email Suppress Suppresses the server domain in the URL. The option is clear by default.
Server
Domain in
URL
Maximum Specifies the maximum line length that can be in an email. The default is 1024. If a single line of the message
Line Length is over this length, a return is automatically inserted. Limits the line length of email messages passed
in Email through the mail server to protect users from excessively long lines.
Email Specifies the base URL that appears in email notifications. If this field is left blank, the Default Web Path is
Notification used. (The Email Notifications Web Path field is available because the Default Web Path is specified for other
Web Path 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 Active Link Specifies the only directory that the Run Process active link action can run from, for example, C:\arsys. If no
Run Process directory is specified, active link processes can run from any directory.
Directory
Active Link Specifies the type of shell the Run Process action can use, for example, /bin/csh. If no path is specified,
Run Process administrators can specify any shell.
Shell(UNIX
servers only)
Allow Enables the administrator to use the arcache and arreload utilities. See arcache.exe or arcache and
arcache and arreload.exe or arreload. The option is selected by default.
arreload
Client Maximum Specifies the maximum number of concurrent client-managed transactions. The default is 10, and the
Managed Concurrent maximum value you can enter is 100.
Transaction Transactions
(CMT)
Configuration
Transaction Specifies the maximum time (in seconds) allowed to hold a transaction before a timeout occurs. The default
Timeout 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 Localize Enables the administrator to enable or disable localization of the server. Selected indicates that the server is
Error Server localized and enabled for such tasks as searching entries in localized forms, or using AR System Message
Messages 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.

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 Displays the name of the form the server uses to resolve error messages when "Localize Server" is selected.
Form Name For more information about the AR System Message Catalog form, see Localizing messages manually.
Filters Maximum Specifies the number of filters that can be performed in an operation. The default and recommended
Filters for an number is 10000. Increase this number at your own risk only if you reach a limit in your system and you
Operation have verified that your workflow is valid.
Maximum Specifies the maximum number of nested filters and filter guides that execute to prevent recursive actions
Stack of on the server. The default and recommended number is 25. Increase this number at your own risk only if
Filters you reach a limit in your system and you have verified that your workflow is valid.
Server Server Specifies how the server records server statistics. Select one of the following options: Off, the default, do
Statistics Recording not record server statistics; Cumulative Queue, record a cumulative statistic that is a combination of all the
Mode 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 Specifies how often the server records server statistics. The default is 60 seconds. Remember that one
Interval (Cumulative Queue) or more (Cumulative and Individual Queue) entries are recorded in the Server Statistics
(seconds) 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.
Server Group Server If the server belongs to a server group, specifies the name of the group. All servers in the server group share
Group this setting.
Names
Check Specifies how often the server communicates with other servers in the group. Each server can register its
Interval own status, determine whether any server is delinquent, establish the parameters needed for sending
signals, and determine operational responsibilities. The default value is 30 seconds, the minimum is 10
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 Preference Specifies where user preferences are read from. The options are User Defined, where users can choose
Server Server whether to use a preference server, and this server might or might not be used depending on whether the
Option 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 If the number of preload threads is not zero, specifies whether the threads are used only at server startup or
Tables Tables At for all cache reloads from the database. See Setting the Preload Tables Configuration option. The values are
Configuration Init Only Yes, if preload threads are 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 Specifies the number of preload threads used when information is loaded from the database into the server
Preload cache. The maximum value is 30 or twice the number of preload segments, whichever is lower. The server
Threads 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.
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

Number of 1/3 the number of schemas (forms) in the AR System server. See Setting the Preload Tables Configuration
Preload option. For information about the corresponding configuration file setting, see
Segments "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.
16.4.3 Setting up an authentication alias

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

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.
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.
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
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.
16.4.4 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
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.
16.4.5 Defining your user base

This section provides instructions for managing information about your BMC Remedy AR System users. Topics
include:
See the following sections for related information:
Viewing user license information

Enabling submitters to modify requests
Setting up an authentication alias
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:

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 Description
type
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 Enables users to create, search for, and display requests within their assigned permissions. Users with Restricted Read licenses cannot
Read 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.
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 BMC Remedy
AR System.
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.

If the user does not log out of the mid tier correctly, the release of the license is delayed. See the License
Release Timeout 30 -300 Seconds row in the General Settings parameters table on the Configuring the
General Settings page section.
A user's mid-tier session times out.
For more information about mid-tier session timeouts, see the License Release Timeout 30 -300 Seconds
row in the General Settings parameters table on the Configuring the General Settings page section.
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.
In addition, administrators can manually terminate a user's session one time in a 24-hour period by using
the following procedure.
To release a floating license
1. In a browser, open the BMC Remedy AR System Administration Console, and click System > Application >
Users/Groups/Roles > License Review.
2. From the Category list in the Manage User Licenses form, select Current Licenses.
3.
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's license information reappears.
6. Click Close.
Viewing user license information

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
1. In a browser, open the BMC Remedy AR System Administration Console, and click System > 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
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.
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.
16.4.6 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:
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 Configuring after installation.
See Using IBM DB2 Universal Database with BMC Remedy AR System for DB2-specific information.
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 Configuring after
installation.
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.
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
Microsoft SQL Server 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
16.4.7 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.

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 Description

Distributed
Server Option
log file
ardist.log Contains information about the DSO server.
ardist.default.log Contains information about the default distributed pool.
ardist. Contains information about a custom distributed pool. Windows log file names In a Windows environment, if the name of a
poolName.log 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 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.)

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 **** 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.

16.5 Setting user preferences

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.
16.5.1 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 Preference form by using the
User 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 Types of browser searches for your end users
form Security administration
AR System Stores preferences for BMC Remedy Developer Studio and BMC Remedy Data Import. By default, this form has administrator
Administrator permissions only. You might want to define subadministrator permissions. Display preferences and the list of login servers are stored
Preference in the AR System User Preference form. Developer Studio and Data Import users can also access these preference settings in the
form 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.

16.5.2 Restricting preferences from users

To restrict preferences, remove Public permissions from individual fields in the AR System User Preference form.
16.5.3 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 AR Server Settings page.
16.5.4 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 — Advanced tab

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.
16.5.5 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 Server The local preferences are used (ar.ini file).
field blank
Specifies a valid preference The system connects to the preference server, and the Accounts list is updated to reflect the list of servers
server specified on the Server List setting.
Specifies an invalid preference The local preferences are used (ar.ini file).
server
"Use This Server" or "Use Other Server" behavior
Leaves the The system searches the Accounts list for a server designated as a preference server. If one is found, the server name is written to
Preference the Preference Server field of the Login dialog box. In addition, the accounts list is updated to reflect the list of servers specified on
Server field the Server List setting for that preference server.
blank
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 The system connects to the preference server, and the Accounts list is updated to reflect the list of servers specified on the Server
valid List setting for that preference server.
preference
server
Specifies an The system searches the accounts list for a server designated as a preference server. If one is found, the server name is written to
invalid the Preference Server field of the Login dialog box. In addition, the accounts list is updated to reflect the list of servers specified on
preference the preference server.
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.
16.5.6 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

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
Login 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 name in this field. Users can search for and modify their own preference records. The default setting is $USER$.
Short Lets the administrator create, search for, and modify preferences based on a value in this field. The default setting is Preference entry
Description for $USER$.
Status Not used.
Create The date the record was created. This field is display-only.
Date
Modified The date the record was last modified. This field is display-only.
Date
Last The login name of the user who last modified the record. This field is display-only.
Modified
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

Accessibility tab fields

Area name Field Description Client
Name
Accessibility Accessible Generates the HTML page so it is optimized as follows: Web

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 Designates the type of nonvisual feedback that applies to workflow for this view. The options are Legacy*
Message
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
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 Field Name Description Client

name
Form Default Form Specifies the view to be used as the default for all forms. Legacy*
View
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 Specifies the extension to be used as the default for all forms opened from other forms. Legacy*
Window
View
Extension 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 Specifies which forms are available. Options are Legacy*

Hidden
Forms No — Only forms designated as visible are available.
(Admin) 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.
Table Refresh Specifies whether the data in a table field is refreshed automatically every time a form is displayed. Web
Fields Content on
Display
Note
The user can refresh the table manually by clicking on it.
Report Report Specifies the name of the server where the following reporting forms reside: Web
Server
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.
ODBC Use Specifies whether to replace special characters with underscores when running reports. Using underscores is Legacy*
Underscores important if the user is running Crystal Reports and field or form names contain special characters.
Result Alert Sort Displays the last column on which the user sorted a result or alert list. The user can specify a value in this field. Legacy*
View
Sort Criteria Displays the value set when the user chooses Actions > Sort Options and specify values. The user can set sort Legacy*
options on a per-form basis.
AR AR System Reserved for future use. N/A

System Reserved
Reserved
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*
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 with a .log file N/A*
extension.
Open Alert List Designates which application should be used to open the Alert List. The options are Web
using
AR System User
Web
Server Designates the server to be used to open the Alert list. N/A*
On Startup Display Alert Designates whether to display alert information when received. N/A*
Message
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

name
Confirm After Creating a New Defines whether a confirmation appears after a request is created. The options are Web
Request
No — (Default) The entry is submitted without verification.
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 options are Legacy*
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 Defines whether a confirmation appears when the user tries to delete a saved search. The Legacy*
Search 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

name
Table Table Field Information about a table field that BMC Remedy AR System saves when the user changes the size of columns Legacy*
Field Column in the table field, including the server name, form name, table field ID, column ID, and the size of the column.
Width
Table Field Column order preference. Legacy*

Column
Order
Table Field Not used. N/A**

Column Sort
Table Field Interval at which tables automatically refreshes (in minutes). Valid values are 0-99. Web
Refresh
Interval
Schema Column Information about a results list that BMC Remedy AR System saves when the user changes the column size in a Legacy*
Width results list.
Column Information about a results list that BMC Remedy AR System saves when the user reorders the columns in a Legacy*
Order results list.
Grid Height Parameter set in Customize View mode by choosing Layout > Grid Size and specifying a value. Legacy*
Grid Width Parameter set in Customize View mode by choosing Layout > Grid Size and specifying a value. Legacy*
App Flag that specifies whether to display extra field name and ID information in the field Help text. Values are: Legacy*
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 Upper limit for the number of items a menu can have. Used for currency and edit field menus. Legacy*
Base Menu
Items Per Obsolete. N/A**

Column

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 of the list menu window. Legacy*

Width
List Menu Height of the list menu window. Legacy*

Height
List Indent Space in pixels on left before list items in list menu. Legacy*
Items When smart menus is selected, the number of items where menus change from pop-up to list menus. Web
Threshold
Level When smart menus is selected, the number of levels where menus change from pop-up to list menus. Web
Threshold
Edit Diary Width Diary editor window width. Legacy*

Diary
Field Diary Height Diary editor window height. Legacy*
Edit Text Width Text editor window width. Legacy*

Text
Field 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 logging or other
clients.
Setting the General tab

AR System User Preference form — General tab
AR System User Preference form — General tab
Field Name Description Client

Area
name
Search Search Path Designates the directories where the user can access custom reports and macros. The path is typically Legacy*
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 The number of recently used items. The user can specify from 4 to 9 items. The default is 5. This setting applies to Legacy*
in Recently these menu lists in the browser:
Used List
File > Recent New Forms
File > Recent Search Forms
File > Recent Requests
File > Recent Entry Points
Actions > Recent Searches
Tooltip Hover Wait Specifies the amount of time (in milliseconds) that the system waits to display a tool tip after the user hovers over Web
Hover Time in an object.
Wait Milliseconds
Time
On On New Defines how fields are set in a form opened in New mode. The options are: Web
New
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 On Search Defines the action a form opened in Search mode takes after the user performs a search, displays the records in Web
Search modify or display mode, and then returns to the search form without closing the form. The options are:
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 Defines whether the user views only the results list after every search. If the user selects No, the results list and a Web
List Only detail pane are displayed after every search.
Limit Defines whether the number of search results returned is limited. The options are: Web
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 Show Defines whether to show the advanced search bar when a new window is opened. Web
Open Advanced
Search Bar
Maximize Defines whether a form is maximized when it is opened. If the user selects No, the form fills only a portion of the Web
Window browser.
Diary Show Most Defines the order in which entries appear in the diary field of a form. The options are: Web
Field Recent First
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.
Field Display As Specifies how menus attached to a character field are displayed. The options are: Web
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 Determines whether field menus are expanded when the menu is opened. The options are: Legacy*
Startup
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 Designates whether forms have a flat or 3-D look. The options are: Legacy*
On Forms
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 Field Description Client

name Name
Home AR Designates the name of the server that contains your home page. For more information, See Configuring home page Web
Page Server preferences.
Form Designates the name of the form to be used as the default home page when the user logs in. For more information, Web
Name see Configuring home page preferences.
Object Defines to what degree the Object List is enabled. Legacy*

List
Enable, Show All — The Object List lists all the applications, guides, and forms on the servers that the user is
logged in to.
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

name Name
Locale Web

User Designates the language displayed on the user's system, in the format language _country, where language is the
Locale 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 Defines the time zone displayed on the user's system. Select a time zone from the menu, for example, Asia/Tokyo, Web
Zone America/New York, or Europe/Paris. Any ICU (International Component for Unicode) format is accepted. This field is
clear by default.
Display Defines the format in which the date and time appear. According to Windows format, the options are: Legacy*
Date/Time
Style 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.
Custom Defines the custom Date/Time length format. This field is active only when Custom is selected from the Display Legacy*
Date/Time Date/Time Style menu list. To customize separators and other options, the user must use a predefined Windows
Format 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 currency is specified Web
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


name
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 Web
Remedy AR System server are logged.
Server 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 Global Logging For future use.

Enabled
Log File Path Defines the path to the log file. Web
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
Open Dialog Shortcut Dir Indicates the directory to use when creating a shortcut. This value is used when the user selects an item Legacy*
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 Not currently used. Legacy*
Performance Preferences that relate to how the browser caches forms. Definitions (for forms and related workflow) are Legacy*
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 If the Duration Since Last Used value is greater than the preference set for Max Age In Minutes, the form Legacy*
Minutes definition can be removed from the memory cache.
Min Age In If the Duration Since Last Used value is greater than the preference set for Min Age In Minutes, the form Legacy*
Minutes 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 Each time a form is opened, the system increments a usage count. As the memory limit is approached, the Legacy*
Threshold Usage Threshold value is compared to the usage count to determine if the definition can be removed from
the memory cache.
Percent Of Represents a memory threshold. It is compared to the percent of memory used for the memory cache to Legacy*
Memory determine if the memory limit is reached. This check is used in conjunction with the Usage Threshold and
the Min Age In Minutes values.
App DDE Application Response Timeout in the browser. Legacy*

Response
Timeout
Transaction DDE Transaction Timeout in the browser. Legacy*

Timeout
RPC Timeout RPC Timeout for submits in the browser. Legacy*

Normal
RPC Timeout RPC Timeout Long queries in the browser. Legacy*

Long
RPC Timeout RPC Timeout for extra long operation in the browser. Legacy*
Extra Long
View Show Macro Designates whether the macro bar is displayed when the browser starts. Legacy*
Bar
Show Status Designates whether the status bar is displayed when the browser starts. Legacy*
Bar
Show Designates whether the toolbar is displayed when the browser starts. Legacy*
Toolbar
Disable Web Designates whether items under BMC Remedy on the Web under the main Help menu in the browser are Legacy*
Help disabled.
Save Designates whether to save information about open New and Search windows in the browser when you Legacy*
Window On close the tool.
Close
Query On Designates whether you can initiate a query by pressing the Enter key in the Request ID field. Legacy*
Return
Close After Designates whether to close a New window after a request is submitted in the browser. Legacy*
Submit

Show Lang Obsolete. Legacy*

DLL Not
found
Step Size Obsolete. Legacy*
Result Open Designates which panes open when you double-click a record in a results view. The options are: Legacy*
On
Double-Click 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
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

name
Default Left MarginRight Defines the number of blank characters from the left or right edge of the page. The default for the left and Web
Margins Margin right margin is 0 characters.
Top Margin Defines the number of blank lines from the top or bottom edge of the page. The default value for the top Web
Bottom Margin and bottom margin is 1 line.
Default Column Titles Defines the default characters to separate column titles, columns, or requests, respectively. By default, Web
Separators ColumnRequest column titles are separated by hyphens (-), and columns and requests are separated by a blank space. You
can use any of these special characters:
\b (backspace)
\n (return)
\t (tab)
*
* (backslash)
** nnn (ASCII character)
Default Orientation Defines whether the default page is in Portrait or Landscape mode. Web
Page Size
Use printer Designates whether the default page size should correspond to the default printer page size. Web
default page
size
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
Misc. Column Title Designates a default value for how often column titles appear in a report. The options are: Web
Default Per
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 logging or other
clients.
Setting the Web tab

AR System User Preference form — Web tab
Web tab fields

name Name
Report Crystal Designates an application for viewing Crystal Reports. Options are Web
Report
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 Refresh Specifies the interval, in minutes, that passes between queries to the Alert Events form. The default value is 0. The Web
Interval alert list displays the user's alerts by querying the Alert Events form that contains the user's alerts.
Alert Specifies which servers contribute alerts to a web-based alert list. The administrator can enter the server names to Web
Servers retrieve alerts from this field. The server names must be separated by the comma ( , ) delimiter. This field is clear
by default.
Date/Time Display Specifies the format in which the date and time appear. Options are Web
Text Date/Time
Style Short
(Web) Long
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.
Custom Specifies the format of date strings to be displayed in the browser if the user selects Custom from the Display Web
Date Date/Time Style (Web) menu. The user can add a forward slash (/), dash (-) or a period (.) as separators. This field is
Format clear by default. For more information about date formats, see AR System server components and external
utilities.
Custom Specifies the format of time strings to be displayed in the browser if the user selects Custom from the Display Web
Time Date/Time Style (Web) menu. The user can add a semicolon (:), dash (-), or a period (.) as separators. This field is
Format clear by default. For more information about time formats, see AR System server components and external
utilities.
Session Session Specifies the number of minutes after which a session times out. The default is 90 minutes. The user can set the Web
Timeout session timeout for longer than 90 minutes, and this setting overrides the session timeout in the General Settings
in Minutes page of Mid Tier Configuration Tool.
Animation Animated Specifies whether animated field effects (which show conditions such as state transition) are enabled. Web
Effects
Setting the Window tab

AR System User Preference form --- Window tab
Window tab fields
Window Size Pick/Selection List Selection List window position. Legacy*
Toolbars Summary Coded information about toolbars. Legacy*
Bar0 Coded information about toolbars. 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 Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days, four-digit year) 01/01/2009
01/15/2009
MM/dd/yy Month, Day, Year (leading zero for single-digit months, leading zero for single-digit days, two-digit year) 01/01/09
01/15/09
MM/d/yyyy 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 Day, Month, Year (leading zero for single-digit days, leading zero for single-digit months, four-digit year) 01/01/2009
15/01/2009
dd/MM/yy Day, Month, Year (leading zero for single-digit days, leading zero for single-digit months, two-digit year) 01/01/09
15/01/09
dd/M/yyyy Day, Month, Year (leading zero for single-digit days, four-digit year) 01/1/2009
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

Short Date Format Description Examples
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 Year, Month, Day (four-digit year, leading zero for single-digit months, leading zero for single-digit days) 2009/01/01
2009/01/15
yyyy/MM/d Year, Month, Day (four-digit year, leading zero for single-digit months) 2009/01/1
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
yy/MM/dd Year, Month, Day (two-digit year, leading zero for single-digit months, leading zero for single-digit days) 09/01/01
09/01/15
yy/MM/d Year, Month, Day (two-digit year, leading zero for single-digit months) 09/01/1
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

Format Example
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
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
16.5.7 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.
16.6 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.
16.6.1 Business Time introduction

In this topic:
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.
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 Time Shared Entity-Entity Association_Join_Join — Used for query purposes. Acts as a join form
between the following forms:
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 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 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
Workday and activities for one day

The application commands described in Business Time 2.0 commands work from the final list.
16.6.2 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
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
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.
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.
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.
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. 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. 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.
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.
16.6.3 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.
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
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:

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

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
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 PM are
Unavailable).
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 PM are
Unavailable).
The following figure illustrates this example.
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.

16.6.4 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

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.
<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-Time2-Assoc-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).
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:
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>"
[HTMLUATarsadministering1030:" <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> " "<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>"
[HTMLUATarsadministering1030:"<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>"
. . . ]]]
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>.
Use the following syntax for the Application-Bus-Time2-Get-Next-Window calculation:

Application-Bus-Time2-Get-Next-Window "<startTimeRange>" "<endTimeRange>"
[HTMLUATarsadministering1030:"<duration>"] [HTMLUATarsadministering1030:"<windowFlag>"]
. . . ]
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>"
[HTMLUATarsadministering1030:"<level>"] [HTMLUATarsadministering1030:"<duration>"]
[HTMLUATarsadministering1030:"<earliestStartTime>"]
[HTMLUATarsadministering1030:"<latestEndTime>"]
. . . ]

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

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
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

"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.).
Earliest Start Time is specified or unspecified scenario

"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

"" "" "" "Work1" "Act1" "Act2" "Act3"
If the duration required is two hours, "" is returned for Level 2.
Duration of 7200 seconds scenario

"" "" "" "Work1" "Act1" "Act2" "Act3"
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:
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.
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).
Business Segment-Entity Association commands

In this topic:
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>" . . .
[HTMLUATarsadministering1030:-e "EntityID1" "EntityID2"... ]]]]
Application-Bus-Time2-Assoc-Diff
Use the following syntax for the Application-Bus-Time2-Assoc-Diff calculation:
Application-Bus-Time2-Assoc-Diff "<startTime>" "<endTime>"
[HTMLUATarsadministering1030:-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>"
[HTMLUATarsadministering1030:-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>"
. . . [HTMLUATarsadministering1030:-e "EntityID1" "EntityID2" . . . ]]
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>"
[HTMLUATarsadministering1030:-e "EntityID1" "EntityID2" . . . ]]
Application-Get-Next-Recurrence-Time
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.
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:
Application-Get-Next-Recurrence-Time <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.
16.6.5 Using the old Business Time forms

This section describes the following forms:

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
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
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.
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.)
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
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.
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:
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 0-24 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 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.
Old Business Time commands

The following commands in this topic were used in the old Business Time scheme.
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>"
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.
16.6.6 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
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.
16.7 Enabling alert notifications

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.
16.7.1 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
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.
16.7.2 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.
16.7.3 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.
16.7.4 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.

16.7.5 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.
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

Registered The AR System login name of the user being registered for alerts.
User
Registered The time that the user registered. This is the Modified Date core field and represents the time when the entry was created or modified.
Time BMC Remedy AR System uses this field to determine if the user registration has expired and to identify unsent alerts.
Expiration 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
Time (secs) 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 Used for optional supporting information. If you do not need to use this field, leave the default value N/A in the field.
Description
Plugin Defines the way alerts are sent for this user registration. The drop-down field menu takes its entries from the AR System Alert Delivery
Name 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.
Plugin Defines the destination to which alerts are sent for this user registration.
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 Used to store a value that must be encrypted. For, example if a plugin requires a password, store the password in this field.
Plugin
Values
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
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 when an alert is
Sent Flag 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.
16.7.6 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
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.
16.7.7 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.

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>

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>




<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>
16.8 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.

If multiple assignees are available, the certain predefined assignment methods are used to identify an assignee for
the request. See Integrating the BMC Remedy Assignment Engine into an application.
16.8.1 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 is assigned 5 issues and has a capacity rating of 10, and person B is assigned 8
issues and has a capacity rating of 20, person B is selected (8/20 < 5/10). If two or more people qualify for
an issue, it is assigned to the first person retrieved from the database.
16.8.2 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.
16.8.3 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.
16.8.4 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):
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.
16.8.5 Assignment Engine forms

The following table lists the forms that are installed when you install BMC Remedy Assignment Engine.
Assignment Engine forms
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.
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.
16.9 Enabling full text search

Full text search (FTS) is an optional feature that you can install with the BMC Remedy AR System server. This
section discusses the capabilities, performance, and administration of the FTS feature.
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 .
Performing case-insensitive searches. Administrators can enable or disable case sensitivity.
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.
16.9.1 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.)
16.9.2 Setting up FTS to search across multiple forms

You can set up full text search (FTS) to search across multiple forms.

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
1. In BMC Remedy Developer Studio, open the form.

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

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.
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.
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 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
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"
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
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

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.

2.
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"
16.9.3 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:
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

2. Click the FTS tab.
3. Select the Reindex check box.
4. Click OK.

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
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.
For more information, see Configuring forms for multiple-form FTS.
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 server for the
changes to take effect.
16.9.4 Defining a field for FTS

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.
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:
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.
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.
16.9.5 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

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

16.9.6 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

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
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
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%" firewall blocks access +

<field> LIKE "%firewall blocks%" firewall blocks access +
firewall blocking my access
firewall blocked her access
have the firewall block access
<field> LIKE "blocks" firewall blocks access +
firewall will block access +
firewall did not block access +
try blocking his access +
<field> LIKE "%blocks%" firewall blocks access +
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
<field> LIKE "firewall,blocking" firewall blocks access +
firewall is not working +
try blocking his access +
<field> LIKE "firewall,blocked%" firewall blocks access +

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
<field> LIKE "firewall" firewall blocks access
<field> LIKE "firewall will block access" firewall blocks access

<field> LIKE "%firewall%" firewall blocks access +
<field> LIKE "firewall%" firewall blocks access +
<field> LIKE "blocks" firewall blocks access

<field> LIKE "%blocks%" firewall blocks access +
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.
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
QBE Match Effect on search criteria

property
setting
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 clien 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.
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).
16.10 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.
16.10.1 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 A mail server that acts as a failover system, assuring uninterrupted processing of messages, when the primary mail server stops
mail server working. You can define this by using the BMC Remedy AR System Email Failover Mail Server form. For more information, see Multiple
mail server support.
Email A user account on a mail server that permits a user to transmit or receive email messages.
account
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 from a specific
mailbox 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 A mailbox containing the information required by BMC Remedy Email Engine to create and send messages. BMC Remedy Email Engine
mailbox 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.

Term Meaning in the context of BMC Remedy Email Engine
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.
16.10.2 How BMC Remedy Email Engine works

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.

1.
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. 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


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

5.
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.
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.
16.10.3 Setting up outgoing email

This section provides the following information and instructions for creating and transmitting outgoing email
messages from the Email Engine:
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

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

1.
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:
Configuring outgoing mailboxes

Defining a workflow to send email notifications
Types of outgoing email
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
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.
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.
Defining a workflow to send email notifications

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.
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.
Tip
This section borrows from the Email Engine: Administering (Webcast) available from BMC Remedy
Education Services. This webcast includes .def and data files you can download and modify for your own
use. For more information, see the Education link at http://www.bmc.com.
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
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 Name field:
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.
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.properties file 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


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. 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 BCC fields:
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.
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:
*#$$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.
2.
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.
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. 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

c.
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 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 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>$$#
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$$#
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


You can use the AR System Email Messages form to send outgoing email, as shown in the following figure.
AR System Email Messages form

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.
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. 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.
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
0 Normal
1 High importance
2 High importance
3 Normal (default)
4 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.
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>
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
A Password field with encryption

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.
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. Click Delete Attachment to open the AR System Email Association form.
4.
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
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.
Advanced Options tab

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.
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.
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
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:
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
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
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.
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.
Message Information tab

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


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>
<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

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

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.
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$$#).

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

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">
<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

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$$#
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.
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$/>
\[#ENCODE_HTML_END#\]
</body>
</html>
When the message is received, the email client correctly renders the user-defined markup as follows:
Leave application
Approved

16.10.4 Setting up incoming email

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

The following figure presents a sample scenario that demonstrates how the Email Engine receives incoming
email.
How the Email Engine receives incoming email

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

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

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.

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

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.
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
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 : 000000000000001
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

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

The following figure presents a sample scenario that demonstrates how to send modify instructions in an email
message.
Using incoming email to modify requests

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
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:
Sending modify instructions in plain text

Sending modify instructions in HTML
Limitations to sending a Modify instruction
Sending modify instructions in plain text

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

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.

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.
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.
Sending modify instructions in HTML

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>

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

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.

Limitations to sending a Modify instruction

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

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 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. 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.
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:

e.
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. 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:

4.
#
# 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.
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
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. 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
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.
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


To display advanced options

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.
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.
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$$#$$]
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.
16.10.5 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. 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:
# 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
16.10.6 Creating and using email templates

This section provides information and instructions about creating and using templates for outgoing and incoming
email.

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

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
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

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

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.
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 Server label
Login User name used when executing the instruction. Yes No User User Name Login, Password, and TCP
Name Login Port labels
Password Password used when executing the instruction. Yes No Login, Password, and TCP
Port labels
TCP Port TCP port used when logging in to the AR System Yes No TCP Login, Password, and TCP
server. Port labels
RPC Number RPC number used when logging in to the AR System Yes No RPC RPC Number and
server. Authentication labels
Authentication Authentication string used when logging in to the AR Yes No RPC Number and
System server. Authentication labels
Language Language used when logging in to the AR System Yes No Language label
server.
Action Denotes the instruction to be executed. Yes No Instruction Action label
Format Specifies the format of the information. Yes Yes Format label
Qualification Qualification for a query-based instruction. Yes No Query Search Qualification label
Result The name of the template to use in the reply. Yes No Result Result Template label
Template ResultTemplate
Status The name of the template to use when Status Yes No Status Status Template label
Template Information is returned. StatusTemplate
Header The template to be used as the header in the reply No Yes Header Header Template and
Template email. HeaderTemplate Footer Template labels
Footer The template to be used as the footer in the reply No Yes Footer Header Template and
Template email. FooterTemplate Footer Template labels

Label Description Incoming Outgoing Aliases Page
!Name! or !ID! The database name or ID of a AR System Form Field. Yes Yes !Name! or !ID! labels
Key The key associated with a given sender or user. Yes No Encryption Key Key label
Encryption
Request ID The Request ID of the entry on which the possible Yes No Entry ID EntryID Request ID label
action must be executed. RequestID
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.)
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.
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.
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.
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 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
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:
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$$#$$]
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.
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>
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:
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$$#
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$$]
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:
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:
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
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. 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

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
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.)
Managing HTML template attachments

This topic explains how to manage email attachments.
In this topic:
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. 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

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


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
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.
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:
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:
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.
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:
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:

d.
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
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!:

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. 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
!Impact!: Medium
!Item!: Email
!Category!: Applications
!Type!: Office
!Problem Summary!: Need to create new post office box.
!536870920!: boot.ini
!536870920!: 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:
....
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


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=iso-
8859-1">
<META content="MSHTML 6.00.2800.1126" name=GENERATOR></HEAD>
<BODY>
<TABLE cellSpacing=0 cellPadding=0 width=772 border=0>
<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>
<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.
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

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.
16.10.7 Email Engine forms

The Email Engine provides a set of administration, user, and workflow forms for configuring and processing email
from your mail server.
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

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.
Failover Mail Server The name or IP address of the mail server that acts as a failover system for the other mail server mentioned on this
Name/IP 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:

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
Mailbox Enter the name of the incoming mailbox.

Name
Mailbox Select whether mailbox is Incoming or Outgoing.

Function
Status Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Email Server Select the email protocol. Incoming mailboxes include following protocols:
Type For 32-bit JVM:
POP3
IMAP4
MBOX
MAPI
For 64-bit JVM:
POP3
IMAP4
MBOX
Polling Enter the number of minutes after which the Email Engine will check for incoming mail from the mail server for this mailbox.
Interval
(Minutes)
Email Server Enables the secure socket layer. Used only with POP3 and IMAP4.
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 Enter the name or IP address of the mail server used in your organization. Used only with POP3 and IMAP4.
Name/IP
Email Server Enter the port used for connecting to the mail server. The default port number is determined by the protocol selected and whether
Port 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 Server Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
User
Email Server Enter the user name of the administrator or user for this email account. Used only with POP3 and IMAP4.
Password
Profile Name Enter the name of the Microsoft Exchange profile to be used for incoming mailbox. Used only with MAPI.
Associated Enter the name of an outgoing mailbox used to reply to incoming emails that require a response.
Mailbox
Name
Email Action Select Parse to enable the Email Engine to detect and process instructions included in an incoming email message, or accept the
default value of None for no action.
Use Original Select Yes to enable the system to use only the parsing mechanism used in the original parsing system (BMC Remedy Mail Server
Template release 5.1 or earlier) and thus ignore special HTML fields and XML formats.
Format
Reply With 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.
Result
Reply With Select Yes to return the complete entry of a submit or modify action. Select No to use the default single-line entry.
Entry
Enable Select Yes to enable modify actions, or No to prevent modify actions from being performed.
Modify
Actions
Default Enter the name of the form upon which the Email Engine will execute instructions found within the incoming email message if no
Workflow specific form is specified in the email message.
Form
Force Select Yes if the Default Workflow Form should be used regardless of what was specified in an incoming email. This action will
Default 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 Supplied Select Yes to use AR System server login information that might be included within the incoming email message.
User
Information
Use Email Select Yes to use the email address of the sender as a form of authentication.
From
Address
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
Mailbox Name Enter the name of the outgoing mailbox.
Mailbox Function Select whether mailbox is Incoming or Outgoing.
Status Select Enabled to activate the mailbox. Select Disabled to keep the mailbox disabled.
Basic Configuration tab
Email Server Select the email protocol. Outgoing mailboxes include the following protocols:
Type For 32-bit JVM:
SMTP
MAPI
For 64-bit JVM:
SMTP
Polling Interval Enter the number of minutes after which the Email Engine will check for new outgoing mail waiting to be sent from this mailbox.
(Minutes)
Email Server Enables the secure socket layer. Used only with SMTP.
Requires SSL
Email Server Enter the name or IP address of the mail server used in your organization. Used only with SMTP.
Name/IP
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 User Enter the user name of the administrator or user for this email account. Used only with SMTP.
Email Server Enter the user name of the administrator or user for this email account. Used only with SMTP.
Password
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 Enter the name of the incoming mailbox that will be used to receive instructions or notifications.
Mailbox Name
Default Outgoing Select Yes so that all outgoing messages for which an outgoing mailbox is not specified will be sent using information in this
Mailbox 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 Outgoing Select Yes to have outgoing notification messages deleted from the AR System Email Messages form after they have been sent
Notification from this mailbox.
Messages
Default Enter the email addresses to send to if addresses have not been specified in the Messages tab for a notify filter or escalation.
Addressing
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.
Default If a user creates a message without specifying a template in the Templates tab for either Notify filter or escalation actions, then
Templates 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
Template Choose the format of template, either Text or HTML.

Format
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 Enter the name of the email template. The contents of the Template Name field are automatically populated if you attach a new file,
Name 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 Click to open the AR System Email Attachments form in New mode. Lets you select and add an attachment (for example, HTML file
Attachment or bitmap) that is always used with a specific template.
button (HTML
templates
only)
Modify Click to open the AR System Email Attachments form in Search mode so you can modify an attachment. The template will not be
Attachment available for use until the Email Engine cache is updated.
button (HTML
templates
only)
Delete Click to delete the attachment from AR System Email Attachments form.
Attachment
button (HTML
templates
only)
Refresh Table Click to refresh the table after you have added, modified, or deleted an attachment.
button (HTML
templates
only)
Add Existing Adds an existing attachment to the template.

menu (HTML
templates
only)
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
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.
AR System Email Error Logs form

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
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

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.
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 Key required for mail received from specific email accounts. If you select Yes, the Email Address field becomes enabled.
Addresses
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:

In this topic:
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); 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

Mailbox Name Name of configured mailbox.
Mailbox Type Select whether mailbox is Incoming or Outgoing.
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
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
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 Messages form — Advanced Options tab
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 With qualification variables, any access information necessary.
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 enables you to add the content of your email as a plain text, HTML, or RTF attachment, instead of
(attachment pool) typing it into the Body field in the Message tab.
Plain Text Content Language encoding used.

Attachment Encoding
HTML Content Attachment Language encoding used.

Encoding
RTF Content Attachment Language encoding used.

Encoding
Values Attachment Encoding Language encoding used.
Fields on the AR System Email Messages form — Message Information tab
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 The timestamp of when the incoming message was executed, or when the outgoing message was sent.
At
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
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 Error Messages form

In this topic:
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.
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
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.
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
Mailbox Name Name of configured mailbox.
Mailbox Type Select whether mailbox is Incoming or Outgoing.
Message tab
Fields on the AR System Email Error Messages form--Messages tab
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 Error Messages form--Attachments tab
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
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 With qualification variables, any access information necessary.
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 enables you to add the content of your email as a plain text, HTML, or RTF attachment, instead of
(attachment pool) typing it into the Body field in the Message tab.
Plain Text Content Language encoding used.

Attachment Encoding
HTML Content Attachment Language encoding used.

Encoding
RTF Content Attachment Language encoding used.

Encoding
Values Attachment Encoding Language encoding used.
Fields on the AR System Email Error Messages form--Message Information tab
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
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, 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
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 Name of attachment.
File Name Enables users to view error messages if their email was not sent correctly.
(attachment pool)
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

The Email Engine uses the AR System Email Instructions form to store instructions obtained when incoming email
is parsed.
Warning
in this form.
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
in this form.
16.11 Setting up the approval process

The following topics provide information about how to set up an approval process:
16.11.1 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
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 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
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:

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

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:
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.
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.
Application Pending 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.
The following topics provide information about approval processes:
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.
Approval process stages

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.
Approval process stages

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
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:
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

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.
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.
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 implement.
The Special Overdue Approval process in the Lunch Scheduler sample application is an example of a Rule-Based
process.
Summary of process types

Processes and their rules are configured by a process administrator. Approval server handles approval requests
with one of the following process types:

Summary of process types
Process type Routing method Determining next approver
Parent-Child Hierarchy of individuals. The process administrator Get Next Approver and Parameterized Get Next Approver rules determine
defines the relationships between individuals. the relationship of the next approver to the current owner.
Level Hierarchy of organizations. The process administrator Get Next Approver and Parameterized Get Next Approver rules determine
defines the levels and their members. the next level and approvers.
Ad Hoc Routing is based on the approvers entered by the Determined manually by users.
requester or approvers.
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:
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.
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
Self Check stage

In this topic:
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

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 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:
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
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.

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.


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:
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.
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.
Signature Accumulator rules

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

Statistical Override 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 type Signatures considered Approving requests Rejecting requests
Level Only signatures for the Preempts the approval server to proceed to the Preempts the approval server to reject the request
current level next level. and stop the processing.
Parent-Child All signatures, at all times Preempts the approval server to proceed to Preempts the approval server to reject the request
proceed to next parent. and stop the processing.
Ad Hoc All signatures, at all times Preempts the approval server to approve the Preempts the approval server to reject the request
request. and stop the processing.
Rule-Based All signatures, at all times Preempts the approval server to proceed to the Preempts the approval server to reject the request
next set of approvers. and stop the processing.
Warning
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
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:

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

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.
Approver fields checked for maximum length at startup
Field ID Field name Form name
12401 Member List

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 8000

Server
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
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

-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
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.
16.11.2 Defining an approval process

The following topics provide information about creating and modifying processes in BMC Remedy Approval
Server:
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
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.
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.
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 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 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:
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.

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

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

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.
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 renamed field, click the drop-down menu.
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. 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. 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.
16.11.3 Defining approval rules

The following topics provide information about how to create and modify rules in BMC Remedy Approval Server:

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.
Creating a rule
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 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.
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. 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.
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
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

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.

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

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
1. Follow the procedure in Using the Basic tab on the Rule Definition formto 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.
Example of an Auto Approval rule

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.
Example of an Auto Approval rule

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
about the 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
5. In the On Server field, select the server where the form is located.

5.
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.
Example of a Get Authority rule

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
Example of a Get Authority rule
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.
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
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
about the 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.
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.
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.

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

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 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
about the 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.
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

5.
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.
Server field.
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 Name 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 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.
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
about the rule.

1.
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.
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.
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.
Alternate — The form exists on another server. In this case, type the server name where the form is
located in the Server field.
10.
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
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.
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.
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:
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
about the 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.
Definition form.

5.

Alternate — The form exists on another server. Enter the remote server name in the Server field.
8. Click Save.
Example of a Validate Approver rule

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).
Example of a Validate Approver rule
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 following information:
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$
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
about the rule.
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.
Definition form.
Server field.
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).
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:
To define a Statistical Override rule
about the 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.
Server field.
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.
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
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.
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
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. 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.
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.
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
about the 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 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
about the 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
Working with existing rules

This topic contains information about viewing, modifying, and deleting existing approval rules.
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.
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.

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.
16.11.4 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

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

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.

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:
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 Approval Server
application commands.
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.
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 Approval Server
application commands.
Chaining approval processes

In this topic:
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 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.

2.
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.
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
16.11.5 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

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
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.
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
Notification: Still in State — Hold
Notification: Still in State — More Information

Urgent priority notifications

Use Schedules
Business Calendar
Holiday Calendar
Automatic Action
After Interval ___________ Unit ___________

Low priority notifications

Use Schedules
Business Calendar
Holiday Calendar
Automatic Action
After 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
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
__________ __________
__________ __________
__________ __________

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

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
__________ __________
__________ __________
__________ __________


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
__________ __________
__________ __________
__________ __________

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
__________ __________
__________ __________
__________ __________


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
__________ __________
__________ __________
__________ __________


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
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
__________ __________
__________ __________
__________ __________
16.11.6 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
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
This form stores the information entered through the AP:AdhocDialog form. See AP-AdhocDialog form.
AP:AdhocDetails form
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 The current sequence of the corresponding process.

Sequence
Application The request ID of the application through which the corresponding request was created.
Request ID
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.
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.

Field Description
Process, rule, notification, role, form, Click a tab to display a list of items of that type. This also selects which category of items is used
administrator, alternate 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.
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 Select Process to rename a process, or Form to rename a form.
renamed
Select the form to be renamed / Select the process name from the menu. When BMC Remedy AR System supplies the GUID, select the
Select GUID of the process to be supplied GUID.
renamed
Enter new process name /Enter Type the replacement name for the process or form. The name of a process can be as long as 80 bytes. This
new form name equates to 80 characters in English and most European languages, but only 40 characters in double-byte
languages.
Scope of update Select an option from the menu to determine which of the associated detail records are renamed.

Field Description
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.
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 Select this check box to enable approval server logging.

Debug
Mode
Log File Type the directory path and file name for the log file.
Name
Other Settings
Definition Type a number of seconds to define how often the approval server checks the definitions for changes. A larger number increases BMC
Check Remedy AR System performance by checking less often. A smaller number of seconds is useful while creating and testing a process. A
Interval 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 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
Server private queue.
RPC
Socket
Plugin Type the RPC socket number of a private queue used for loopback calls. Leave this field empty if your server does not use a dedicated
Loopback queue for loopback calls.
RPC
Socket
Due-Soon Type the duration after which approval requests that are due for action should be highlighted on Approval Central. Use the adjacent
Interval 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 upon. Select the
History unit of measurement (Hours or Days) using the adjacent drop-down list. This affects My Recent Approvals on Approval Central. See
Interval 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:
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:Administration form.
For information about the notification tab, see Setting notifications for approval events.
Escalations tab
AP:Admin-ServerSettings form — Escalations tab
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 Enabled means the approval server enables escalations for the approver list when this event type occurs during an approval
(repeat) process.
Enabled Including Alternate (default setting) means the approval server enables escalations to the approver list as well all
Still Pending
active alternates when this event type occurs during an approval process.
Still Pending
These settings enable escalations for each event type. To use escalations, you must define the specific escalations for each process
(repeat)
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.
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 the mode in which
Mode 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 Displays the lists of available views for the selected form. Select a view for the selected form.
Label
Note
If you do not select a view, the form opens in the default view.

Lookup Displays a list of fields present on the selected custom form (See the Form Name field description).
Field
Note
This option appears if the Display Mode field contains one of the following items:
Modify
Display
Modify Directly
Display Directly
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 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
Mappings 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
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 This field contains an audit trail of date, time, and approver for actions taken on this request. This information is part of the
Trail permanent record for this request.
Global Approve 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.
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 The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the multi-tenancy
Permissions 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 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 The BMC Remedy AR System populates this field with the current status for the signature record.
Status
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 Displays the priority of this request as defined in the approval process.
Priority
Comments Enter any comments you want to store with the approval request.
Next When the process allows ad hoc approvers to be added, type the AR System user names of the next approvers.
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
Approvers field.

Field Description
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.
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 This field contains an audit trail of date, time, and approver for actions taken on this request. This information is part of the permanent
Audit Trail record for this request.
Assignee The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the multi-tenancy
Group feature.
Permission
For The BMC Remedy AR System populates this field with the name of the approval request form for the request.
Application
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 This field records the AR System user name of the approver who has responded for this signature line. The name appears only after an
Signature authorized person modifies the Approval Status field.
Alternate This field records the AR System user name of the alternate approver who modifies the Approval Status field, if any.
Signature
More This field contains More Information requests sent by the approver for this request and signature line, and the responses to those
Information requests. The field is not populated until the requestee responds to the More Information request.
Show Opens the approval request form for this request.

Details
More Opens AP:Dtl-Sig-MoreInfoDialog and searches for More Information requests associated with this approval request.
information
Signing Tracks the method (Approval Console or Email Engine) used for approving or rejecting a request.
Method
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

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 Provide labels for the fields 14508, 14509, 14510, and 14511, and click Save. For information about where these labels appear, see
14508 AP-Form form.
Label for The default labels for these fields are GL Account, Cost Center, Total Cost, and Phase, respectively.
14509
Label for
14510
Label for
14511
Labels for ToolTip:
Label for Provide labels for the fields 14711, 14712, 14713, 14714, 14715, 14716, 14717, 14718, 14719, and 14720, and click Save. For information
14711 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

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 The BMC Remedy AR System populates this field with the Assignee Group for the request. This field supports the
Permission 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.

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 Time
Real Diary
Date/Time Attachment
Currency 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 Map to an application ID, which could be the request ID or any other ID field in the application. For example, BMC Change
Request ID 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 The value from the mapped field is displayed in the Summary column on Approval Central.
{14506}
Field 2 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
{14507} approval console.

Field 3 The values from the mapped fields are displayed in the top panel on AP:Show-Detail. For example, for a request of the Lunch
{14508} Field Scheduler sample application, these values appear against the following labels:
4 {14509}
Field 5 P-C GL Account
{14510} Field P-C Cost Center
6 {14511} 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 this field is not
displayed anywhere on Approval Central.
Field 8 The value from the mapped field is displayed in the Notes field for a request on Approval Central.
{14513}
Field 9 The value from the mapped field is displayed in the Attachment table on the AP:Show-Detail form.
{14514}
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.
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 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 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
{14711} Approval Central.
Field 2
{14712} 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,
Field 3 the tool tip does not appear.
{14713}
Field 4
{14714}
Field 5
{14715}
Field 6
{14716}
Field 7
{14717}
Field 8
{14718}
Field 9
{14719}
Field 10
{14720}
Define Click to define labels for the fields 14711, 14712, 14713, 14714, 14715, 14716, 14717, 14718, 14719 and 14720, for various applications,
Labels processes, and locales. The AP:DynamicLabels form appears. See AP-DynamicLabels form.
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.

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:Administration form.
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.
Permission multi-tenancy feature.

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.
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 Select "Yes" to use the email based approval template. The appropriate template name will be automatically displayed in the
Approval template 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.
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 template directly,
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 template directly,
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

Field Description
Application The application request ID.

Request ID
Application The application form name.

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 The semicolon-separated list of processes, each prefixed with some related information and separated by a colon ( : ). Some
List 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/Ticket The request ID that you want previewed.

Number
Single/Multi Select the appropriate value to indicate whether you want to generate a single process or multi-process preview.
Process
Retrieval Type Users have an option of specifying a value as a qualification for the query being made.
Full — Returns list of all completed signatures (from the AP:Signature form), and all previews from the preview form.

Field Description
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 Select the process related to the request.

Process
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
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 Use the drop-down list to determine the method for notifications to this user.
Method
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.

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 Use the drop-down list to select a process name if you selected Specific Process in the Covering field.
Name
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

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 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
Owner menu are populated from the approval request form. See Request Owner field.
Field
First 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
Approver menu are populated from the approval request form. This field is required for Ad Hoc process type, optional if you allow ad hoc
Field overrides, and otherwise unused.
Generate Select generate preview setting from the available options:

Preview
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:
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 Specify whether approvers should or should not be able to reassign a request of this process type to another approver.
Reassign?
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
Form 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.
Exclude This menu lists all the fields on the application form. Select a field that contains user names. The users from the selected field are
User Field 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 Select the manner with which the approval server determines whether the approval process for a request is complete:
Success
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 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
Approvers 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 This field applies to Parent-Child, Level, and Rule-Based process types. Specify using the available option whether users can add
Hoc Next approvers to the approver list for a request:
Approver?
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 This field specifies how the approval server determines the next approver, when the requester is not the person who submitted the
Assignment 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 This field tells the approval server whether to verify the value in your next approver field with a Validate Approver rule when creating a
Approvers request. Select from the available options:
Yes — Validate the approvers when saving a request.

No — (Default) Skip validating approvers.
Require This field determines whether the approver must enter a password to save changes to an approval request. Select from the Available
password 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.
Assignee The BMC Remedy AR System populates this field with the Assignee Group for the request; the Public group is selected by default. The
Group approval server uses this field to support multi-tenancy for use by application service providers. If you use this field for multi-tenancy
Permissions 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 This field is enabled only if you select:

Settings
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 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
Form 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 This field determines the course of action in case the approval server fails to retrieve the first approver for a request.
first
approver Yes — (Default) Set the state of the request to Error and add the error details to the audit trail.
failed, 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.
error?
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?
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 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 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
Due for the process is 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 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
Period from all process intervals, except Signature Due, when computing the action date.
Enable Select Yes to use the Preview feature in calculating the Signature Due Date. The Preview feature is used to fetch information about the
Preview 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 Select the menu from which to derive user names for the corresponding operations. The selected menu determines the list of users
Information that appears when a user creates a More Information request (by adding a question or comment), or chooses to reassign a request, or
Reassign 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
Ad-hoc choosing names from a user list; they can continue with the operation by entering login names manually.
Rejection Justification

Require Select Yes to make it mandatory for an approver to provide a justification when rejecting a request. In addition to storing the
Justification justification in various approval server fields, it is pushed to the application form's field specified in the Justification Field menu. Select
on No to indicate that rejection justification is optional; an approver is not prompted to justify rejecting a request. However, if provided,
Rejection the justification is processed further.
Justification Select the field in which to store the rejection justification. This menu lists Character fields from the application form.
Field
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
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 Use the drop-down list to select a holiday schedule created on one of the business time holiday forms.
calendar
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 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
State 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 Type a numeric value for the amount of time to pass before this notification first occurs.
Interval
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 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
Interval unit is determined in the next field.
Notification: Still in State

Use these fields to send a notification to an approver for signatures in an active state.
On Set the separate escalation and repeat intervals to occur when a form is saved with the status of Pending, Error, Hold, or More
State Information.
First Type a numeric value for the amount of time to pass before this notification first occurs. For example, type a 2 for two hours or two days.
Interval The unit is determined in the next field.
Note: This is one of the Escalation intervals, which is used to compute the action date for the corresponding process.
Repeat 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
Interval unit is determined in the next field.
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 Use the drop-down list to select a workday schedule created on one of the business time workday forms.
calendar
Holiday Use the drop-down list to select a holiday schedule created on one of the business time holiday forms.
calendar
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 hours or two days.
The unit is determined in the next field.
Repeat 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
interval unit is determined in the next field.
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

Record type Source field
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
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 Select one of the options:

Approvers
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.
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 The BMC Remedy AR System automatically populates this field with the GUID of the process.
Instance ID
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 Use the drop-down list to select the behavior when multiple results are found.
Results
Value from First — The approval server uses the value from the first record retrieved.
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.

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 Use the drop-down list to select the behavior when multiple Get Next Approver rules exist.
Approver
Rule Is 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.
Group feature. See Error 333 and Assignee Group Permission.
Permissions
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
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.
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
Fields on the AP:Rule Definition form — Set Fields tab

Field Description
Set Fields Select an item from the drop-down list to specify how the rule should populate this field type. The options are: Value, Query, SQL,
Type 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 Type the letters, numbers, or symbols to use when separating multiple entries set in the same field. This field is disabled with some
string options available in the Set Field Type field.
Qualification
Query The Fields from Set Fields Form, Fields from Application Form, and other SQL keywords and operator buttons are available for use
builder only when you select a Set Fields type other than Value. For example, choosing SQL causes Select, From, Where, and the comma
buttons separator (, ) buttons to appear so that you can construct SQL statements easily.
SQL Type a qualification or use the other fields to select functions or keywords. You can dynamically define the search criteria by using
Command / the EXTERNAL keyword. When using the EXTERNAL keyword, make sure you see fields using single quotes instead of dollar signs, for
Qualification example:
then the value from the current transaction is returned:
"John" = "John"
Fields data
Field name 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 This field is valid only if multiple entries exist in the Next Approver field. Select one of the options:
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.
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.
Permissions multi-tenancy feature.
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 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:
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.
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 Click to view the requests that await your approval. Such requests are in the Pending state. The following links are displayed under the
Approvals Pending Approval link:
Needs Attention
Past Due
Due Soon
For more information, see Pending Approvals table.
Needs 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 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 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
Approval of which appear on the right pane in the My Approvals History table. Requests displayed in this table have the Approved, Rejected, or
History 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 Click to view the requests that you approved earlier, but are rejected by an approver further in the approval sequence. This is a
by Others 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.
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

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 Click to approve the selected request.

icon
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.
Reassign Click to reassign the selected request to another person. If Can Reassign is set to Yes for the corresponding process, the AP:Reassign
icon 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 Click to open the AP:Show-Detail form, which displays the details of the highlighted approval request and enables you to take further
Details icon 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 Click to display all the questions and responses, if any, for the selected request. If there is no question for the selected request, the
Questions following pop-up message is displayed:
and
Responses No Questions Present
icon
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 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
For Action Activity Log table. If you click any other action button, this field is ignored. For information about how your input is processed, see
Rejection justification for approval requests.
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 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 Select an approval status from the list to search for requests with the selected status. The default is Pending.
Status
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 Select the Action Date. See Signature Escalations tabs and step 5 of the To enter signature escalations section.
Date
Priority Select the priority. This is the priority of the approval request and not that of the application request.
Modified Select the date on which the requests you want to search for were last modified.
Date
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.
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 Click to approve the selected request.

icon
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.
Reassign Click to reassign the selected request to another person. If Can Reassign is set to Yes for the corresponding process, the AP:Reassign
icon 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 Click to open the AP:Show-Detail form, which displays the details of the highlighted approval request and enables you to take further
Details icon action. For more information, see Working with request details.
View Click to display all the questions and responses, if any, for the selected request. If there are no questions for the selected request, the
Questions following pop-up message is displayed:
and
Responses No Questions Present
icon
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
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.
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 Click to approve the selected requests. If other approvers are required, BMC Remedy AR System routes the requests to the
Selected respective next approvers. If no further approvers are required, the request statuses change to Approved, and the approval
process is done.
Reject Click to reject the selected requests. If rejection justification is mandatory, but the Justification For Action field is empty, a dialog
Selected box prompts you to enter a reason for rejecting the request. The same comment is applied to all the selected requests. See
Hold Click to put the selected requests on hold. The request statuses change to Hold until any further action is performed on them.
Selected
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
Request 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
ID 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 Displays the activity log (Questions, Comments, and other information) associated with the Request ID. Click View Activity Summary to
Log 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 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
To 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 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 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.
Summary
Response This field is labeled as Response when you view a question about the approval request; the corresponding response appears here. It is
/ Notes 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.

Approvers
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 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
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
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.
Covering Select a value to identify which processes are included in this alternate's authority.
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 BMC Remedy AR System populates this field with the name of the person who last modified this alternate.
By
Last Modified BMC Remedy AR System populates this field with the date of the last modification to this alternate.
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 This field displays any More Information records attached to the current approval process.
Information records
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
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.

Field Description
More Info Status of the More Information request.

Status
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.
Group 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.
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
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
Field Description
Approver Displays the approval process preview for the current request as a flowchart or a table.
tab
Activity Displays the list of questions and comments associated with the current request in a table. You can also add or delete questions and
Log tab 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 Click to see a preview of how the current request might traverse through the current approval process. This preview is generated
Type: after the process begins (when the detail and signature records for the current request have been created).
Current
Process Only
Preview Click to see a flowchart or tabular view of the path the current request might traverse when it pertains to multiple processes. This
Type: view appears only when the Generate-Multi-Process-Preview application command is executed, whose input values determine the
Multiple what appears in the view. See Using the multi-process preview.
Processes
View As: Click to see a flowchart view of the current approval request. See Sequence diagram.
Sequence
Diagram
View As: Click to see a tabular view of the current approval request. See Table.
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].
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
Fields on the AP:Show-Detail form — Activity Log tab

Field Description
Refresh Click to refresh the contents of this tab.
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 This section enables you to add, modify, and delete comments, questions, notes, and attachments to the current request.
Details
Type This drop-down list enables you to specify whether you are creating a comment or a question.
Question 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
To 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 / 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 Summary when you choose to add a comment. Enter the brief comment here.
Response / This field is labeled as Response when you view a question about the approval request; the corresponding response appears here. It is
Notes 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 Displays the date and time of submission.

Date
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
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.

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.
16.11.7 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 <joinfix>

Approval Change Schema <chgschema>
Approval Upgrade <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]
[-m Mode]
1. Update Join Criteria
2. Add new fields in Three-way Join Form
Arguments:
b. If you type chgschema, and press enter, the interface displays the parameters for the utility and
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 utility and
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.

16.12 Setting up DSO to synchronize data across multiple AR

System servers
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.

16.12.1 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
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

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
0 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.
1 Identifies the next pending item to process from the list obtained in stage 0.
2 Gets the definition of the source form associated with the pending item.
3 Gets detailed information about the request to transfer, which is identified by the request ID in the Source ID field of the pending item.
4 Gets the definition of the distributed mapping associated with the pending item.
5 Verifies that it can implement the mapping.
6 Gets the definition of the target form associated with the pending item.

Stage DSO server action
7 Transfers the request from the source form to the target form.
8 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 Copy of request in target form Description

transfer
Holds Is in Can be
ownership? ownership modified?
chain?
Data Only No No No Typically used for archiving. Because data-only copies cannot hold ownership, they cannot
start ownership chains.
Data + Yes Yes Yes Considered the master copy. Modifications made to this copy can be automatically made to
Ownership all other copies of the request in the ownership chain (see Distributed updates).
Independent Yes No Yes Cannot receive updates from the master copy because independent copies are outside the
Copy ownership chain. Independent copies can start new ownership chains.

Copy + Yes No Yes Transfers an independent copy of a request to the target server and then deletes the original
Delete 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

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

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.

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.
16.12.2 Distributed operations components

This section contains information about configuring distributed operations using these elements:
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.
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.
Distributed logical mapping

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.
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 Displays one of these values after a transfer is attempted:

Status
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.
Update Displays one of these values after an update or a return is attempted:

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 Specifies the ID of the request in the source (From) form.

Request
ID
From Specifies the form from which a request was transferred. Also called the source form.
Form
From Specifies the server from which a request was transferred. Also called the source server.
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 Description
name
To Tells DSO which mapping to use when transferring the request. If the mapping specified in this field does not exist or is disabled, the
Mapping distributed operation fails.
From Specifies the mapping that was used during a transfer to create this request. Only DSO can set the value of this field.
Mapping
To Specifies the ID of the request to which the data was transferred. Only DSO can set the value of this field.
Request
ID
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.
To 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
Server on their values. If no mapping to the specified server exists, the distributed operation fails. Also called the target server.
Mapping Contains a history-tracking record created at the time of transfer. The record includes the date and time of transfer, the source request
History 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 Specifies the form in which the master copy of the request resides. Only DSO can set the value of this field.
Form
Current Specifies the server on which the form with the master copy of the request resides. Only DSO can set the value of this field.
Server


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.
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 Specifies the action that occurs if you transfer a request and the To form already contains a request with the same request ID.
Request ID See Duplicate Request ID Action.
Action
Max Time to Specifies the maximum times a distributed operation is retried before the system cancels the operation. See Retries.
Retry
Enforce Pattern Specifies whether to enforce patterns defined in fields on the target form during distributed operations. See Enforce Pattern
Matching Matching.
Require Required Specifies whether to require values in fields defined as required fields on the target form. Use this field to enable transfer of an
Fields 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.
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.
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.
16.12.3 Implementing DSO

This section contains information about working with distributed fields, mappings, and pools. It also explains how
to administer data transfers between forms.
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

Use distributed transfers to transfer a request from one form to another.
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.
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.
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.
For an overview of distributed fields, see Distributed fields.
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.
3. In the Add Distributed Fields dialog box, do one of the following:

To remove only the advanced fields, select Full.
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.
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
1 To From The mapping specified in this field is selected.

Mapping (source)
form
2 To From A list of mappings associated with the To server and the To form is generated. Default mappings are listed
Server (source) first in the order they were created. The first mapping in the list is selected.
and To form
Form
3 Mapping Filter or The mapping specified in this field is selected.

escalation
4 To Filter or A list of mappings associated with the To server and the To form is generated. Default mappings are listed
Server escalation first in the order they were created. The first mapping in the list is selected.
and To
Form
5 From Distributed A list of mappings is generated from all distributed mappings on the server whose From Form value matches
Form mapping 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


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 When selected, specifies that the mapping is the default mapping. When the DSO action in a filter or escalation does not specify
Mapping 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 Specifies the name of the server from which the distributed operation is initiated (the source server). You can enter or select any
Name 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
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 Specifies that the mapping can use any server in the group as the From server. See Configuring DSO for a server group. Available
Any only when the server is in a server group.
Server in

Server Note
Group
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 Specifies the name of the form from which the distributed operation is initiated (the source form). Enter the form name, or click
Name the ellipsis button to use the Form Selector.
To
Server Specifies the name of the server to which the transfer is mapped and from which update and return operations occur (the target
Name 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 Specifies the name of the form to which the distributed operation is mapped (the target form). Enter the form name, or click the
Name 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 Specifies the update frequency for the original request if a copy transferred with ownership is updated:
Update 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 Specifies the type of transfer to perform:

Mode 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.
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 Specifies the action that occurs if you transfer a request and the target form already contains a request with the same
Request ID request ID:
Action 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 Specifies whether to enforce patterns defined in fields on the target form:
Pattern Yes — The target system pattern checks data sent to the target form. Data transferred to fields on the target form
Matching 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 Specifies whether to require values in fields defined as required fields on the target form:
Required Yes — The target system does not allow NULL entries in required fields on the target form. Optional fields on the
Fields 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 Specifies whether to use request IDs or another qualification to find the correct request in the target form:
Request ID 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 When the Match by Request ID check box is not selected, specifies the qualification to use to find the correct entry in the
Qualification 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:
Setting up automatic mapping
Using the excluded fields option

5.
Creating custom mapping

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.
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.
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 of the
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. 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 of the
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
Distributed logical mapping
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

Follow this procedure to modify a distributed mapping.
Warning
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

on the server.
5. Double-click the distributed mapping that you want to copy.
The distributed mapping appears in the Distributed Mapping editor.
7. In the Save Distributed Mapping As dialog box, enter a name for the new distributed mapping.
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

on the server.
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:
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
State Specifies whether the pool is active (enabled) or inactive (disabled). Select the appropriate value:
Enabled (default)
Disabled
Default Specifies whether the pool is the default pool. The default pool is used when no pool is specified for a distributed operation. See
Pool Default distributed pool.
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 pending queue.
(mins) Minimum interval is 5 minutes (default).
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.
4. Select File > Save.

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.
Managing distributed pools

In this topic:
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 mappings defined on
the server.
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.
9. Restart the DSO server.
Deleting distributed pools

Follow this procedure to delete a distributed pool. You cannot delete enabled distributed pools.
Warning
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.
6. Select Edit > Delete.
The distributed pool is deleted from the server, and its name is removed from the Distributed Pools tab.
Setting polling intervals for distributed pools

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:

For an overview of distributed logical mappings, see Distributed logical mapping.
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 Remedy Developer Studio.
3. Click Save.
Managing distributed logical mappings

In this topic:
Modifying distributed logical mappings
Distributed Logical Mappings > Search.
2. From the results list, select the item to modify.
3. Modify the mapping as necessary.
4. Click Save.
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
1.
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

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 Distributed operation type (transfer, update, return, or delete).

Type
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.
-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:
Setting a polling interval for the DSO server

Setting polling intervals for distributed pools
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:
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.
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. 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.
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)
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:
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
16.12.4 Distributed operations scenarios

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 Request ID prefix
San Francisco 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
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
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:

9.
Distributed Mapping editor — Basic panel for chicago server
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.
5. In the Execution Options panel, set the options shown in the following figure:
Filter editor — Execution Options panel
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.

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

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.
16.12.5 Chained and broadcast distributed transfers

Both chained and broadcast distributed transfers involve multiple servers. For example:

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.
Setting up 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

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

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:

e.
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 ).
Avoiding infinite loops

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

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

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

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:
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.
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.
Setting up broadcast distributed transfers

In this topic:
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 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:

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
Options When to Update field Immediately

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
Options 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)

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.
16.12.6 Distributed Server Administration program

In this topic:

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
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
Runs the program in Debug mode, printing debug information to the terminal. This is a flag; do not assign a value to it.
-d
Specifies the ID of the request to modify.

-e
Specifies the directory in which the AR System server is installed.

-i
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
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
-m 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
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
16.12.7 Managing request IDs in distributed environments

In this topic:
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

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.
16.12.8 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: T
4.
4. Save the AR System server configuration file.

5. Restart the BMC Remedy Action Request System Server serverName service.
16.13 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.
16.13.1 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.
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.

16.13.2 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.
16.13.3 Types of events you can record

The following table lists the types of server events you can record.
Events you can record
Object Example For more information
Changes to server objects (such as forms, filters, active The AR System server records the API calls that cause Viewing server object
links, escalations, fields, VUIs, char menus, and containers) server object changes changes
Changes to users, groups, applications, and roles Viewing user, group,

User added, modified, or deleted using the User or application, and role
Group form changes
User or group changes using the arcache 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 Viewing server setting

changes

Object Example For more information
Alert registration Alert users are registered or deregistered Viewing alert registration
activity
Archive activity Viewing archive activity
Server group activity A server in a server group fails and another server takes Viewing server group
over actions
16.13.4 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
The #define statements for the event types in ar.h are:

#define AR_SVR_EVENT_CHG_SCHEMA 1
#define AR_SVR_EVENT_CHG_FIELD 2
#define AR_SVR_EVENT_CHG_CHARMENU 3

#define AR_SVR_EVENT_CHG_FILTER 4
#define AR_SVR_EVENT_CHG_IMPORT 5
#define AR_SVR_EVENT_CHG_ACTLINK 6
#define AR_SVR_EVENT_CHG_ESCAL 7
#define AR_SVR_EVENT_CHG_VUI 8
#define AR_SVR_EVENT_CHG_CONTAINER 9
#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
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

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.
Server object changes
Type Cause Cause Description Event Details 1 Event Details 2 Event Details 3
1 0 or 8 ARSetSchema form name old form name
1 1 or 9 ARCreateSchema form name
1 10 ARDeleteSchema form name
2 0 or 13 ARSetField field ID; field name form name old form name
2 1 or 14 ARCreateField field ID; field name form name
2 43 ARDeleteField field ID; field name form name
2 56 ARDeleteMultipleFields field ID; field ID; ...; field ID form name
2 151 ARCreateMultipleFields field ID; field ID; ...; field ID form name
2 152 ARSetMultiple Fields field ID;field ID;...;field ID form name
3 0 or 17 ARSetCharMenu menu name old menu name
3 1 or 18 ARCreateCharMenu menu name
3 19 ARDeleteCharMenu menu name
4 0 or 22 ARSetFilter filter name old filter name
4 1 or 23 ARCreateFilter filter name
4 24 ARDeleteFilter filter name
5 35 ARImport
6 0 or 39 ARSetActiveLink active link name old active link name
6 1 or 40 ARCreateActiveLink active link name
6 41 ARDeleteActiveLink active link name
7 0 or 49 ARSetEscalation escalation name old escalation name

7 1 or 50 ARCreateEscalation escalation name
7 51 ARDeleteEscalation escalation name
8 0 or 63 ARSetVUI vui ID;vui name form name old vui name
8 1 or 64 ARCreateVUI vui ID;vui name form name
8 65 ARDeleteVUI vui ID;vui name form name
9 0 or 75 ARSetContainer container name old container name
9 1 or 76 ARCreateContainer container name
9 77 ARDeleteContainer 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:
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.

In the Event Details fields, semicolons separate multiple items. No spaces follow the semicolon.
User and group, application, and role changes
Type Cause Cause Description Event Details 1
10 0 User added entry ID;user login name
10 1 User modified entry ID;user login name
10 2 User deleted entry ID;user login name
11 0 Group added entry ID;group name
11 1 Group modified entry ID;group name
11 2 Group deleted entry ID;group name
11 3 Computed Group added entry ID;group name
11 4 Computed Group modified entry ID;group name
11 5 Computed Group deleted entry ID;group name
11 6 Application added application name
11 7 Application modified application name
11 8 Application deleted application name
11 9 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.
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
12 5 AR_SERVER_INFO_ALLOW_GUESTS datatype;value
12 6 AR_SERVER_INFO_USE_ETC_PASSWD datatype;value
12 7 AR_SERVER_INFO_XREF_PASSWORDS datatype;value
12 8 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
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
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
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
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
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
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.

Datatype Description #define in ar.h
0 NULL AR_DATA_TYPE_NULL
2 Integer AR_DATA_TYPE_INTEGER
4 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 Event Details 1

Description
13 102 User logs in to Operation type tag (R);byte length of user name;user name;registration time;IP address of client;client port;actual
alert client client IP address;server IP address that client expected;registration flag;client version;client codeset
13 103 User logs out Operation type tag (U);byte length of user name;user name;IP address of client;client port;client version
from alert
client
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
Submitter: User who caused the archive change event

Archive activity
Type Cause Cause Description Event Event Details 2 Event Details 3

Details 1
14 1 Copy to archive only Source <Actual number of entries copied to archive> of <Total number of Destination
form name matches> form name
14 2 Delete from source only Source <Actual number of entries deleted from source> of <Total number of Destination
form name matches> form name
14 3 Copy to archive and delete Source <Actual number of entries copied to archive and deleted from Destination
from source form name source> of <Total number of matches> 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
15 1 Server in group fails over an Server that an operation is Name of the Server that an operation is failing over
operation failing over to. operation involved. from.
15 2 Server in group is relinquishing an Server relinquishing an Name of the Server expected to take over a
operation operation. operation involved. relinquished operation.
15 3 Server in group takes over an Server taking over an Name of the Null
unowned operation. unowned operation. operation involved.
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
17 1 A group command is initiated Schema for which the groups are being initiated Null Null
17 2 A group command is completed Schema for which the groups are being completed Null Null
16.13.5 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.
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.
16.14 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.

16.14.1 Auditing data

The following topics provide information about auditing:
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:
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
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.

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

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
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.
Log Key 1 Fields that help in searching of log entries. See Log keys for more information.
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

The following procedure describes how to enable auditing for a form.
Note
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 System
Administration: Server Information form.
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.
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.
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.
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).
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 the following figure.
How a join audit form is created
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

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

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.
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:
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.
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

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.
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.
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
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.
For more information about BMC Remedy Approval Server signatures, forms, and handling approval requests, see
Configuring the BMC Remedy Approval Server.
16.14.2 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
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.
Copy to Archive — The entries you choose from the main form are copied to the archive form; the data
remains on the main form. (For vendor forms, this is the only archive type that is available.)
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

You can use the data archiving feature to back up and delete data from forms.

Note
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.
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
Copy to Archive
Delete from Source
None
5. Select the Enable option to enable archiving of the form.
6. If you selected Copy to Archive and Delete from Source or Copy to Archive, 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.
7. (optional ) If you selected Copy to Archive and Delete from Source or Copy to Archive, select the following
options to exclude them from the archive form:

7.
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.
8. In the Times Selected area, set the time when you want the archiving process to occur.
You cannot set the interval time between each archiving process for less than 1 hour.
9. To specify a limited amount of data on the form to archive, enter a qualification.
For example, to archive statistics older than 30 days in the Application Statistics form, enter:
'Time Stamp' < ($TIMESTAMP$ - 2592000)
10. 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, join form, or vendor 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.
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.
3. Double-click Forms.
4. In the Forms list, right-click the form name, and choose Delete.
5. In the Confirm Deletion dialog box, click OK.
6.
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.
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

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

All archive forms have the following characteristics.
General
The form is a regular form. The detail view in the BMC Remedy Developer Studio forms list shows its Type
as Archive.
Any changes to the definitions in the main form (such as adding or deleting a field) are also applied to the
archive form. But if there is any data in the form, no fields are deleted from the archive form. You can
change the form and view properties of the archive form explicitly. Trim and button fields are not created
automatically, but you can manually add trim and button fields to an archive form.
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," then 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.
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 uniqueness constraints (indexes) on the main form are removed from the archive form. You can add
indexes to the archive form.
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.

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
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).
(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.
16.14.3 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.
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.

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.
16.14.4 Importing data into BMC Remedy AR System forms

This section contains information about importing data into BMC Remedy AR System forms:
Starting Data Import and logging on to AR System servers

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. Choose Start > Programs > BMC Software > Data Import.
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

a.
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. Choose 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. 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.
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

2. Set the preferences, which are defined in the following table.
Data Import preferences
Group Field Function

name
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 Uses transactions to import data (if the server supports transactions). For example, if you enter a value of 100, the server
Records performs only one commit to the database every 100 records, which significantly improves performance.
Per
Transaction 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 Defines how to handle duplicate request IDs. The options are
Duplicate
Request Generate New ID for All Records — Assigns new request IDs to all requests in the data file, whether or not any IDs
IDs By 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 Defines what happens when multiple requests match. The options are
Requests
Match 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 Make Specifies that noncore required fields are optional during the import. By default, the check box is cleared, and all required
Handling Non-Core fields are treated as required. If a required field has a NULL value, an error is generated. The error is processed according
Required to what you enter in the Bad Records field under the "Error Handling" section.
Fields
Optional *
Disable Specifies that records are imported, even if the data in a field does not match the specified pattern. By default, the check
Pattern box is cleared, and the server rejects records if data in the field does not match the specified pattern. The error is
Matching * processed according to what you enter in the Bad Records field under the "Error Handling" section.
Suppress Suppresses (turns off) any filters that execute on Merge.

Filters
Suppress Suppresses the default values of the fields. If the field has a default value and the data you are importing for the field is
Field empty, the import process does not use the default value for that field.
Default
Values
Remove Specifies that all leading white space is removed from each field imported. By default, the check box is cleared, and
Leading values are imported exactly as they appear in the data file.
Spaces and
Tabs *
Remove Specifies that all trailing white space is removed from each field imported. By default, the check box is cleared, and values
Trailing are imported exactly as they appear in the data file.
Spaces and
Tabs *

Truncate Specifies that fields that are too long are truncated. By default, the check box is cleared, and fields whose contents are
Strings too long generate an error. The error is processed according to what you enter in the Bad Records field under the "Error
Exceeding Handling" section.
Field Limit
*
Import Specifies how BMC Remedy AR System imports records that contain fewer fields than described by the field titles in the
Records data file. Problem records are imported with NULL values in the missing fields. By default, the check box is cleared, and
with Too the problem records are not imported and an error is generated. The error is processed according to what you enter in
Few Fields the Bad Records field under the "Error Handling" section.
Import Specifies how BMC Remedy AR System imports records that contain more fields than described by the field titles in the
Records data file. By default, this option is selected. The problem records are imported, and the extra fields are ignored. If you
with Too clear the check box, the problem records are not imported, and an error is generated. The error is processed according
Many Fields to what you enter in the Bad Records field under the "Error Handling" section.
Date Short Date Defines the short-date format. The options are
Format Format
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
Defines the separator character between the month, day, and year. Slash is the default. You can use any character
Separator 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 Hour Mode Defines the hour mode. The options are
Format
12 Hour — Tracks in the 12-hour clock (default).
24 Hour — Tracks in universal time.
Separator Defines the time format separator between the hours, minutes, and seconds. A colon (:) is the default. You can use any
(Time character that is not part of the field separator string for the data file.
Format)
AM/PM Specifies where the symbol is positioned if you select 12 Hour for the Hour Mode. The options are
Position
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.
Real Digit Group Defines the separator for groups of real numbers in .arm and .armx files.
Number Separator
Handling
Decimal Defines the decimal separator for real numbers in .arm and .armx files.
Separator

Error Bad Defines what happens when the import process encounters a bad record. The options are
Handling Records
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

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.
In this topic:
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 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.

Creating a mapping file
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 (CSV and ASCII format only) Determines whether BMC Remedy Import converts the field titles into data.
Field Titles 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 (ASCII format only) The field separator used in the .asc file.
Separator
Source Form from which you exported data.

Form
Name
Target Server that contains the form to which to import data.

Server
Target Form to which to import data.

Form
Name
Custom (Optional) The custom_options.xml file, which used to specify date and time formats, the separators to be used, and other
Options information. This field appears only if the source data file selected is a CSV or ASCII file.
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 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.

Home e. BMC Software Confidential
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 preferences fields on Options tab
Group Field Function
name
General Use Entry Enables the Number of Records Per Transaction field.
Transactions
Duplicates Match Defines how duplicate requests should be matched. The options are
Duplicate Request ID
Request By Custom Fields — If you select this option, click Add to specify which fields determine whether
requests match. For example, if you select the Phone Number field, if two requests have the
same number in the Phone Number field, the requests match.
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.
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.

16.14.5 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.
16.14.6 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

In this topic:
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 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.
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
--version Writes the version to standard output and exits without executing other options.
-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.

-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.
-inplace Import in place. Overwrite each existing object without deleting the object first. DefinitionImport only.
-lock 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 Import or export the active link. +
-A Import or export all active links. Any -a options are ignored.
-b DSOPoolname Import or export the DSO pool. +
-B Import or export all DSO pools. Any -b options are ignored.
-d DSOMappingname Import or export the DSO mapping. +
-D Import or export all DSO mappings. Any -d options are ignored.
-f formName Import or export the form. +
-F Import or export all forms. Any -f options are ignored.
-g activeLinkGuideName Import or export the active link guide. +
-G Import or export all active link guides. Any -g options are ignored.
-h filterGuideName Import or export the filter guide. +
-H Import or export all filter guides. Any -h options are ignored.
-k packingListName Import or export the packing list. +
-K Import or export all packing lists. Any -k options are ignored.
-l 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. +

-M Import or export all menus. Any -m options are ignored.
-n applicationName Import or export the application. +
-N Import or export all applications. Any -n options are ignored.
-q escalationName Import or export the escalation. +
-Q Import or export all escalations. Any -Q options are ignored.
-t filerName Import or export the filer. +
-T Import or export all filters. Any -t options are ignored.
-z webServiceName Import or export the web service. +
-Z Import or export all web services. Any -z options are ignored.
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.

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

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

Option Description
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 Authenticator — Name of the external authentication string or Windows NT domain. This is related to the Login window's Authentication
-W) 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 export. If multiple
-s) 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


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

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

Importing with a mapping file

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 file

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.
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:
"Bad-Record-Handling: 1"
Data Import command-line utility options

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] [-t multiMatchOption] [-v] [-i]
[-D duplicateIDOption] [-q option] [-c option] [-h option]
[-charset name] [-M fullyQualifiedMappingFileName]
Note
[-m mappingFileName ] [-d directoryWithMappingFile ] Enclose arguments that contain blank spaces or
symbols in double quotation marks.
The following table describes available options.
Option Description
-u User name — Required login parameter that identifies the user account.
Note
Every cross-platform CLI command opens a sep arate 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 — 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 Importing with a mapping file
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.

Importing without a mapping file
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 One of the following paths:
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 (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 option, the command
imports all the data files in the directory specified with the -o option, regardless of file type.
-threads (For multithreaded environments only) Number of threads in the pool.
Note
Make sure that your hardware configuration can handle the number of threads that you enter.
If you do not specify the -threads option, the default of 50 threads is used. If the number of files in the data directory or number of files
you specify in the -filelist option is less than the -threads value or the default value (50), the number of threads used is equal to the
number of files in the data directory or number of files specified in -filelist option.
-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 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
-t Multiple match option — Use when more than one entry matches. Enter a value of 3 to affect the first match, and a 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.
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.
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.
-D Duplicate ID — 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 required field property for non-core fields. The options are 1 (on) and 0 (off) .
-c Truncates character values that are longer than the field length for character fields. The options are 1 (on) and 0 (off) .
-h Suppresses pattern matching for fields. If supplied, the $PATTERN$ field limit is ignored. The options are 1 (on) and 0 (off) .
-charset Specifies the character set used in the data file. The character set name must be supplied as listed in the IANA Charset Registry.
-debug Sets the log level. The log levels are:
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.
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:
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:
-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:
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

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 serverName -u userName -p password -f formName

-o dataFilePath -l logFilePath
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.
com.bmc.arsys.apiext.data.DataImport -x serverName -u userName -p password

-f formName -o dataFilePath -filelist listOfFiles -l 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 userName -p password -m mappingFileName

-d mappingFileDir -l logFile
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 mappingFileDir -l logFile -o dataFilePath -f formName
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 userName -p password -o dataFilePath

-l 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.
com.bmc.arsys.apiext.data.DataImport -x serverName -u userName -p password -f formName

-o dataFilePath -l logFileName
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 logFileName
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:
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.
The default value is 0.
-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.

Option Description
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
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.
-timestamp Use this option to add a time stamp to the folder containing form attachment data. This option has the following values:
1 - Do not add a time stamp.

0 - Add a time stamp.
The default value is 0.
-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:

Option Description
-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.
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.
16.14.7 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:
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.
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.
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:
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.
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.
>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
Password: <password>
1>use ARSystem
2>go
1>select name, nextId from arschema where name = 'ZZZ'
2>go
name nextId
ZZZ 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. 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

You might want to change the values of Request ID fields for your BMC Remedy AR System requests for the
following reasons:

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

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.
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 Description
name
T A table that contains the data in your form. A table named T43 indicates that 43 is the schema ID.
schemaID
T (Oracle only) A table that contains long text and diary data. For example, a table named T43C536870924 indicates that 43 is the schema
schemaID 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
C fieldID compatibility with forms created using BMC Remedy AR System versions prior to 4.5.
H A table that contains the Status History information for your form. A table named H43 indicates that 43 is the schema ID. See the
schemaID Database Reference Using relational databases with BMC Remedy AR System.
B A table that contains a list of all the attachments and related information for each record in your form. A table named B43 indicates that
schemaID 43 is the schema ID. See The attachment tables for a form.
B A table that contains the actual Binary objects for attachment fields in your form. A table named B43C536870924 indicates that 43 is the
schemaID 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
C fieldID 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.
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.
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);

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
*% 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, 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.
16.14.8 Understanding the AR System database

This section contains information about the AR System database:

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.
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.
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.
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.
original column is copied to the new column, and the original column is deleted from 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 <= Adds a varchar column to the main data table; copies the data from the clob column to
4000 bytes. the new column; deletes the old column.
Performs no restructuring.

Administrator Action BMC Remedy AR System Action
Decreases the length of a field from <= 4000 bytes to

less than 4000 bytes.
Increases the length of a field from <= 4000 bytes to > Adds a clob column to the main data table; copies the data from the varchar column to
4000 bytes. the new column; deletes the old column.
Increases the length of a field from > 4000 bytes to Performs no restructuring.
another value also > 4000 bytes.
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.
original column is copied to the new column, and the original column is deleted from the main data table.
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. Performs no restructuring.
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. Performs no restructuring.
a 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 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 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 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.

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.
The currency table 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
Suffix Currency Column Represented
V Decimal value

Suffix Currency Column Represented
C Code associated with decimal value
D 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 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.
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
Oracle
Sybase ASE
Note
For the most accurate information about supported platforms and software, Checking system
Each type of relational database behaves differently with regard to search qualifications, wildcards, and so forth.
The following topics describe these differences.

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

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
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:
3. To set the snapshot isolation level, enter:
4. Restart the AR System server. Optionally, to revert to the original setting, use the following commands in
the same sequence as mentioned:
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:

1.
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.
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)
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 BMC Remedy
Developer Studio.
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.

Table Description
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.
The AR System data dictionary

In this topic:
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

AR System Data Dictionary: Active Links, Filters, and Escalations

AR System Data Dictionary: Container

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.

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.
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 c

BMC Remedy AR Systems 8.1.00 Online Documentation PDF

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

BMC Remedy AR Systems 8.1.00 Online Documentation PDF

Uploaded by

Copyright:

Available Formats

BMC Software Confidential

BMC Remedy Action Request System 8.1

Date: 29-Jan-2014 14:56

BMC Remedy Action Request System 8.1 Page 2 of 4492

7.6 8.1.00 enhancements ______________________________________________________________ 53

BMC Remedy Action Request System 8.1 Page 3 of 4492

9.7.1 BMC Remedy AR System architecture ____________________________________________ 122

BMC Remedy Action Request System 8.1 Page 4 of 4492

10.7.1 Supported languages and character encodings _____________________________________ 374

BMC Remedy Action Request System 8.1 Page 5 of 4492

BMC Remedy Action Request System 8.1 Page 6 of 4492

BMC Remedy Action Request System 8.1 Page 7 of 4492

12.7.9 Configuring the Report Settings page ____________________________________________ 689

BMC Remedy Action Request System 8.1 Page 8 of 4492

BMC Remedy Action Request System 8.1 Page 9 of 4492

BMC Remedy Action Request System 8.1 Page 10 of 4492

13.3.2 Complete the upgrade stages __________________________________________________ 926

BMC Remedy Action Request System 8.1 Page 11 of 4492

14.1.2 Multiplatform issues ________________________________________________________ 1047

BMC Remedy Action Request System 8.1 Page 12 of 4492

14.7.1 Defining BMC Atrium Orchestrator web services ___________________________________ 1190

BMC Remedy Action Request System 8.1 Page 13 of 4492

15.2.2 Running a saved, recent, or defined search _______________________________________ 1297

BMC Remedy Action Request System 8.1 Page 14 of 4492

16.4 Security administration ___________________________________________________________ 1457

BMC Remedy Action Request System 8.1 Page 15 of 4492

16.9.6 Performing searches with FTS _________________________________________________ 1618

BMC Remedy Action Request System 8.1 Page 16 of 4492

BMC Remedy Action Request System 8.1 Page 17 of 4492

BMC Remedy Action Request System 8.1 Page 18 of 4492

17.9.2 URLs for forms and applications _______________________________________________ 2870

BMC Remedy Action Request System 8.1 Page 19 of 4492

BMC Remedy Action Request System 8.1 Page 20 of 4492

BMC Remedy Action Request System 8.1 Page 21 of 4492

18.6.1 Types of functions _________________________________________________________ 3456

BMC Remedy Action Request System 8.1 Page 22 of 4492

BMC Remedy Action Request System 8.1 Page 23 of 4492

BMC Remedy Action Request System 8.1 Page 24 of 4492

BMC Remedy Action Request System 8.1 Page 25 of 4492

21.1 Contacting Customer Support _____________________________________________________ 4489

BMC Remedy Action Request System 8.1 Page 26 of 4492

BMC Remedy Action Request System 8.1 Page 27 of 4492

Service Pack 1: 8.1.01

BMC Remedy Action Request System 8.1 Page 28 of 4492

BMC Remedy Action Request System 8.1 Page 29 of 4492

3 About BMC Remedy AR System

BMC Remedy Action Request System 8.1 Page 30 of 4492

4 About BMC Remedy Encryption Premium

Premium Security provides the following types of encryption:

BMC Remedy Action Request System 8.1 Page 31 of 4492

5 About BMC Remedy Encryption Performance

BMC Remedy Encryption Performance provides the following types of encryption:

BMC Remedy Action Request System 8.1 Page 32 of 4492

6 About BMC Remedy Migrator

BMC Remedy Action Request System 8.1 Page 33 of 4492

To stay informed of changes to this space, place a watch on this page.

Date Title Summary

February 27, 2013 New videos for overlays

7.1 Urgent issues

BMC Remedy Action Request System 8.1 Page 34 of 4492

7.1.2 Issue while logging in to the BMC Remedy IT Service Management

BMC Remedy Action Request System 8.1 Page 35 of 4492

7.2 Documentation updates

7.2.1 Added BIRT report documentation